{"openapi":"3.1.0","info":{"title":"Voicepanel API","version":"1.1.0","description":"API for creating and managing voice-based user research studies, distributing them to participants, and retrieving responses.\n\n## Authentication\n\nAll API requests require a Bearer token passed in the `Authorization` header.\n\n### Getting an API key\n\n1. Sign in to the [Voicepanel dashboard](https://app.voicepanel.co)\n2. Go to **Settings → API Tokens**\n3. Enter a name for the token (e.g. \"Production\" or \"CI/CD\") and click **Create**\n4. Copy the token immediately — it is only shown once\n\n### Making requests\n\nInclude your token in the `Authorization` header of every request:\n\n```bash\ncurl https://app.voicepanel.co/api/v1/studies \\\n  -H \"Authorization: Bearer vpt_your_token_here\" \\\n  -H \"Content-Type: application/json\"\n```\n\nIf the token is missing or invalid, the API returns a `401 Unauthorized` response.\n\n## Getting Started\n\nThe Voicepanel API allows you to programmatically create voice-based research studies, distribute them to participants, and retrieve responses.\n\nAfter getting your API key, the typical flow is:\n\n1. **Create a study** — Use [POST /api/v1/studies](#tag/studies/post-api-v1-studies) to create a study and [PATCH /api/v1/studies/{study_id}](#tag/studies/patch-api-v1-studies-study_id) to configure your interview guide with sections, questions, and recording settings. Use [GET /api/v1/studies](#tag/studies/get-api-v1-studies) to list your studies or [GET /api/v1/studies/{study_id}](#tag/studies/get-api-v1-studies-study_id) to retrieve a specific one.\n2. **Set up distribution** — Use [POST /api/v1/distributions](#tag/distributions/post-api-v1-distributions) to define how you'd like to target the study — via a shareable link, panel provider, embedded widget, or other method. Use [GET /api/v1/distributions](#tag/distributions/get-api-v1-distributions) to list distributions or [GET /api/v1/distributions/{distribution_id}](#tag/distributions/get-api-v1-distributions-distribution_id) to retrieve a specific one.\n3. **Publish** — Use [POST /api/v1/distributions/{distribution_id}/publish](#tag/distributions/post-api-v1-distributions-distribution_id-publish) to make the distribution live and start collecting responses.\n4. **Fetch responses** — Use [GET /api/v1/responses](#tag/responses/get-api-v1-responses) to retrieve responses for your study, with filtering by distribution, status, date range, and more.\n\n## Study plan reference\n\nThe `plan` field describes the whole interview: sections, question types, assets, recording modes, and logic. The [Study plan reference](https://www.voicepanel.com/docs/study-reference) documents every block with a JSON example, plus complete plans for common research methods.\n"},"servers":[{"url":"https://app.voicepanel.co","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/studies":{"get":{"summary":"List studies","description":"Retrieve all studies accessible to the authenticated account. Optionally filter by account ID.","tags":["Studies"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string"},"description":"Filter studies by account ID"}]},"post":{"summary":"Create a study","description":"Create a new research study. Provide an account_id and optionally a plan configuration with sections, steps, and recording settings.","tags":["Studies"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"string","description":"ID of the account to create the study under"},"display_name":{"description":"Public-facing study name shown to participants","anyOf":[{"type":"string"},{"type":"null"}]},"internal_name":{"description":"Internal name for organization purposes","anyOf":[{"type":"string"},{"type":"null"}]},"objective":{"description":"Research objective for the study","anyOf":[{"type":"string"},{"type":"null"}]},"context":{"description":"Brand or product context for the AI interviewer","anyOf":[{"type":"string"},{"type":"null"}]},"plan":{"description":"Study plan with sections, steps, and recording config. Every block, with examples: https://www.voicepanel.com/docs/study-reference","anyOf":[{"type":"object","properties":{"version":{"type":"string"},"sections":{"type":"array","items":{"type":"object","properties":{"intro":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}]},"steps":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"question":{"type":"string"},"type":{"type":"string","const":"task"},"task_type":{"type":"string","enum":["visit_website","download_app","open_app","watch_video","generic_instruction"]},"expected_duration_seconds":{"type":"number"}},"required":["question","type","task_type"],"additionalProperties":false},{"type":"object","properties":{"question":{"type":"string"},"type":{"type":"string","const":"long_question"},"probing_areas":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}]},"probing_type":{"default":"light","type":"string","enum":["none","light","custom"]},"response_format":{"default":"audio","type":"string","enum":["audio","audio_only","chat_only","chat"]}},"required":["question","type","probing_areas","probing_type","response_format"],"additionalProperties":false},{"type":"object","properties":{"question":{"type":"string"},"type":{"type":"string","const":"single_select"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"anchor":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]},"exclusive":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["value","anchor","exclusive"],"additionalProperties":false}},"shuffle_options":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]},"vertically_align_choices":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["question","type","options","shuffle_options","vertically_align_choices"],"additionalProperties":false},{"type":"object","properties":{"question":{"type":"string"},"type":{"type":"string","const":"multi_select"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"anchor":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]},"exclusive":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["value","anchor","exclusive"],"additionalProperties":false}},"shuffle_options":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]},"vertically_align_choices":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["question","type","options","shuffle_options","vertically_align_choices"],"additionalProperties":false},{"type":"object","properties":{"question":{"type":"string"},"type":{"type":"string","const":"rating_scale"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"anchor":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]},"exclusive":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["value","anchor","exclusive"],"additionalProperties":false}},"lowest_rating_label":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}]},"highest_rating_label":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["question","type","options","lowest_rating_label","highest_rating_label"],"additionalProperties":false},{"type":"object","properties":{"question":{"type":"string"},"type":{"type":"string","const":"ranking"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"anchor":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]},"exclusive":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["value","anchor","exclusive"],"additionalProperties":false}},"shuffle_options":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["question","type","options","shuffle_options"],"additionalProperties":false},{"type":"object","properties":{"question":{"type":"string"},"type":{"type":"string","const":"conversation"},"time_limit_seconds":{"type":"number"},"conversation_mode":{"type":"string","enum":["no-guide","guide"]},"conversation_guide":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}]},"response_format":{"default":"audio","type":"string","enum":["audio","audio_only","chat_only","chat"]}},"required":["question","type","time_limit_seconds","conversation_mode","conversation_guide","response_format"],"additionalProperties":false}]}},"stimulus":{"anyOf":[{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"text"},"content":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}]}},"placement":{"anyOf":[{"type":"string","enum":["throughout","at-start"]},{"type":"null"}]},"displaySeconds":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["website","mobile_app","audio","video","youtube","prototype","image","html","offline","none"]},"url":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}]}},"urlPreview":{"anyOf":[{"type":"object","properties":{"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"favicon":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"botProtected":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["image","title","description"],"additionalProperties":false},{"type":"null"}]},"placement":{"anyOf":[{"type":"string","enum":["throughout","at-start"]},{"type":"null"}]},"displaySeconds":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"sizing":{"anyOf":[{"type":"string","enum":["fit","fit-width","fit-height"]},{"type":"null"}]}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"group"},"stimuli":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"text"},"content":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}]}},"placement":{"anyOf":[{"type":"string","enum":["throughout","at-start"]},{"type":"null"}]},"displaySeconds":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["website","mobile_app","audio","video","youtube","prototype","image","html","offline","none"]},"url":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}]}},"urlPreview":{"anyOf":[{"type":"object","properties":{"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"favicon":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"botProtected":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["image","title","description"],"additionalProperties":false},{"type":"null"}]},"placement":{"anyOf":[{"type":"string","enum":["throughout","at-start"]},{"type":"null"}]},"displaySeconds":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"sizing":{"anyOf":[{"type":"string","enum":["fit","fit-width","fit-height"]},{"type":"null"}]}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"side_by_side"},"stimuli":{"maxItems":4,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["image","html"]},"url":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}]}},"urlPreview":{"anyOf":[{"type":"object","properties":{"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"favicon":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"botProtected":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["image","title","description"],"additionalProperties":false},{"type":"null"}]},"placement":{"anyOf":[{"type":"string","enum":["throughout","at-start"]},{"type":"null"}]},"displaySeconds":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"sizing":{"anyOf":[{"type":"string","enum":["fit","fit-width","fit-height"]},{"type":"null"}]}},"required":["type","url"],"additionalProperties":false}},"displaySeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"sizing":{"anyOf":[{"type":"string","enum":["fit","fit-width","fit-height"]},{"type":"null"}]}},"required":["type","stimuli"],"additionalProperties":false}]}},"showCount":{"type":"number"},"displaySeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"sizing":{"anyOf":[{"type":"string","enum":["fit","fit-width","fit-height"]},{"type":"null"}]}},"required":["type","stimuli","showCount"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"side_by_side"},"stimuli":{"maxItems":4,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["image","html"]},"url":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}]}},"urlPreview":{"anyOf":[{"type":"object","properties":{"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"favicon":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"botProtected":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["image","title","description"],"additionalProperties":false},{"type":"null"}]},"placement":{"anyOf":[{"type":"string","enum":["throughout","at-start"]},{"type":"null"}]},"displaySeconds":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"sizing":{"anyOf":[{"type":"string","enum":["fit","fit-width","fit-height"]},{"type":"null"}]}},"required":["type","url"],"additionalProperties":false}},"displaySeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"sizing":{"anyOf":[{"type":"string","enum":["fit","fit-width","fit-height"]},{"type":"null"}]}},"required":["type","stimuli"],"additionalProperties":false}]},{"type":"null"}]},"recording":{"anyOf":[{"type":"object","properties":{"audio":{"default":false,"type":"boolean"},"video":{"default":false,"type":"boolean"},"screen":{"default":false,"type":"boolean"},"mobile_screen":{"default":false,"type":"boolean"}},"required":["audio","video","screen","mobile_screen"],"additionalProperties":false},{"type":"null"}]},"conditionalBranch":{"anyOf":[{"anyOf":[{"type":"object","properties":{"sourceType":{"type":"string","const":"segment"},"segmentationKey":{"type":"string"},"triggerValues":{"type":"array","items":{"type":"string"}}},"required":["sourceType","segmentationKey","triggerValues"],"additionalProperties":false},{"type":"object","properties":{"sourceType":{"type":"string","const":"task"},"sourceSectionIndex":{"type":"number"},"sourceStepIndex":{"type":"number"},"triggerValues":{"type":"array","items":{"type":"string","enum":["completed","not_completed"]}}},"required":["sourceType","sourceSectionIndex","sourceStepIndex","triggerValues"],"additionalProperties":false},{"type":"object","properties":{"sourceType":{"type":"string","const":"question"},"sourceSectionIndex":{"type":"number"},"sourceStepIndex":{"type":"number"},"triggerValues":{"type":"array","items":{"type":"string"}}},"required":["sourceSectionIndex","sourceStepIndex","triggerValues"],"additionalProperties":false}]},{"type":"null"}]}},"required":["intro","steps"],"additionalProperties":false}},"randomizations":{"type":"array","items":{"type":"object","properties":{"sectionIndices":{"type":"array","items":{"type":"number"}}},"required":["sectionIndices"],"additionalProperties":false}},"flagged_content":{"type":"boolean"},"device":{"type":"string","enum":["any","desktop","mobile","ios","android"]}},"required":["version","sections","randomizations"],"additionalProperties":false},{"type":"null"}]},"brand_logo_url":{"description":"URL of brand logo shown during the interview","anyOf":[{"type":"string"},{"type":"null"}]},"show_welcome_page":{"description":"Whether to show a welcome page before starting","type":"boolean"},"target_length_min":{"description":"Target interview length in minutes","anyOf":[{"type":"number"},{"type":"null"}]},"welcome_text":{"description":"Custom welcome page text","anyOf":[{"type":"string"},{"type":"null"}]},"written_in_language":{"description":"Language code the study is written in","type":"string"},"is_archived":{"description":"Whether the study is archived","type":"boolean"},"brand_words":{"description":"Brand-related keywords for AI interviewer context","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"enable_tts_default":{"description":"Whether text-to-speech is enabled by default","type":"boolean"},"tts_voice_id":{"description":"Voice ID for text-to-speech","anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"description":"Tags for organizing studies","type":"array","items":{"type":"string"}}},"required":["account_id"],"additionalProperties":false}}}}}},"/api/v1/studies/{study_id}":{"get":{"summary":"Get a study","description":"Retrieve a single study by its ID, including its full plan configuration.","tags":["Studies"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"parameters":[{"name":"study_id","in":"path","required":true,"description":"The study ID","schema":{"type":"string"}}]},"patch":{"summary":"Update a study","description":"Update an existing study's configuration. Include the study ID in the request body. Any provided fields will be updated; omitted fields remain unchanged.","tags":["Studies"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"parameters":[{"name":"study_id","in":"path","required":true,"description":"The study ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID of the study to update"},"display_name":{"description":"Public-facing study name","anyOf":[{"type":"string"},{"type":"null"}]},"internal_name":{"description":"Internal name","anyOf":[{"type":"string"},{"type":"null"}]},"objective":{"description":"Research objective","anyOf":[{"type":"string"},{"type":"null"}]},"context":{"description":"Brand or product context","anyOf":[{"type":"string"},{"type":"null"}]},"plan":{"description":"Study plan configuration. Every block, with examples: https://www.voicepanel.com/docs/study-reference","anyOf":[{"type":"object","properties":{"version":{"type":"string"},"sections":{"type":"array","items":{"type":"object","properties":{"intro":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}]},"steps":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"question":{"type":"string"},"type":{"type":"string","const":"task"},"task_type":{"type":"string","enum":["visit_website","download_app","open_app","watch_video","generic_instruction"]},"expected_duration_seconds":{"type":"number"}},"required":["question","type","task_type"],"additionalProperties":false},{"type":"object","properties":{"question":{"type":"string"},"type":{"type":"string","const":"long_question"},"probing_areas":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}]},"probing_type":{"default":"light","type":"string","enum":["none","light","custom"]},"response_format":{"default":"audio","type":"string","enum":["audio","audio_only","chat_only","chat"]}},"required":["question","type","probing_areas","probing_type","response_format"],"additionalProperties":false},{"type":"object","properties":{"question":{"type":"string"},"type":{"type":"string","const":"single_select"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"anchor":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]},"exclusive":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["value","anchor","exclusive"],"additionalProperties":false}},"shuffle_options":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]},"vertically_align_choices":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["question","type","options","shuffle_options","vertically_align_choices"],"additionalProperties":false},{"type":"object","properties":{"question":{"type":"string"},"type":{"type":"string","const":"multi_select"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"anchor":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]},"exclusive":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["value","anchor","exclusive"],"additionalProperties":false}},"shuffle_options":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]},"vertically_align_choices":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["question","type","options","shuffle_options","vertically_align_choices"],"additionalProperties":false},{"type":"object","properties":{"question":{"type":"string"},"type":{"type":"string","const":"rating_scale"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"anchor":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]},"exclusive":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["value","anchor","exclusive"],"additionalProperties":false}},"lowest_rating_label":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}]},"highest_rating_label":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["question","type","options","lowest_rating_label","highest_rating_label"],"additionalProperties":false},{"type":"object","properties":{"question":{"type":"string"},"type":{"type":"string","const":"ranking"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"anchor":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]},"exclusive":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["value","anchor","exclusive"],"additionalProperties":false}},"shuffle_options":{"default":null,"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["question","type","options","shuffle_options"],"additionalProperties":false},{"type":"object","properties":{"question":{"type":"string"},"type":{"type":"string","const":"conversation"},"time_limit_seconds":{"type":"number"},"conversation_mode":{"type":"string","enum":["no-guide","guide"]},"conversation_guide":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}]},"response_format":{"default":"audio","type":"string","enum":["audio","audio_only","chat_only","chat"]}},"required":["question","type","time_limit_seconds","conversation_mode","conversation_guide","response_format"],"additionalProperties":false}]}},"stimulus":{"anyOf":[{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"text"},"content":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}]}},"placement":{"anyOf":[{"type":"string","enum":["throughout","at-start"]},{"type":"null"}]},"displaySeconds":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["website","mobile_app","audio","video","youtube","prototype","image","html","offline","none"]},"url":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}]}},"urlPreview":{"anyOf":[{"type":"object","properties":{"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"favicon":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"botProtected":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["image","title","description"],"additionalProperties":false},{"type":"null"}]},"placement":{"anyOf":[{"type":"string","enum":["throughout","at-start"]},{"type":"null"}]},"displaySeconds":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"sizing":{"anyOf":[{"type":"string","enum":["fit","fit-width","fit-height"]},{"type":"null"}]}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"group"},"stimuli":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"text"},"content":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}]}},"placement":{"anyOf":[{"type":"string","enum":["throughout","at-start"]},{"type":"null"}]},"displaySeconds":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["website","mobile_app","audio","video","youtube","prototype","image","html","offline","none"]},"url":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}]}},"urlPreview":{"anyOf":[{"type":"object","properties":{"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"favicon":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"botProtected":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["image","title","description"],"additionalProperties":false},{"type":"null"}]},"placement":{"anyOf":[{"type":"string","enum":["throughout","at-start"]},{"type":"null"}]},"displaySeconds":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"sizing":{"anyOf":[{"type":"string","enum":["fit","fit-width","fit-height"]},{"type":"null"}]}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"side_by_side"},"stimuli":{"maxItems":4,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["image","html"]},"url":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}]}},"urlPreview":{"anyOf":[{"type":"object","properties":{"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"favicon":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"botProtected":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["image","title","description"],"additionalProperties":false},{"type":"null"}]},"placement":{"anyOf":[{"type":"string","enum":["throughout","at-start"]},{"type":"null"}]},"displaySeconds":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"sizing":{"anyOf":[{"type":"string","enum":["fit","fit-width","fit-height"]},{"type":"null"}]}},"required":["type","url"],"additionalProperties":false}},"displaySeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"sizing":{"anyOf":[{"type":"string","enum":["fit","fit-width","fit-height"]},{"type":"null"}]}},"required":["type","stimuli"],"additionalProperties":false}]}},"showCount":{"type":"number"},"displaySeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"sizing":{"anyOf":[{"type":"string","enum":["fit","fit-width","fit-height"]},{"type":"null"}]}},"required":["type","stimuli","showCount"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"side_by_side"},"stimuli":{"maxItems":4,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["image","html"]},"url":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}]}},"urlPreview":{"anyOf":[{"type":"object","properties":{"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"favicon":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"botProtected":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["image","title","description"],"additionalProperties":false},{"type":"null"}]},"placement":{"anyOf":[{"type":"string","enum":["throughout","at-start"]},{"type":"null"}]},"displaySeconds":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"sizing":{"anyOf":[{"type":"string","enum":["fit","fit-width","fit-height"]},{"type":"null"}]}},"required":["type","url"],"additionalProperties":false}},"displaySeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"sizing":{"anyOf":[{"type":"string","enum":["fit","fit-width","fit-height"]},{"type":"null"}]}},"required":["type","stimuli"],"additionalProperties":false}]},{"type":"null"}]},"recording":{"anyOf":[{"type":"object","properties":{"audio":{"default":false,"type":"boolean"},"video":{"default":false,"type":"boolean"},"screen":{"default":false,"type":"boolean"},"mobile_screen":{"default":false,"type":"boolean"}},"required":["audio","video","screen","mobile_screen"],"additionalProperties":false},{"type":"null"}]},"conditionalBranch":{"anyOf":[{"anyOf":[{"type":"object","properties":{"sourceType":{"type":"string","const":"segment"},"segmentationKey":{"type":"string"},"triggerValues":{"type":"array","items":{"type":"string"}}},"required":["sourceType","segmentationKey","triggerValues"],"additionalProperties":false},{"type":"object","properties":{"sourceType":{"type":"string","const":"task"},"sourceSectionIndex":{"type":"number"},"sourceStepIndex":{"type":"number"},"triggerValues":{"type":"array","items":{"type":"string","enum":["completed","not_completed"]}}},"required":["sourceType","sourceSectionIndex","sourceStepIndex","triggerValues"],"additionalProperties":false},{"type":"object","properties":{"sourceType":{"type":"string","const":"question"},"sourceSectionIndex":{"type":"number"},"sourceStepIndex":{"type":"number"},"triggerValues":{"type":"array","items":{"type":"string"}}},"required":["sourceSectionIndex","sourceStepIndex","triggerValues"],"additionalProperties":false}]},{"type":"null"}]}},"required":["intro","steps"],"additionalProperties":false}},"randomizations":{"type":"array","items":{"type":"object","properties":{"sectionIndices":{"type":"array","items":{"type":"number"}}},"required":["sectionIndices"],"additionalProperties":false}},"flagged_content":{"type":"boolean"},"device":{"type":"string","enum":["any","desktop","mobile","ios","android"]}},"required":["version","sections","randomizations"],"additionalProperties":false},{"type":"null"}]},"brand_logo_url":{"description":"URL of brand logo","anyOf":[{"type":"string"},{"type":"null"}]},"show_welcome_page":{"description":"Show welcome page","type":"boolean"},"target_length_min":{"description":"Target length in minutes","anyOf":[{"type":"number"},{"type":"null"}]},"welcome_text":{"description":"Welcome page text","anyOf":[{"type":"string"},{"type":"null"}]},"written_in_language":{"description":"Language code","type":"string"},"is_archived":{"description":"Whether archived","type":"boolean"},"brand_words":{"description":"Brand-related keywords","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"enable_tts_default":{"description":"Whether text-to-speech is enabled by default","type":"boolean"},"tts_voice_id":{"description":"Voice ID for TTS","anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"description":"Tags","type":"array","items":{"type":"string"}}},"required":["id"],"additionalProperties":false}}}}}},"/api/v1/distributions":{"get":{"summary":"List distributions","description":"Retrieve all distributions accessible to the authenticated account. Optionally filter by study ID or distribution type.","tags":["Distributions"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"parameters":[{"name":"studyId","in":"query","required":false,"schema":{"type":"string"},"description":"Filter distributions by study ID"},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["link","service","email","website","app","panel","simulation"]},"description":"Filter by distribution type"}]},"post":{"summary":"Create a distribution","description":"Create a new distribution for a study. A distribution defines how participants access the study — via a shareable link, a panel provider, embedded widget, or other method.","tags":["Distributions"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"study_id":{"type":"string","description":"ID of the study this distribution belongs to"},"name":{"description":"Name of the distribution","anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string","enum":["link","service","email","website","app","panel","simulation"],"description":"How the study is distributed to participants"},"distribution_provider":{"anyOf":[{"type":"string","enum":["respondent","user_interviews","prolific","terac"],"description":"Third-party panel provider"},{"type":"null"}]},"config":{"description":"Provider-specific configuration","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"incentive":{"description":"Incentive configuration for link distributions","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},{"type":"null"}]},"quota_limit":{"description":"Maximum number of responses","anyOf":[{"type":"number"},{"type":"null"}]},"quota_frequency":{"description":"How often the quota resets","type":"string","enum":["lifetime","monthly","weekly","daily"]},"segment_quotas":{"description":"Per-segment subquotas within the overall quota","anyOf":[{"$ref":"#/$defs/__schema0"},{"type":"null"}]},"screener_questions":{"description":"Screener questions for qualifying participants","type":"array","items":{"$ref":"#/$defs/__schema0"}},"targeting_condition":{"description":"Targeting rules for who is eligible","anyOf":[{"$ref":"#/$defs/__schema0"},{"type":"null"}]},"default_response_language":{"description":"Default language for responses","anyOf":[{"type":"string"},{"type":"null"}]},"collect_email":{"description":"Whether to collect participant email","type":"boolean"},"screen_email":{"description":"Whether to screen participants against an email list","type":"boolean"},"email_list_id":{"description":"Email list used to screen or invite participants","anyOf":[{"type":"string"},{"type":"null"}]},"automatic_invites":{"description":"Whether participants are invited automatically","type":"boolean"},"key":{"description":"Snippet key used to trigger an intercept distribution","anyOf":[{"type":"string"},{"type":"null"}]},"traffic_threshold":{"description":"Share of eligible traffic shown the study, out of 1,000,000","anyOf":[{"type":"number"},{"type":"null"}]},"complete_redirect_url":{"description":"URL to redirect to after completion","anyOf":[{"type":"string"},{"type":"null"}]},"screen_out_redirect_url":{"description":"URL to redirect screened-out participants","anyOf":[{"type":"string"},{"type":"null"}]},"quota_full_redirect_url":{"description":"URL to redirect when quota is full","anyOf":[{"type":"string"},{"type":"null"}]},"quality_terminate_redirect_url":{"description":"URL to redirect participants terminated for quality","anyOf":[{"type":"string"},{"type":"null"}]},"description":{"description":"Description of the distribution","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["study_id"],"additionalProperties":false,"$defs":{"__schema0":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema0"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}}]}}}}}}}},"/api/v1/distributions/{distribution_id}":{"get":{"summary":"Get a distribution","description":"Retrieve a single distribution by its ID, including its full configuration.","tags":["Distributions"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"parameters":[{"name":"distribution_id","in":"path","required":true,"description":"The distribution ID","schema":{"type":"string"}}]},"patch":{"summary":"Update a distribution","description":"Update an existing distribution's configuration. The study_id must be included in the request body.","tags":["Distributions"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"parameters":[{"name":"distribution_id","in":"path","required":true,"description":"The distribution ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"study_id":{"type":"string","description":"ID of the study this distribution belongs to"},"name":{"description":"Name of the distribution","anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string","enum":["link","service","email","website","app","panel","simulation"],"description":"How the study is distributed to participants"},"distribution_provider":{"anyOf":[{"type":"string","enum":["respondent","user_interviews","prolific","terac"],"description":"Third-party panel provider"},{"type":"null"}]},"config":{"description":"Provider-specific configuration","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"incentive":{"description":"Incentive configuration for link distributions","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},{"type":"null"}]},"quota_limit":{"description":"Maximum number of responses","anyOf":[{"type":"number"},{"type":"null"}]},"quota_frequency":{"description":"How often the quota resets","type":"string","enum":["lifetime","monthly","weekly","daily"]},"segment_quotas":{"description":"Per-segment subquotas within the overall quota","anyOf":[{"$ref":"#/$defs/__schema0"},{"type":"null"}]},"screener_questions":{"description":"Screener questions for qualifying participants","type":"array","items":{"$ref":"#/$defs/__schema0"}},"targeting_condition":{"description":"Targeting rules for who is eligible","anyOf":[{"$ref":"#/$defs/__schema0"},{"type":"null"}]},"default_response_language":{"description":"Default language for responses","anyOf":[{"type":"string"},{"type":"null"}]},"collect_email":{"description":"Whether to collect participant email","type":"boolean"},"screen_email":{"description":"Whether to screen participants against an email list","type":"boolean"},"email_list_id":{"description":"Email list used to screen or invite participants","anyOf":[{"type":"string"},{"type":"null"}]},"automatic_invites":{"description":"Whether participants are invited automatically","type":"boolean"},"key":{"description":"Snippet key used to trigger an intercept distribution","anyOf":[{"type":"string"},{"type":"null"}]},"traffic_threshold":{"description":"Share of eligible traffic shown the study, out of 1,000,000","anyOf":[{"type":"number"},{"type":"null"}]},"complete_redirect_url":{"description":"URL to redirect to after completion","anyOf":[{"type":"string"},{"type":"null"}]},"screen_out_redirect_url":{"description":"URL to redirect screened-out participants","anyOf":[{"type":"string"},{"type":"null"}]},"quota_full_redirect_url":{"description":"URL to redirect when quota is full","anyOf":[{"type":"string"},{"type":"null"}]},"quality_terminate_redirect_url":{"description":"URL to redirect participants terminated for quality","anyOf":[{"type":"string"},{"type":"null"}]},"description":{"description":"Description of the distribution","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["study_id"],"additionalProperties":false,"$defs":{"__schema0":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema0"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}}]}}}}}}}},"/api/v1/distributions/{distribution_id}/publish":{"post":{"summary":"Publish a distribution","description":"Publish a distribution to make it live. For link/website distributions, this activates the distribution URL. For panel distributions, this launches the project with the panel provider.","tags":["Distributions"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"parameters":[{"name":"distribution_id","in":"path","required":true,"description":"The distribution ID to publish","schema":{"type":"string"}}]}},"/api/v1/stimuli/{stimulus_id}/metadata":{"get":{"summary":"Get stimulus metadata","description":"Retrieve the caller-defined attributes stored on a stimulus. Stimulus IDs appear on each stimulus in a study's plan.","tags":["Stimuli"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"parameters":[{"name":"stimulus_id","in":"path","required":true,"description":"The stimulus ID","schema":{"type":"string"}}]},"put":{"summary":"Replace stimulus metadata","description":"Replace every attribute on a stimulus in one call. Values may be strings, numbers, or arrays of those; nested objects are flattened into dotted keys, so { \"pricing\": { \"tier\": \"pro\" } } is stored as { \"pricing.tier\": \"pro\" }. Null values are dropped and booleans are rejected.","tags":["Stimuli"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"parameters":[{"name":"stimulus_id","in":"path","required":true,"description":"The stimulus ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Attributes to store on the stimulus. Values may be strings, numbers, booleans, or arrays of strings and numbers — a list may not hold booleans. Nested objects are flattened into dotted keys — { \"pricing\": { \"tier\": \"pro\" } } is stored as { \"pricing.tier\": \"pro\" }. Null values are dropped."}},"required":["metadata"],"additionalProperties":false,"description":"Replace a stimulus's metadata"}}}}},"patch":{"summary":"Merge stimulus metadata","description":"Merge attributes into a stimulus's existing metadata. Keys in the payload are replaced, keys left out are untouched. Nested objects are flattened the same way as a replace.","tags":["Stimuli"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"parameters":[{"name":"stimulus_id","in":"path","required":true,"description":"The stimulus ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Attributes to store on the stimulus. Values may be strings, numbers, booleans, or arrays of strings and numbers — a list may not hold booleans. Nested objects are flattened into dotted keys — { \"pricing\": { \"tier\": \"pro\" } } is stored as { \"pricing.tier\": \"pro\" }. Null values are dropped."}},"required":["metadata"],"additionalProperties":false,"description":"Merge attributes into a stimulus's metadata"}}}}}},"/api/v1/stimuli/{stimulus_id}/metadata/{key}":{"get":{"summary":"Get one metadata attribute","description":"Retrieve a single attribute from a stimulus's metadata. Returns 404 when the stimulus has no such key.","tags":["Stimuli"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"parameters":[{"name":"stimulus_id","in":"path","required":true,"description":"The stimulus ID","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"The metadata key","schema":{"type":"string"}}]},"put":{"summary":"Set one metadata attribute","description":"Set a single attribute, leaving the rest of the stimulus's metadata alone. An object value is flattened under the key and replaces anything already nested there; a null value removes the key.","tags":["Stimuli"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"parameters":[{"name":"stimulus_id","in":"path","required":true,"description":"The stimulus ID","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"The metadata key","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"The value to store — a string, a number, a boolean, or an array of strings and numbers. An object is flattened under the key, replacing anything already nested there. Null removes the key."}},"required":["value"],"additionalProperties":false,"description":"Set a single metadata key on a stimulus"}}}}},"delete":{"summary":"Delete one metadata attribute","description":"Remove a single attribute from a stimulus's metadata, along with anything nested under it.","tags":["Stimuli"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"parameters":[{"name":"stimulus_id","in":"path","required":true,"description":"The stimulus ID","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"The metadata key","schema":{"type":"string"}}]}},"/api/v1/responses":{"get":{"summary":"List responses","description":"Retrieve responses for a study. Supports filtering by study, distribution, status, date range, and more. Returns responses ordered by sequence number (newest first).","tags":["Responses"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — missing or invalid authentication"}},"parameters":[{"name":"studyId","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by study ID"},{"name":"startDateTime","in":"query","required":false,"schema":{"type":"string"},"description":"Filter responses after this ISO 8601 datetime"},{"name":"endDateTime","in":"query","required":false,"schema":{"type":"string"},"description":"Filter responses before this ISO 8601 datetime"},{"name":"environment","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by environment (e.g. production, test)"},{"name":"hasMessages","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by whether the response has messages ('true' or 'false')"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"Filter by response status (single value or array)"},{"name":"distributionId","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"Filter by distribution ID (single value or array)"},{"name":"id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"Filter by response ID (single value or array)"}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API token from the Voicepanel dashboard (Settings → API Tokens)"}}}}