• 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:

CommandWhat it does
make whoamichecks the API key works
make surveyslists every survey as a table
make get-save SURVEY_ID=…exports a survey definition to survey.json
make createcreates 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.json can 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.