- Apr 23, 2026
- 4 min read
Formbricks as Code: Surveys as JSON and a Small CLI
By spring I had several sites, each wanting some kind of form: a lead qualifier for consulting calls, an interest survey for an ebook, a sign-up for upcoming talks. I was using Formbricks, an open-source survey tool with a hosted version, and building every form by clicking through its editor.
That works for one form. For five, it stops working:
- No history. What did the qualifier ask last month? The editor doesn’t say.
- No reuse. A good funnel form for one site has to be rebuilt by hand for the next.
- No review. A change goes live the moment you save it.
So I turned surveys into files, and the editor into a command line.
The idea
A survey in Formbricks is a JSON document: a name, a type, a status, a list of questions, a thank-you card. The management API can create, read and update those documents. Put the JSON in a repository, put a small CLI in front of the API, and a survey becomes something you can diff, copy and review.
forms/
main.py the CLI (Python, Typer, httpx)
Makefile the commands I actually type
survey-sample.json a template with the common question types
survey.json the survey I'm working on
.env API key + environment ID (never committed)
The commands
make is the interface, so I never have to remember arguments:
| Command | What it does |
|---|---|
make whoami | checks the API key works |
make surveys | lists every survey as a table |
make get-save SURVEY_ID=… | exports a survey definition to survey.json |
make create | creates a survey from survey.json |
make publish SURVEY_ID=… | makes it live |
make responses-save SURVEY_ID=… | saves responses to responses.json |
make complete SURVEY_ID=… | closes it |
make draft SURVEY_ID=… | takes it back to draft |
Underneath, each one is a single call to the management API
(/api/v1/management/surveys and friends) with the key in an x-api-key
header.
The lifecycle
The most useful rule is that nothing goes live by accident:
make create # always created as a draft
# look at it in the Formbricks UI
make publish SURVEY_ID=<id> # now it's live
make responses-save SURVEY_ID=<id>
make complete SURVEY_ID=<id> # closed when the campaign ends
Creating and publishing are separate steps, on purpose. A draft can be checked in the real UI before anyone sees it.
To build a new survey from a good old one:
make get-save SURVEY_ID=<old> # export
# edit survey.json
make create # a new draft with the same structure
The template (survey-sample.json) covers the question types I use most:
single choice, multiple choice, rating, open text and contact info.
Three gotchas
1. There are two kinds of API key. Formbricks has a client key (it
starts with fbk_), used by a page to submit responses, and a management
key, created from the organisation menu, that can create and edit surveys.
The CLI needs the management key. The client key fails in confusing ways.
2. The public link isn’t in the API response. Exporting a survey doesn’t
give you its share URL. For a hosted link survey it’s
https://app.formbricks.com/s/<survey_id>, and not /surveys/<survey_id>,
which is the dashboard route and doesn’t work for visitors. I check it with
curl -I -L and expect a 200.
3. Exported JSON carries runtime fields. A survey you export comes back
with id, createdAt, updatedAt, _count and its environmentId. Sending
those back on create causes errors or, worse, ties the definition to one
workspace. The CLI strips the runtime fields and injects the environment ID
from .env, so the same JSON works anywhere.
What it changed
- Forms have history. Survey definitions are files, so git shows how a form evolved.
- Good structure gets reused. A funnel form for one site is a copy and a few edits away from the next.
- Changes get reviewed before they go live, because creating and publishing are different commands.
- Responses are files.
responses.jsoncan be read by a script, not just by me in a dashboard.
Takeaways
- If a tool has an API, its configuration can be code.
- Separate create from publish. Drafts are free; mistakes in production aren’t.
- Use the right key: management for building, client for submitting.
- Strip runtime fields so a definition isn’t tied to one workspace.