{"openapi":"3.1.0","info":{"title":"Baxly API","version":"1.1.0","summary":"Create, publish and read Baxly surveys from your own tools or AI assistant.","description":"Account-scoped. Authenticate with an API key from the Baxly API page (`Authorization: Bearer bx_live_...`) or with sign-in with Baxly (OAuth 2.1 with PKCE; discovery at /.well-known/oauth-authorization-server). Business plan. Surveys are written in the published definition format (baxly-survey/1.0): rule book https://baxly.brc.com/survey-definition/rulebook.md, JSON Schema https://baxly.brc.com/survey-definition/schema.json. An AI assistant can also connect directly through the MCP connector at https://api.brc.com/se/mcp (see https://baxly.brc.com/survey-definition). Rate limit: 300 requests per 5 minutes per key.","contact":{"name":"Baxter Research Group","email":"baxly@brc.com","url":"https://baxly.brc.com"}},"servers":[{"url":"https://api.brc.com/se/api/v1"}],"security":[{"apiKey":[]},{"oauth2":["surveys"]}],"tags":[{"name":"Surveys"},{"name":"Definitions"},{"name":"Results"},{"name":"Lists"}],"paths":{"/surveys":{"get":{"tags":["Surveys"],"operationId":"listSurveys","summary":"List the surveys on this account","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"surveys":{"type":"array","items":{"$ref":"#/components/schemas/SurveySummary"}}}}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Definitions"],"operationId":"createSurvey","summary":"Create a draft survey from a definition","description":"Validates the definition exactly as validate does; on any error nothing is created and the report is returned with status 400. On success the survey exists as a draft (editable in the builder); call publish to make it live.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefinitionBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"surveyUuid":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","const":"draft"},"outline":{"$ref":"#/components/schemas/Outline"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}}}}}}},"400":{"description":"The definition has errors; see report","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"report":{"$ref":"#/components/schemas/ValidationReport"}}}]}}}}}}},"/surveys/validate":{"post":{"tags":["Definitions"],"operationId":"validateSurvey","summary":"Validate a definition without creating anything","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefinitionBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationReport"}}}}}}},"/surveys/{uuid}":{"get":{"tags":["Surveys"],"operationId":"getSurvey","summary":"Survey structure (pages, questions, choices)","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The survey uuid (from list surveys or create)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/surveys/{uuid}/definition":{"get":{"tags":["Definitions"],"operationId":"exportSurveyDefinition","summary":"Export the survey as a baxly-survey/1.0 definition","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The survey uuid (from list surveys or create)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"surveyUuid":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"definition":{"type":"object","description":"A baxly-survey/1.0 document; see the JSON Schema."},"notes":{"type":"array","items":{"type":"string"},"description":"Anything the format could not carry."}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/surveys/{uuid}/publish":{"post":{"tags":["Surveys"],"operationId":"publishSurvey","summary":"Publish a draft (draft to active)","description":"Same gate as the builder: at least one question, plan limits on active surveys, question types and AI follow-ups.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The survey uuid (from list surveys or create)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"surveyUuid":{"type":"string"},"status":{"type":"string"},"alreadyPublished":{"type":"boolean"}}}}}},"400":{"description":"Cannot publish; the message says why","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/surveys/{uuid}/status":{"post":{"tags":["Surveys"],"operationId":"setSurveyStatus","summary":"Pause, resume or close a published survey","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The survey uuid (from list surveys or create)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["paused","active","closed"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"surveyUuid":{"type":"string"},"status":{"type":"string"},"previous":{"type":"string"},"unchanged":{"type":"boolean"}}}}}},"400":{"description":"Not allowed from the current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/surveys/{uuid}/links":{"get":{"tags":["Surveys"],"operationId":"getSurveyLinks","summary":"The live respondent link and a preview link","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The survey uuid (from list surveys or create)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"surveyUuid":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"link":{"type":"string","format":"uri"},"previewLink":{"type":"string","format":"uri"},"note":{"type":"string"}}}}}}}}},"/surveys/{uuid}/results":{"get":{"tags":["Results"],"operationId":"getSurveyResults","summary":"Aggregated results (the Results tab numbers)","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The survey uuid (from list surveys or create)."},{"name":"filter","in":"query","schema":{"type":"string"},"description":"A segment filter as the Results view encodes it."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/surveys/{uuid}/responses":{"get":{"tags":["Results"],"operationId":"getSurveyResponses","summary":"Responses with answers, paginated","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The survey uuid (from list surveys or create)."},{"name":"status","in":"query","schema":{"type":"string","enum":["complete","screened","all"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"after","in":"query","schema":{"type":"integer"},"description":"Cursor: the last responseId seen."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/surveys/{uuid}/lists":{"get":{"tags":["Lists"],"operationId":"getSurveyLists","summary":"The survey lists and their items","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The survey uuid (from list surveys or create)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/surveys/{uuid}/lists/{name}":{"put":{"tags":["Lists"],"operationId":"replaceSurveyList","summary":"Create or replace a list by name","description":"Blocked with 409 on a live survey unless ?force=1 (changing items mid-field splits bases).","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The survey uuid (from list surveys or create)."},{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"force","in":"query","schema":{"type":"string","enum":["1"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"columns":{"type":"array","items":{"type":"string"}},"items":{"type":"array","items":{"type":"object","additionalProperties":{"type":"string"}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"Survey is live; repeat with ?force=1","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"bx_live_ key from the Baxly API page, or an OAuth access token (see oauth2)."},"oauth2":{"type":"oauth2","description":"Sign in with Baxly (PKCE, public clients, dynamic registration at /se/oauth/register).","flows":{"authorizationCode":{"authorizationUrl":"https://api.brc.com/se/oauth/authorize","tokenUrl":"https://api.brc.com/se/oauth/token","refreshUrl":"https://api.brc.com/se/oauth/token","scopes":{"surveys":"Create, publish and read surveys on the account"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}}},"Issue":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string","description":"JSON path into the definition, e.g. $.pages[2].questions[0].choices"},"message":{"type":"string"}}},"Outline":{"type":"object","description":"A client-facing summary of what the definition builds: pages, questions, lists, features."},"ValidationReport":{"type":"object","properties":{"format":{"type":"string"},"ok":{"type":"boolean"},"summary":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}},"outline":{"$ref":"#/components/schemas/Outline"}}},"DefinitionBody":{"type":"object","required":["definition"],"properties":{"definition":{"description":"The baxly-survey/1.0 document (object, or a JSON string). Schema: https://baxly.brc.com/survey-definition/schema.json","type":["object","string"]}}},"SurveySummary":{"type":"object","properties":{"surveyUuid":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","closed"]},"createdDate":{"type":"string"},"openedDate":{"type":["string","null"]},"closedDate":{"type":["string","null"]},"completes":{"type":"integer"}}}}}}