For AI assistants and developers
Let your AI write the whole survey. Baxly builds it.
The Baxly survey definition is a published JSON format that describes a complete survey: pages, every question type, choices, lists, loops, show and hide logic, screen-outs, quotas, A/B variants, variables, themes, incentives and AI follow-ups. Any assistant that can read a web page can write one. You upload it, Baxly checks it and shows you exactly what it contains, and one click builds it as a draft you can still edit.
Why use your own AI instead of the builder?
Because your assistant already knows your business. It has your product names, your customer segments, the questions you asked last year and the wording your team argued about. It can draft a survey that fits all of that in one go, with the screeners, loops, quotas and logic already in place, and Baxly does the checking and the building. The builder is still there for the final edits.
How it works
Paste the prompt
Give your assistant the prompt below and describe the survey you want in plain words. It reads the rule book itself.
Upload the file
Sign in to Baxly and paste or upload the JSON on the import page. Baxly validates it and lists every problem with a plain fix. Hand that list back to the AI if there is anything to correct.
Create and edit
When the check is clean, create the survey. It opens in the builder as an ordinary draft: change anything, preview it, then publish when you are ready.
The prompt
Read the Baxly survey definition rule book at https://baxly.brc.com/survey-definition/rulebook.md and follow it exactly. Then write a complete survey definition file (format baxly-survey/1.0) for the survey described below. Output only the JSON file. Put anything you had to guess in the top-level "notes" field. Survey to write:
Then go to Surveys, Build from a definition file in your Baxly account.
Or connect your AI directly, no file at all
Baxly is also an MCP connector. Claude, ChatGPT, Gemini, Cursor and any other assistant that takes a remote connector can read the rule book, write the survey, check it, create it in your account, publish it and hand you the link, all in one conversation. The assistant uses nine tools: get_rulebook, list_surveys, validate_survey, create_survey, get_survey_definition, publish_survey, set_survey_status, get_survey_links and get_survey_results. Surveys it creates are ordinary drafts you can still edit in the builder, and publishing goes through the same checks as the Publish button.
Set it up
Add a connector in your assistant with this address. It will send you to Baxly to sign in and click Allow, and that is it (Business plan). Tools that cannot do a sign-in can use an API key from the API page instead.
https://api.brc.com/se/mcp
Then just ask
“Build a 5-minute concept test for our three new subscription tiers with an A/B split, check it, create it in Baxly and give me the preview link.” The assistant reads the rule book, writes the definition, fixes whatever the validator flags, creates the draft and reports back. Nothing goes live until you ask for publish.
Developers: the same operations are plain REST, described at openapi.json.
The files
Rule book (rulebook.md)
The complete specification, written for an AI to follow. Every key, every question type and its settings, logic, loops, limits and error codes.
JSON Schema (schema.json)
Draft 2020-12 schema generated from the validator, for editors and tools that check shapes and ranges before upload.
Example: customer satisfaction
Core question types, a screen-out, show and hide logic, an AI follow-up and a quota.
Example: concept test with an A/B experiment
Two variants that see different pages, variables with rules, a matrix, a ranking, a theme, a completion form and a prize drawing.
Example: readership study
Lists, a page that repeats once per article with an image beside it, a follow-up loop over the reader’s picks, and a MaxDiff.
Your file is treated as untrusted. Here is what that means.
Every definition is handled the same way, whoever wrote it. Text is run through the same sanitizer the Baxly builder uses, every setting is checked against an allowlist for its question type, everything is referenced by the keys you choose rather than by ids, sizes are capped, and instructions aimed at the reviewer have no effect. Nothing in the file is ever executed. The practical consequence is that there is always a safe, supported way to get the result you want, and the table below is the map.
| You want | Do this | Not this |
|---|---|---|
| Emphasis, headings, lists | The allowed HTML tags (p, b, i, h2, ul, li, table and so on) | Markdown, script, style, iframe, form |
| A link | <a href="https://..."> with http, https, mailto or tel | javascript: links, click handlers |
| An image | An https URL in an img tag, in side_media, or on an image_choice | data: URLs, base64, SVG, file paths |
| Colors and fonts | survey.theme, or simple inline styles (color, font-size, margin) | position, z-index, transforms, url() in CSS |
| Personalised text | Merge tags: {{var.Name}} and {{item.Column}} inside a loop | Template syntax from other tools |
| Refer to a question or choice | Its key, or a choice's exact text | Ids, uuids, positions |
| Tell the person something | The notes field at the top of the file | Hidden text or instructions inside questions |
The validator reports every error and warning in one pass, each with a code, the JSON path and a plain message, so an assistant can fix the file in a single round.
Question types
Core, on every plan
select_onePick onemulti_selectPick severaldropdownPick one from a listyes_noYes or noopen_textText boxemail_captureEmail addressnumberA numberdateA datescaleNumbered scalenps0 to 10 recommendstar_ratingStarsnoteText only
Advanced, on Pro and Business
matrixGrid of rows and columnsrankingDrag to rankconstant_sumDistribute pointspercentage_sumPercentages to 100image_choicePick from picturesheatmapClick on an imagesliderSlidercontact_formName, email and morefile_uploadUpload a fileai_conversationAI interviewmaxdiffBest and worst trade-offsbestofAwards-style category picks
Beyond the questions themselves, a definition can carry lists and loops (ask the same questions once per product, article or ad), show and hide logic, screen-out rules with their own thank-you message, quotas, A/B variants, variables with rules, a cover page with consent, a theme, a completion form, an incentive and AI follow-ups. The rule book has the details.