{ "openapi": "3.1.0", "info": { "title": "User Intuition Public API", "description": "## Public Integration API\n\nProgrammatic access to User Intuition for external integrators: manage studies, participants, interviews, reports, and panels.\n\n### Authentication\n\nAll endpoints require a Bearer token \u2014 either an API key (prefixed `ui_sk_`, created in the dashboard) or a dashboard JWT:\n\n```\nAuthorization: Bearer \n```\n\n### Base URLs\n\n- **Production:** `https://api.userintuition.ai`\n- **Staging:** `https://staging.userintuition.ai`\n\n### Support\n\nFor API support, contact support@userintuition.ai", "version": "1.0.0", "contact": { "name": "User Intuition Support", "email": "support@userintuition.ai" } }, "servers": [ { "url": "https://api.userintuition.ai", "description": "Production" }, { "url": "https://staging.userintuition.ai", "description": "Staging" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/api/public/v1/studies/": { "get": { "tags": [ "public-studies" ], "summary": "List Studies", "operationId": "listStudies", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" }, "example": 1 }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" }, "example": 20 }, { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by name", "title": "Name" }, "description": "Filter by name", "example": "Appliance" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by provisioning status: draft, ready, provisioned", "title": "Status" }, "description": "Filter by provisioning status: draft, ready, provisioned" }, { "name": "recruiting_method", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by panel, byop, or synthetic_respondents", "title": "Recruiting Method" }, "description": "Filter by panel, byop, or synthetic_respondents" }, { "name": "created_after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created After" } }, { "name": "has_report", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Report" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudyList" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "List studies visible to this account with pagination and optional filters." }, "post": { "tags": [ "public-studies" ], "summary": "Create Study", "operationId": "createStudy", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudyCreate" }, "examples": { "Minimal draft": { "summary": "Minimal draft", "description": "Creates a BYOP draft. The response lists the settings still required before interviews can run.", "value": { "name": "Recent appliance purchases", "study_type": "in-depth-interview", "recruiting_method": "byop" } }, "Synthetic respondents": { "summary": "Chat study with synthetic respondents", "description": "synthetic_respondents uses AI respondents. interview_format defaults to chat when omitted; video and voice are rejected for this recruiting method.", "value": { "name": "AI research tool positioning", "study_type": "in-depth-interview", "recruiting_method": "synthetic_respondents", "language": "en", "expected_duration_seconds": 900, "study_plan": { "objectives": "Understand what triggers startup CEOs to evaluate AI-powered research tools, how they build a shortlist, and what proof makes a provider credible.", "conversation_flow": "Discuss the last important customer-research decision, how the CEO gathered input, why they considered an AI tool, alternatives they compared, trust thresholds, and evidence needed to shortlist one.", "background": "Research into the earliest evaluation stage for AI research tools." } } }, "Single-select screener": { "summary": "In-depth interview with single-select screener", "description": "A five-minute BYOP chat study. Choosing No disqualifies the respondent.", "value": { "name": "Recent appliance purchases", "study_type": "in-depth-interview", "recruiting_method": "byop", "interview_format": "chat", "language": "en", "expected_duration_seconds": 300, "study_plan": { "objectives": "Understand what triggered one recent blender or microwave purchase, which alternatives were considered, and how price and reliability affected the choice.", "conversation_flow": "Ask for the participant's purchase story. Explore the need that triggered it, the closest alternative, the price-versus-reliability tradeoff, and satisfaction after using the appliance.", "background": "Exploratory research into household appliance purchase decisions." }, "screener_questions": [ { "text": "Have you bought a blender or microwave in the past year?", "type": "single_select", "options": [ { "text": "Yes", "disqualify": false }, { "text": "No", "disqualify": true } ] } ] } }, "Multi-select screener": { "summary": "Concept test with multi-select screener", "description": "Every multi-select option must set selection_rule. must_select is required, may_select is optional, and reject disqualifies when selected.", "value": { "name": "Analytics dashboard concept", "study_type": "concept-test", "recruiting_method": "byop", "interview_format": "voice", "voice": "female", "language": "en", "expected_duration_seconds": 900, "study_plan": { "objectives": "Learn how product managers interpret and prioritize a dashboard concept.", "conversation_flow": "Discuss current reporting work, show the concept, and probe comprehension, value, and concerns." }, "screener_questions": [ { "text": "Which tools do you currently use for product analytics?", "type": "multi_select", "options": [ { "text": "Amplitude", "selection_rule": "must_select" }, { "text": "Mixpanel", "selection_rule": "may_select" }, { "text": "I do not use analytics tools", "selection_rule": "reject" } ] } ] } }, "Numeric text screener": { "summary": "Voice study with numeric text screener", "description": "An integers-only answer constrained to an inclusive age range. text_input questions have no options.", "value": { "name": "Home appliance ownership", "study_type": "in-depth-interview", "recruiting_method": "byop", "interview_format": "voice", "voice": "male", "language": "en", "expected_duration_seconds": 600, "study_plan": { "objectives": "Understand what triggered one recent blender or microwave purchase, which alternatives were considered, and how price and reliability affected the choice.", "conversation_flow": "Ask for the participant's purchase story. Explore the need that triggered it, the closest alternative, the price-versus-reliability tradeoff, and satisfaction after using the appliance.", "background": "Exploratory research into household appliance purchase decisions." }, "screener_questions": [ { "text": "What is your age?", "type": "text_input", "input_mode": "integers_only", "numeric_ranges": [ { "min": 25, "max": 64 } ] } ] } }, "Prototype video Panel": { "summary": "Panel prototype test with catalog targeting", "description": "Uses a video interview and panel targeting IDs. Look up current qualification_id and option_id values with GET /targeting-attributes before sending.", "value": { "name": "Checkout prototype test", "study_type": "prototype-test", "recruiting_method": "panel", "interview_format": "video", "voice": "female", "language": "en", "expected_duration_seconds": 1200, "study_plan": { "objectives": "Observe where startup leaders hesitate while evaluating a checkout prototype.", "conversation_flow": "Establish context, ask the participant to use the prototype, then probe expectations and friction." }, "targeting_attributes": [ { "qualification_id": 89, "allowed_options": [ 1 ], "disallowed_options": [] } ] } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudy" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "Create a draft study. Customize its plan before inviting participants or launching recruitment." } }, "/api/public/v1/studies/{study_id}/concept-images": { "post": { "tags": [ "public-studies" ], "summary": "Upload Concept Image", "description": "Upload a participant-facing image stimulus, up to 10 MB, to an owned study.", "operationId": "uploadConceptImage", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_uploadConceptImage" }, "examples": { "Image file": { "summary": "Attach an image file", "description": "Send PNG, JPEG, GIF, or WebP bytes, up to 10 MB, with a participant-facing label.", "value": { "file": "", "label": "Concept A" } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicConceptImage" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/{study_id}/concept-images/from-url": { "post": { "tags": [ "public-studies" ], "summary": "Upload Concept Image From Url", "description": "Fetch a public image URL with redirect and private-network checks, then attach it to an owned study.", "operationId": "uploadConceptImageFromUrl", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicConceptImageUrlUpload" }, "examples": { "Public image URL": { "summary": "Attach an image by URL", "description": "The API checks the URL and redirects before downloading a bounded image.", "value": { "url": "https://example.com/concept.png", "label": "Concept A" } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicConceptImage" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/{study_id}/customize-plan": { "post": { "tags": [ "public-studies" ], "summary": "Customize Study Plan", "description": "Run one resumable turn through the same planning agent and tools used by\nthe dashboard's Customize Plan page.\n\nThe conversation id is stored on the study. Questions are returned to the\ncaller; completed plan markdown is persisted automatically.", "operationId": "customizeStudyPlan", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCustomizeStudyRequest" }, "examples": { "Planning turn": { "summary": "Planning instruction", "description": "Send one natural-language turn. If response_type is question, answer it in the next call.", "value": { "message": "We want to understand how households choose a blender or microwave. Ask about one recent purchase, what triggered it, the closest alternative, and how they weighed price against reliability." } }, "Delegated research design": { "summary": "Proceed with research-design assumptions", "description": "The researcher delegated ordinary design choices. Keep draft-only workflow instructions out of the research message; this call does not launch fieldwork.", "value": { "message": "Understand why recent buyers abandoned checkout and what reassurance they needed.", "decisions": "agent", "execution_policy": "draft_only" } }, "Concept image": { "summary": "Planning turn with concept image", "description": "data_base64 contains image bytes only, without a data-URL prefix. Decoded files may be at most 10 MB.", "value": { "message": "Add this checkout screen to the plan and ask what the participant expects to happen next.", "concept_image": { "data_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB", "filename": "checkout.png", "content_type": "image/png", "label": "Checkout screen" } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCustomizeStudyResponse" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/create-with-participants": { "post": { "tags": [ "public-studies" ], "summary": "Create Study With Participants", "description": "Create a BYOP study and its participant invitations in one request.", "operationId": "createStudyWithParticipants", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCreateWithParticipants" }, "examples": { "Emailed and silent": { "summary": "Create a provisioned study with emailed and silent invites", "description": "silent false sends the invitation email; silent true creates the participant without sending it.", "value": { "study": { "name": "AI research tool shortlist", "study_type": "in-depth-interview", "recruiting_method": "byop", "interview_format": "voice", "voice": "male", "language": "en", "expected_duration_seconds": 1080, "study_plan": { "objectives": "Understand what triggers startup CEOs to evaluate AI-powered research tools, how they build a shortlist, and what proof makes a provider credible.", "conversation_flow": "Discuss the last important customer-research decision, how the CEO gathered input, why they considered an AI tool, alternatives they compared, trust thresholds, and evidence needed to shortlist one.", "background": "Research into the earliest evaluation stage for AI research tools." }, "byop_config": { "incentive_amount": 123, "is_incentives_enabled": true, "auto_send_incentives": true } }, "participants": [ { "email": "alex@example.com", "silent": false }, { "email": "sam@example.com", "silent": true } ] } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCreateWithParticipantsResponse" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/create-and-launch-panel": { "post": { "tags": [ "public-studies" ], "summary": "Create Study And Launch Panel", "description": "Preview a Panel study without creating or fielding it. Paid launch requires\na persisted study and a current estimate from the two-step launch flow.", "operationId": "createStudyAndLaunchPanel", "parameters": [ { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCreateAndLaunch" }, "examples": { "Targeted dry run": { "summary": "Targeted cost estimate", "description": "dry_run true validates the complete request and returns cost and timeline without creating or fielding a study.", "value": { "study": { "name": "Startup CEO AI tool shortlist", "study_type": "in-depth-interview", "recruiting_method": "panel", "interview_format": "voice", "voice": "male", "language": "en", "expected_duration_seconds": 1200, "study_plan": { "objectives": "Understand what triggers startup CEOs to evaluate AI-powered research tools, how they build a shortlist, and what proof makes a provider credible.", "conversation_flow": "Discuss the last important customer-research decision, how the CEO gathered input, why they considered an AI tool, alternatives they compared, trust thresholds, and evidence needed to shortlist one.", "background": "Research into the earliest evaluation stage for AI research tools." }, "targeting_attributes": [ { "qualification_id": 89, "allowed_options": [ 1 ], "disallowed_options": [] } ], "screener_questions": [ { "text": "Are you the founder or CEO of a startup?", "type": "single_select", "options": [ { "text": "Yes", "disqualify": false }, { "text": "No", "disqualify": true } ] } ] }, "panel": { "target": 20, "incident_rate": 25, "country_code": "US", "frequency": "one-time", "dry_run": true } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCreateAndLaunchResponse" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/{study_id}": { "get": { "tags": [ "public-studies" ], "summary": "Get Study", "operationId": "getStudy", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudy" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "Retrieve the persisted study, including its current plan, status, and participant link." }, "patch": { "tags": [ "public-studies" ], "summary": "Patch Study", "description": "Partially update a study. Only provided fields change; screener_questions\nand targeting_attributes are patched independently (one doesn't wipe the other).", "operationId": "patchStudy", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudyUpdate" }, "examples": { "Metadata only": { "summary": "Change selected metadata", "description": "PATCH changes only fields present in the body.", "value": { "name": "Updated appliance interviews", "expected_duration_seconds": 600 } }, "BYOP incentives": { "summary": "Configure BYOP incentives", "description": "BYOP incentive configuration belongs on study update, not study creation. Amount is USD and must be 5\u2013500.", "value": { "byop_config": { "incentive_amount": 25, "is_incentives_enabled": true, "auto_send_incentives": true } } }, "Replace screeners": { "summary": "Replace custom screeners", "description": "Supplying screener_questions replaces the custom screener set without clearing panel targeting attributes.", "value": { "screener_questions": [ { "text": "Which appliance types have you purchased in the past year?", "type": "multi_select", "options": [ { "text": "Blender", "selection_rule": "may_select" }, { "text": "Microwave", "selection_rule": "may_select" }, { "text": "None of these", "selection_rule": "reject" } ] }, { "text": "How many household appliances have you purchased in the past year?", "type": "text_input", "input_mode": "integers_only", "numeric_ranges": [ { "min": 1, "max": 20 } ] } ] } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudy" } } } }, "409": { "description": "Active panel must be paused or stopped before editing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudyEditConflict" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } }, "delete": { "tags": [ "public-studies" ], "summary": "Delete Study", "operationId": "deleteStudy", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudy" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "Soft-delete a study and remove its linked research from normal reads." } }, "/api/public/v1/studies/{study_id}/fielding-progress": { "get": { "tags": [ "public-studies" ], "summary": "Get Fielding Progress", "description": "Show current target progress, quality grades, and a conservative finish estimate.", "operationId": "getFieldingProgress", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFieldingProgress" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/{study_id}/embed-code": { "get": { "tags": [ "public-studies" ], "summary": "Get Study Embed Code", "description": "Return copy-ready HTML that launches a study from another website.", "operationId": "getStudyEmbedCode", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } }, { "name": "type", "in": "query", "required": false, "schema": { "enum": [ "widget", "button" ], "type": "string", "description": "Return a full interview widget or a link styled as a button", "default": "widget", "title": "Type" }, "description": "Return a full interview widget or a link styled as a button" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudyEmbedCode" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/{study_id}/pause": { "post": { "tags": [ "public-studies" ], "summary": "Pause Study", "description": "Pause a study. Panel surveys, target cycles, and reward holds are preserved.", "operationId": "pauseStudy", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudy" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/{study_id}/resume": { "post": { "tags": [ "public-studies" ], "summary": "Resume Study", "description": "Resume a paused study. A preserved panel survey returns to fielding.", "operationId": "resumeStudy", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudy" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/{study_id}/stop": { "post": { "tags": [ "public-studies" ], "summary": "Stop Study", "description": "Stop recruitment and prevent additional interviews through study links.", "operationId": "stopStudy", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudy" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/{study_id}/report": { "post": { "tags": [ "public-studies" ], "summary": "Generate Report", "description": "Queue report analysis and return a job to poll; report.ready also fires on completion.", "operationId": "generateStudyReport", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicJob" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } }, "get": { "tags": [ "public-studies" ], "summary": "Get Report", "operationId": "getStudyReport", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "view", "in": "query", "required": false, "schema": { "enum": [ "overview", "full", "references", "study_findings", "participant_profiles", "participant_responses", "evidence_coverage", "recommended_next_steps" ], "type": "string", "description": "overview (default), full, or one report section", "default": "overview", "title": "View" }, "description": "overview (default), full, or one report section", "example": "study_findings" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicReport" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "Read the latest persisted report. Choose an overview, one section, or the full report with view." } }, "/api/public/v1/studies/{study_id}/report/jobs/{job_id}": { "get": { "tags": [ "public-studies" ], "summary": "Get Report Job", "operationId": "getStudyReportJob", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicJob" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "Poll an asynchronous report job until it succeeds or fails." } }, "/api/public/v1/studies/{study_id}/estimate-panel": { "post": { "tags": [ "public-studies" ], "summary": "Estimate Panel", "description": "Read-only estimate of one panel recruitment cycle, including balance and card hold.", "operationId": "estimatePanel", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPanelCreate" }, "examples": { "Read-only panel estimate": { "summary": "Estimate one recruitment cycle", "description": "Returns credit cost, available balance, participant reward, card hold, and a heuristic timeline without launching.", "value": { "target": 20, "incident_rate": 25, "country_code": "US", "frequency": "one-time" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPanelResponse" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/{study_id}/launch-panel": { "post": { "tags": [ "public-studies" ], "summary": "Launch Panel", "description": "Launch a paid panel for a Panel-type study (use ``dry_run`` for a cost estimate).", "operationId": "launchPanel", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPanelCreate" }, "examples": { "Cost estimate": { "summary": "Untargeted cost estimate", "description": "Returns estimated price and timeline without starting recruitment.", "value": { "target": 20, "incident_rate": 25, "country_code": "US", "frequency": "one-time", "dry_run": true } }, "Fixed option targets": { "summary": "Estimate with fixed option targets", "description": "Reserves 8 interviews for option 1. Other qualifying options share the remaining 12 interviews.", "value": { "target": 20, "incident_rate": 25, "country_code": "US", "frequency": "one-time", "dry_run": true, "targeting_attributes": [ { "qualification_id": 2, "option_targets": [ { "option_id": 1, "target": 8 } ] } ] } }, "Option-target object map": { "summary": "Option targets as an object map", "description": "Direct API clients may key option_targets by option ID. This is equivalent to the array form.", "value": { "target": 20, "incident_rate": 25, "country_code": "US", "frequency": "one-time", "dry_run": true, "targeting_attributes": [ { "qualification_id": 2, "option_targets": { "1": 8 } } ] } }, "Paid launch": { "summary": "Start paid recruitment", "description": "Launch an already-provisioned Panel study with a current estimate_id from estimatePanel after approval.", "value": { "target": 20, "incident_rate": 25, "country_code": "US", "frequency": "one-time", "dry_run": false, "estimate_id": "est_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPanelResponse" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/{study_id}/external-panel": { "get": { "tags": [ "public-external-panels" ], "summary": "Get Study External Panel", "description": "Get the external-panel entry link and outcome redirects for an owned BYOP study.", "operationId": "getStudyExternalPanel", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicExternalPanelConfig" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } }, "put": { "tags": [ "public-external-panels" ], "summary": "Put Study External Panel", "description": "Create or replace the external-panel integration for an owned BYOP study.", "operationId": "putStudyExternalPanel", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalPanelConfigInput" }, "examples": { "Custom panel": { "summary": "Connect a customer-supplied panel", "description": "The provider substitutes its respondent ID in the returned entry_url and receives an outcome redirect after the interview.", "value": { "provider": "custom", "respondent_id_param": "rid", "respondent_id_placeholder": "{{RESPONDENT_ID}}", "complete_redirect_url": "https://panel.example/complete?rid={{respondent_id}}", "screenout_redirect_url": "https://panel.example/screenout?rid={{respondent_id}}" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicExternalPanelConfig" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } }, "delete": { "tags": [ "public-external-panels" ], "summary": "Delete Study External Panel", "description": "Disable the external-panel entry link for an owned BYOP study.", "operationId": "deleteStudyExternalPanel", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/{study_id}/external-panel/regenerate-token": { "post": { "tags": [ "public-external-panels" ], "summary": "Regenerate Study External Panel Token", "description": "Replace the public entry token, immediately invalidating the old link.", "operationId": "regenerateStudyExternalPanelToken", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicExternalPanelConfig" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/participants/": { "get": { "tags": [ "public-participants" ], "summary": "List Participants", "operationId": "listParticipants", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" }, "example": 1 }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" }, "example": 20 }, { "name": "study_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by study", "title": "Study Id" }, "description": "Filter by study", "example": "11111111-2222-3333-4444-555555555555" }, { "name": "email", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by email", "title": "Email" }, "description": "Filter by email", "example": "alex@example.com" }, { "name": "external_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ], "description": "Exact customer ID; requires study_id", "title": "External Id" }, "description": "Exact customer ID; requires study_id" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicParticipantList" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "List BYOP participants and invitation status, optionally filtered by study or email." }, "post": { "tags": [ "public-participants" ], "summary": "Create Participants", "description": "Queue up to 100 invitations. Poll the returned job before listing participants.", "operationId": "createParticipants", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicParticipantsCreate" }, "examples": { "Emailed and silent": { "summary": "Create emailed and silent participants", "description": "Participant emails must be unique ignoring case. A request may contain 1\u2013100 participants.", "value": { "study_id": "11111111-2222-3333-4444-555555555555", "participants": [ { "email": "alex@example.com", "silent": false }, { "email": "sam@example.com", "silent": true } ] } } } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicJob" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/participants/jobs/{job_id}": { "get": { "tags": [ "public-participants" ], "summary": "Get Participant Job", "operationId": "getParticipantJob", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicJob" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "Poll an asynchronous participant creation job until it succeeds or fails." } }, "/api/public/v1/participants/{participant_id}": { "get": { "tags": [ "public-participants" ], "summary": "Get Participant", "operationId": "getParticipant", "parameters": [ { "name": "participant_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Participant Id" }, "example": "66666666-7777-8888-9999-000000000000" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicParticipant" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "Retrieve one BYOP participant and their current lifecycle status." }, "patch": { "tags": [ "public-participants" ], "summary": "Patch Participant", "description": "Update email, customer ID, or bounded metadata.", "operationId": "updateParticipant", "parameters": [ { "name": "participant_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Participant Id" }, "example": "66666666-7777-8888-9999-000000000000" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicParticipantPatch" }, "examples": { "Update email": { "summary": "Update participant email", "description": "The participant ID is supplied in the path; email is the only mutable body field.", "value": { "email": "alex.new@example.com" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicParticipant" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } }, "put": { "tags": [ "public-participants" ], "summary": "Update Participant", "description": "Deprecated: use PATCH /api/public/v1/participants/{participant_id}.", "operationId": "updateParticipantPut", "deprecated": true, "parameters": [ { "name": "participant_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Participant Id" }, "example": "66666666-7777-8888-9999-000000000000" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicParticipantUpdate" }, "examples": { "Legacy email update": { "summary": "Legacy participant email update", "description": "Deprecated PUT form; use PATCH for new integrations.", "value": { "email": "alex.new@example.com" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicParticipant" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } }, "delete": { "tags": [ "public-participants" ], "summary": "Delete Participant", "description": "Soft-delete a BYOP invitation; linked interviews require explicit cascade consent.", "operationId": "deleteParticipant", "parameters": [ { "name": "participant_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Participant Id" } }, { "name": "cascade_interviews", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Also soft-delete this invitation's interviews", "default": false, "title": "Cascade Interviews" }, "description": "Also soft-delete this invitation's interviews" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/participants/{participant_id}/reward": { "post": { "tags": [ "public-participants" ], "summary": "Send Participant Reward", "description": "Send the configured incentive to a participant (BYOP studies only).", "operationId": "sendParticipantReward", "parameters": [ { "name": "participant_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Participant Id" }, "example": "66666666-7777-8888-9999-000000000000" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TremendousRewardResponse" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/interviews/": { "get": { "tags": [ "public-interviews" ], "summary": "List Interviews", "operationId": "listInterviews", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" }, "example": 1 }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" }, "example": 20 }, { "name": "study_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by study", "title": "Study Id" }, "description": "Filter by study", "example": "11111111-2222-3333-4444-555555555555" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by interview status", "title": "Status" }, "description": "Filter by interview status", "example": "completed" }, { "name": "quality", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Filter by quality (Excellent, Good, Fair, Poor)", "title": "Quality" }, "description": "Filter by quality (Excellent, Good, Fair, Poor)", "example": [ "Good", "Excellent" ] }, { "name": "participant_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by participant ID", "title": "Participant Id" }, "description": "Filter by participant ID" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicInterviewList" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "List interview summaries with pagination and optional study, participant, status, or quality filters." } }, "/api/public/v1/interviews/{interview_id}": { "get": { "tags": [ "public-interviews" ], "summary": "Get Interview", "operationId": "getInterview", "parameters": [ { "name": "interview_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Interview Id" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "message_offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Message Offset" } }, { "name": "message_limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum segments; the response also stops near 20 KB of transcript text", "default": 50, "title": "Message Limit" }, "description": "Maximum segments; the response also stops near 20 KB of transcript text" }, { "name": "redact_pii", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Mask email addresses, phone numbers, and US Social Security numbers in transcript and screener text; omit participant email and recording links. Pattern masking cannot detect every identifier.", "default": false, "title": "Redact Pii" }, "description": "Mask email addresses, phone numbers, and US Social Security numbers in transcript and screener text; omit participant email and recording links. Pattern masking cannot detect every identifier." }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicInterview" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "Read one interview's public metadata and a bounded page of transcript messages." }, "delete": { "tags": [ "public-interviews" ], "summary": "Delete Interview", "description": "Soft-delete an interview owned by the authenticated user.", "operationId": "deleteInterview", "parameters": [ { "name": "interview_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Interview Id" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/webhooks/": { "post": { "tags": [ "public-webhooks" ], "summary": "Create Webhook", "operationId": "createWebhook", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" }, "examples": { "Completed-interview webhook": { "summary": "Register an account-wide webhook", "description": "The URL receives completed interviews for every study. Store the returned signing_secret; it is shown once.", "value": { "hook_url": "https://your-company.example/webhooks/user-intuition" } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "Register a signed event webhook. The signing secret appears only in the creation response." }, "get": { "tags": [ "public-webhooks" ], "summary": "List Webhooks", "operationId": "listWebhooks", "parameters": [ { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookList" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "List the account's registered event webhooks without signing secrets." }, "delete": { "tags": [ "public-webhooks" ], "summary": "Delete Webhook", "description": "Deprecated: use DELETE /api/public/v1/webhooks/{webhook_id}. The body-based form remains available during migration.", "operationId": "deleteWebhook", "deprecated": true, "parameters": [ { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelete" }, "examples": { "Delete by URL": { "summary": "Unregister a webhook by URL", "description": "Pass the exact hook_url used when the webhook was created.", "value": { "hook_url": "https://your-company.example/webhooks/user-intuition" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/webhooks/{webhook_id}": { "get": { "tags": [ "public-webhooks" ], "summary": "Get Webhook", "operationId": "getWebhook", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "Retrieve one registered webhook without its signing secret." }, "delete": { "tags": [ "public-webhooks" ], "summary": "Delete Webhook By Id", "operationId": "deleteWebhookById", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "Delete a registered webhook by ID." } }, "/api/public/v1/webhooks/{webhook_id}/deliveries": { "get": { "tags": [ "public-webhooks" ], "summary": "List Webhook Deliveries", "operationId": "listWebhookDeliveries", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryAttemptList" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "List bounded webhook delivery attempts and status without event payloads." } }, "/api/public/v1/webhooks/{webhook_id}/test": { "post": { "tags": [ "public-webhooks" ], "summary": "Test Webhook", "description": "Send a signed test event containing no participant or study data.", "operationId": "testWebhook", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResult" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/webhooks/{webhook_id}/rotate-secret": { "post": { "tags": [ "public-webhooks" ], "summary": "Rotate Webhook Secret", "description": "Replace the signing secret; the new value is returned once.", "operationId": "rotateWebhookSecret", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/targeting-attributes/": { "get": { "tags": [ "public-targeting" ], "summary": "List Targeting Attributes", "description": "Catalog of panel targeting attributes, searchable by name and filterable by category.", "operationId": "listTargetingAttributes", "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Case-insensitive name search", "title": "Name" }, "description": "Case-insensitive name search", "example": "Job Title" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Case-insensitive exact category filter", "title": "Category" }, "description": "Case-insensitive exact category filter", "example": "Employment" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTargetingAttributeCatalog" }, "title": "Response Listtargetingattributes" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/panel-countries/": { "get": { "tags": [ "public-panel-countries" ], "summary": "List Panel Countries", "description": "Supported panel countries with their language options. Provide `language`\nOR `country` to filter (not both); omit both to list all.", "operationId": "listPanelCountries", "parameters": [ { "name": "language", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to countries that support this language (e.g. en); case-insensitive", "title": "Language" }, "description": "Filter to countries that support this language (e.g. en); case-insensitive", "example": "EN" }, { "name": "country", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to a single country code (e.g. US)", "title": "Country" }, "description": "Filter to a single country code (e.g. US)" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicPanelCountry" }, "title": "Response Listpanelcountries" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/feasibility-requests/": { "post": { "tags": [ "public-feasibility" ], "summary": "Submit Feasibility Request", "description": "Submit an audience for manual feasibility review.", "operationId": "submitFeasibilityRequest", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFeasibilityRequestCreate" }, "examples": { "Niche audience": { "summary": "Low-incidence audience in one country", "description": "incident_rate is percentage points, so 8.5 means 8.5%. country_code is an array.", "value": { "target_audience": "US startup CEOs who evaluated AI research tools in the past six months", "country_code": [ "US" ], "target": 20, "incident_rate": 8.5 } }, "Multi-country existing study": { "summary": "Multi-country audience linked to a study", "description": "study_id is optional. Include it only when the request belongs to an existing accessible study.", "value": { "target_audience": "Finance directors who approve SaaS purchases at companies with 100\u2013500 employees", "country_code": [ "US", "CA", "GB" ], "target": 30, "incident_rate": 6, "study_id": "11111111-2222-3333-4444-555555555555" } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFeasibilityRequest" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } }, "get": { "tags": [ "public-feasibility" ], "summary": "List Feasibility Requests", "description": "List the current account's feasibility requests, newest first.", "operationId": "listFeasibilityRequests", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFeasibilityRequestList" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/feasibility-requests/{request_id}/cancel": { "post": { "tags": [ "public-feasibility" ], "summary": "Cancel Feasibility Request", "description": "Withdraw a pending request before a feasibility response is issued.", "operationId": "cancelFeasibilityRequest", "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFeasibilityRequest" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/feasibility-requests/{request_id}": { "get": { "tags": [ "public-feasibility" ], "summary": "Get Feasibility Request", "description": "Get a feasibility request by ID.", "operationId": "getFeasibilityRequest", "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" }, "example": "ffffffff-1111-2222-3333-444444444444" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFeasibilityRequest" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/research/search/": { "post": { "tags": [ "public-research-search" ], "summary": "Search Research", "description": "Rank candidate content, then return canonical stored JSON.", "operationId": "searchResearch", "parameters": [ { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicResearchSearchRequest" }, "examples": { "Find pricing evidence": { "summary": "Find pricing evidence", "description": "Search one indexed study and return canonical finding/response JSON; cursor must be null in this release.", "value": { "query": "What makes people think The Ribbon is too expensive?", "filters": { "study_ids": [ "11111111-2222-3333-4444-555555555555" ], "content_types": [ "study_finding", "participant_response" ], "research_date_from": "2026-01-01", "research_date_to": "2026-09-16" }, "limit": 10, "cursor": null } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicResearchSearchResponse" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/account/identity": { "get": { "tags": [ "public-account" ], "summary": "Get Account Identity", "description": "Return the authenticated workspace without changing account state.", "operationId": "getAccountIdentity", "parameters": [ { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAccountIdentity" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/account/": { "get": { "tags": [ "public-account" ], "summary": "Get Account", "description": "Return account scope, available credits, and payment readiness.", "operationId": "getAccount", "parameters": [ { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAccount" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/reference/languages": { "get": { "tags": [ "public-reference" ], "summary": "List Interview Languages", "description": "List language codes accepted by public study creation.", "operationId": "listInterviewLanguages", "parameters": [ { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicLanguage" }, "title": "Response Listinterviewlanguages" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/reference/modes": { "get": { "tags": [ "public-reference" ], "summary": "List Interview Modes", "description": "List the supported interview formats.", "operationId": "listInterviewModes", "parameters": [ { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicInterviewMode" }, "title": "Response Listinterviewmodes" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/reference/voices": { "get": { "tags": [ "public-reference" ], "summary": "List Voice Choices", "description": "List product voice settings and display names without implementation data.", "operationId": "listVoiceChoices", "parameters": [ { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicVoiceChoice" }, "title": "Response Listvoicechoices" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/reference/study-types": { "get": { "tags": [ "public-reference" ], "summary": "List Study Types", "description": "Page through visible planning templates without their internal prompts.", "operationId": "listStudyTypes", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudyTypeList" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/reference/study-types/{slug}": { "get": { "tags": [ "public-reference" ], "summary": "Get Study Type", "description": "Read one visible planning template by slug.", "operationId": "getStudyType", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudyType" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/usage/interviews": { "get": { "tags": [ "public-usage" ], "summary": "Get Interview Usage", "description": "Read bounded usage with the same resolved scope and totals as the dashboard.", "operationId": "getInterviewUsage", "parameters": [ { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive UTC start date", "title": "Start Date" }, "description": "Inclusive UTC start date" }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive UTC end date", "title": "End Date" }, "description": "Inclusive UTC end date" }, { "name": "cadence", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "daily", "weekly", "monthly" ], "type": "string" }, { "type": "null" } ], "title": "Cadence" } }, { "name": "app_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "App Id" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicInterviewUsage" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/admin/organizations": { "get": { "tags": [ "public-admin" ], "summary": "List Admin Organizations", "description": "Find organizations and active owners in this app for platform-admin selection.", "operationId": "listAdminOrganizations", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "Match organization name, active owner name, or active owner email", "title": "Search" }, "description": "Match organization name, active owner name, or active owner email" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAdminOrganizationList" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/{study_id}/customize-plan/jobs": { "post": { "tags": [ "public-studies" ], "summary": "Queue Customize Study Plan", "description": "Queue one planning turn and return immediately with a durable job ID.", "operationId": "queueCustomizeStudyPlan", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCustomizeStudyRequest" }, "examples": { "Planning turn": { "summary": "Queue a planning instruction", "description": "Receive a job ID immediately, then poll the job for the next question or saved plan.", "value": { "message": "Understand why recent buyers abandoned checkout and what reassurance they needed.", "decisions": "human", "execution_policy": "review_before_fieldwork" } } } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCustomizeStudyJob" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/{study_id}/customize-plan/jobs/{job_id}": { "get": { "tags": [ "public-studies" ], "summary": "Get Customize Study Job", "operationId": "getCustomizeStudyJob", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" }, "example": "66666666-7777-8888-9999-aaaaaaaaaaaa" }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCustomizeStudyJob" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "description": "Poll an asynchronous planning turn. A failed turn is not replayed automatically; inspect the saved study before retrying." } }, "/api/public/v1/studies/{study_id}/exports/interviews": { "post": { "tags": [ "public-exports" ], "summary": "Queue Interview Export", "description": "Queue a private CSV or JSONL export for one page of a study's interviews.", "operationId": "queueInterviewExport", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } }, { "name": "format", "in": "query", "required": true, "schema": { "enum": [ "csv", "jsonl" ], "type": "string", "description": "Export format", "title": "Format" }, "description": "Export format" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page of at most 100 interviews", "default": 1, "title": "Page" }, "description": "Page of at most 100 interviews" }, { "name": "redact_pii", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Mask email, phone, and US SSN patterns and omit recording links", "default": true, "title": "Redact Pii" }, "description": "Mask email, phone, and US SSN patterns and omit recording links" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicInterviewExportJob" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/api/public/v1/studies/{study_id}/exports/interviews/jobs/{job_id}": { "get": { "tags": [ "public-exports" ], "summary": "Get Interview Export Job", "description": "Poll a private export and receive a fresh 15-minute URL when complete.", "operationId": "getInterviewExportJob", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "X-UI-Organization-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.", "title": "X-Ui-Organization-Id" }, "description": "Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicInterviewExportJob" } } } }, "422": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "default": { "description": "Public API error. X-Request-ID matches error.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } } }, "webhooks": { "interview.completed": { "post": { "operationId": "onInterviewCompleted", "summary": "Receive interview.completed", "description": "Return any 2xx status to acknowledge delivery. Failed deliveries retry with backoff; deduplicate by the stable event id. Verify X-UI-Signature using the raw body and X-UI-Timestamp when a signing secret is configured.", "parameters": [ { "name": "X-UI-Timestamp", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "X-UI-Signature", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "study_id", "data" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "interview.completed" }, "study_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/PublicInterview" } } } } } }, "responses": { "200": { "description": "Delivery acknowledged" } } } }, "report.ready": { "post": { "operationId": "onReportReady", "summary": "Receive report.ready", "description": "Return any 2xx status to acknowledge delivery. Failed deliveries retry with backoff; deduplicate by the stable event id. Verify X-UI-Signature using the raw body and X-UI-Timestamp when a signing secret is configured.", "parameters": [ { "name": "X-UI-Timestamp", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "X-UI-Signature", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "study_id", "data" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "report.ready" }, "study_id": { "type": "string" }, "data": { "type": "object", "required": [ "report_id" ], "properties": { "report_id": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Delivery acknowledged" } } } }, "study.completed": { "post": { "operationId": "onStudyCompleted", "summary": "Receive study.completed", "description": "Return any 2xx status to acknowledge delivery. Failed deliveries retry with backoff; deduplicate by the stable event id. Verify X-UI-Signature using the raw body and X-UI-Timestamp when a signing secret is configured.", "parameters": [ { "name": "X-UI-Timestamp", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "X-UI-Signature", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "study_id", "data" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "study.completed" }, "study_id": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "description": "The completed target cycle summary." } } } } } }, "responses": { "200": { "description": "Delivery acknowledged" } } } } }, "components": { "schemas": { "Body_uploadConceptImage": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" }, "label": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Label" } }, "type": "object", "required": [ "file", "label" ], "title": "Body_uploadConceptImage" }, "ExternalPanelConfigInput": { "properties": { "provider": { "type": "string", "enum": [ "prolific", "cint", "cloudresearch", "terac", "custom" ], "title": "Provider", "default": "custom" }, "respondent_id_param": { "type": "string", "title": "Respondent Id Param", "default": "respondent_id" }, "respondent_id_placeholder": { "type": "string", "title": "Respondent Id Placeholder", "default": "{{RESPONDENT_ID}}" }, "session_id_param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id Param" }, "session_id_placeholder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id Placeholder" }, "external_study_id_param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Study Id Param" }, "external_study_id_placeholder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Study Id Placeholder" }, "complete_redirect_url": { "type": "string", "title": "Complete Redirect Url" }, "screenout_redirect_url": { "type": "string", "title": "Screenout Redirect Url" }, "quota_full_redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quota Full Redirect Url" }, "technical_redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Technical Redirect Url" } }, "type": "object", "required": [ "complete_redirect_url", "screenout_redirect_url" ], "title": "ExternalPanelConfigInput" }, "FeasibilityRequestStatus": { "type": "string", "enum": [ "received", "responded", "cancelled" ], "title": "FeasibilityRequestStatus" }, "GoalAssessment": { "properties": { "goal_id": { "type": "string", "title": "Goal Id" }, "finding_ids": { "items": { "type": "string" }, "type": "array", "title": "Finding Ids" }, "label": { "type": "string", "title": "Label", "default": "" }, "supports": { "type": "string", "minLength": 1, "title": "Supports" }, "limits": { "type": "string", "minLength": 1, "title": "Limits" }, "purpose": { "type": "string", "minLength": 1, "title": "Purpose" } }, "type": "object", "required": [ "goal_id", "supports", "limits", "purpose" ], "title": "GoalAssessment" }, "NumericRange": { "properties": { "min": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Min", "description": "Inclusive lower bound" }, "max": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Max", "description": "Inclusive upper bound" } }, "type": "object", "title": "NumericRange", "description": "Optional inclusive bounds constraining a numeric `text_input` answer." }, "PublicAccount": { "properties": { "user_id": { "type": "string", "title": "User Id" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id" }, "role": { "type": "string", "title": "Role" }, "workspace_scope": { "type": "string", "enum": [ "organization", "personal" ], "title": "Workspace Scope" }, "app_id": { "type": "string", "title": "App Id" }, "credential_type": { "type": "string", "enum": [ "api_key", "session" ], "title": "Credential Type" }, "scopes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Scopes", "description": "Granted API-key scopes; null for a dashboard session." }, "organization_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Name" }, "billing": { "$ref": "#/components/schemas/PublicAccountBilling" }, "limits": { "$ref": "#/components/schemas/PublicAccountLimits" } }, "type": "object", "required": [ "user_id", "role", "workspace_scope", "app_id", "credential_type", "billing" ], "title": "PublicAccount" }, "PublicAccountBilling": { "properties": { "available_credits": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Available Credits", "description": "Available credit balance; null when no wallet exists." }, "available_balance_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Available Balance Usd", "description": "USD value of available credits at this account's current conversion rate; null when unavailable." }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency", "description": "Currency used for the USD balance, not the unit of available_credits." }, "payment_method_on_file": { "type": "boolean", "title": "Payment Method On File", "default": false } }, "type": "object", "title": "PublicAccountBilling" }, "PublicAccountIdentity": { "properties": { "user_id": { "type": "string", "title": "User Id" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id" }, "role": { "type": "string", "title": "Role" }, "workspace_scope": { "type": "string", "enum": [ "organization", "personal" ], "title": "Workspace Scope" }, "app_id": { "type": "string", "title": "App Id" }, "credential_type": { "type": "string", "enum": [ "api_key", "session" ], "title": "Credential Type" }, "scopes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Scopes", "description": "Granted API-key scopes; null for a dashboard session." } }, "type": "object", "required": [ "user_id", "role", "workspace_scope", "app_id", "credential_type" ], "title": "PublicAccountIdentity" }, "PublicAccountLimits": { "properties": { "incentive_min_usd": { "type": "integer", "title": "Incentive Min Usd", "default": 5 }, "incentive_max_usd": { "type": "integer", "title": "Incentive Max Usd", "default": 500 } }, "type": "object", "title": "PublicAccountLimits" }, "PublicAdminOrganization": { "properties": { "organization_id": { "type": "string", "title": "Organization Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "owners": { "items": { "$ref": "#/components/schemas/PublicAdminOrganizationOwner" }, "type": "array", "title": "Owners" } }, "type": "object", "required": [ "organization_id", "owners" ], "title": "PublicAdminOrganization" }, "PublicAdminOrganizationList": { "properties": { "organizations": { "items": { "$ref": "#/components/schemas/PublicAdminOrganization" }, "type": "array", "title": "Organizations" }, "total_count": { "type": "integer", "title": "Total Count" }, "page": { "type": "integer", "title": "Page" }, "page_size": { "type": "integer", "title": "Page Size" } }, "type": "object", "required": [ "organizations", "total_count", "page", "page_size" ], "title": "PublicAdminOrganizationList" }, "PublicAdminOrganizationOwner": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" } }, "type": "object", "title": "PublicAdminOrganizationOwner" }, "PublicByopConfig": { "properties": { "incentive_amount": { "anyOf": [ { "type": "number", "maximum": 500.0, "minimum": 5.0 }, { "type": "null" } ], "title": "Incentive Amount", "description": "Per-participant incentive in USD ($5\u2013$500)." }, "is_incentives_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Incentives Enabled", "description": "Enable incentives." }, "auto_send_incentives": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Send Incentives", "description": "Auto-send incentive after high-quality interviews." } }, "additionalProperties": false, "type": "object", "title": "PublicByopConfig", "description": "Incentive settings (BYOP studies only)." }, "PublicByopConfigOut": { "properties": { "incentive_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Incentive Amount" }, "is_incentives_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Incentives Enabled" }, "auto_send_incentives": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Send Incentives" } }, "type": "object", "title": "PublicByopConfigOut" }, "PublicByopStudyCreate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "title": "Name", "description": "Study display name (maximum 40 characters)" }, "study_type": { "type": "string", "enum": [ "in-depth-interview", "concept-test", "prototype-test" ], "title": "Study Type", "description": "Study-type template slug", "default": "in-depth-interview" }, "recruiting_method": { "anyOf": [ { "type": "string", "const": "byop" }, { "type": "null" } ], "enum": [ "byop" ], "title": "Recruiting Method", "description": "Must be byop when supplied." }, "interview_format": { "anyOf": [ { "type": "string", "enum": [ "chat", "video", "voice" ] }, { "type": "null" } ], "title": "Interview Format", "description": "chat, video, or voice" }, "voice": { "anyOf": [ { "type": "string", "enum": [ "male", "female" ] }, { "type": "null" } ], "title": "Voice", "description": "Interviewer voice: male (Elliot) or female (Clara)" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "enum": [ "auto", "af", "am", "ar", "as", "az", "bg", "bn", "bs", "ca", "cs", "cy", "da", "de", "el", "en", "es", "et", "eu", "fa", "fi", "fil", "fr", "ga", "gl", "gu", "he", "hi", "hr", "hu", "hy", "id", "is", "it", "iu", "ja", "jv", "ka", "kk", "km", "kn", "ko", "lo", "lt", "lv", "mk", "ml", "mn", "mr", "ms", "mt", "my", "nb", "ne", "nl", "or", "pa", "pl", "ps", "pt", "ro", "ru", "si", "sk", "sl", "so", "sq", "sr", "su", "sv", "sw", "ta", "te", "th", "tr", "uk", "ur", "uz", "vi", "wuu", "yue", "zh", "zu" ], "title": "Language", "description": "Interview language: an ISO 639-1 code, or 'auto' to auto-detect. Must be one of the supported options." }, "study_plan": { "anyOf": [ { "$ref": "#/components/schemas/PublicStudyPlan" }, { "type": "null" } ], "description": "Interview instructions as named sections." }, "expected_duration_seconds": { "anyOf": [ { "type": "integer", "minimum": 300.0 }, { "type": "null" } ], "title": "Expected Duration Seconds", "description": "Maximum planned interview duration in seconds, including all sections, transitions, and likely follow-up probes. Estimate this from the completed study plan; it is not a guaranteed participant completion time." }, "screener_questions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicScreenerQuestionInput" }, "type": "array" }, { "type": "null" } ], "title": "Screener Questions" }, "targeting_attributes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicTargetingAttribute" }, "type": "array" }, { "type": "null" } ], "title": "Targeting Attributes", "description": "Target the panel by demographic qualifications (panel studies)." }, "byop_config": { "anyOf": [ { "$ref": "#/components/schemas/PublicByopConfig" }, { "type": "null" } ], "description": "Incentive settings for the participants created with this study." } }, "additionalProperties": false, "type": "object", "title": "PublicByopStudyCreate", "description": "Create fields for a BYOP study together with its participants." }, "PublicConceptImage": { "properties": { "id": { "type": "string", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "label": { "type": "string", "title": "Label" } }, "type": "object", "required": [ "id", "url", "label" ], "title": "PublicConceptImage", "description": "Participant-facing image stimulus. Storage metadata remains internal." }, "PublicConceptImageUrlUpload": { "properties": { "url": { "type": "string", "maxLength": 2048, "minLength": 1, "format": "uri", "title": "Url" }, "label": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Label" } }, "type": "object", "required": [ "url", "label" ], "title": "PublicConceptImageUrlUpload", "description": "Attach a publicly downloadable image without placing bytes in a planning turn." }, "PublicConceptLink": { "properties": { "id": { "type": "string", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "label": { "type": "string", "title": "Label" }, "embeddable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Embeddable" } }, "type": "object", "required": [ "id", "url", "label" ], "title": "PublicConceptLink", "description": "Participant-facing external stimulus. Recorder and credential metadata\nremain internal." }, "PublicCountryLanguage": { "properties": { "code": { "type": "string", "title": "Code", "description": "Lowercase language code, e.g. en" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Language name" } }, "type": "object", "required": [ "code" ], "title": "PublicCountryLanguage" }, "PublicCreateAndLaunch": { "properties": { "study": { "$ref": "#/components/schemas/PublicPanelStudyCreate" }, "panel": { "$ref": "#/components/schemas/PublicPanelCreate" } }, "additionalProperties": false, "type": "object", "required": [ "study", "panel" ], "title": "PublicCreateAndLaunch", "description": "Preview a Panel study without creating or fielding it. Paid launch requires\ncreating the study, obtaining a current estimate, then calling launch-panel." }, "PublicCreateAndLaunchResponse": { "properties": { "study": { "anyOf": [ { "$ref": "#/components/schemas/PublicStudy" }, { "type": "null" } ] }, "panel": { "$ref": "#/components/schemas/PublicPanelResponse" } }, "type": "object", "required": [ "panel" ], "title": "PublicCreateAndLaunchResponse" }, "PublicCreateWithParticipants": { "properties": { "study": { "$ref": "#/components/schemas/PublicByopStudyCreate" }, "participants": { "items": { "$ref": "#/components/schemas/PublicParticipantInviteInput" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Participants" } }, "additionalProperties": false, "type": "object", "required": [ "study", "participants" ], "title": "PublicCreateWithParticipants", "description": "Create a ready BYOP study and its participants in one request." }, "PublicCreateWithParticipantsResponse": { "properties": { "study": { "$ref": "#/components/schemas/PublicStudy" }, "participants": { "items": { "$ref": "#/components/schemas/PublicParticipant" }, "type": "array", "title": "Participants" } }, "type": "object", "required": [ "study", "participants" ], "title": "PublicCreateWithParticipantsResponse" }, "PublicCustomizeConceptImage": { "properties": { "data_base64": { "type": "string", "maxLength": 14000000, "minLength": 1, "title": "Data Base64", "description": "Base64-encoded image bytes (maximum decoded size: 10 MB)." }, "filename": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Filename" }, "content_type": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/gif", "image/webp" ], "title": "Content Type" }, "label": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Label", "description": "User-approved participant-facing label." } }, "additionalProperties": false, "type": "object", "required": [ "data_base64", "filename", "content_type", "label" ], "title": "PublicCustomizeConceptImage", "description": "A client-provided image attached to a Customize Plan turn." }, "PublicCustomizeStudyRequest": { "properties": { "message": { "type": "string", "maxLength": 20000, "minLength": 1, "title": "Message" }, "decisions": { "type": "string", "enum": [ "human", "agent" ], "title": "Decisions", "description": "human relays required decisions; agent makes reviewable assumptions when possible.", "default": "human" }, "execution_policy": { "type": "string", "enum": [ "review_before_fieldwork", "draft_only" ], "title": "Execution Policy", "description": "Caller workflow constraint, kept separate from participant-facing research content. This endpoint never launches recruitment.", "default": "review_before_fieldwork" }, "concept_image": { "anyOf": [ { "$ref": "#/components/schemas/PublicCustomizeConceptImage" }, { "type": "null" } ], "description": "Optional native concept-image attachment for this turn. The backend validates, stores, and makes it available to Customize Plan." } }, "additionalProperties": false, "type": "object", "required": [ "message" ], "title": "PublicCustomizeStudyRequest", "description": "One user turn for the stateful Customize Plan conversation." }, "PublicCustomizeStudyResponse": { "properties": { "message": { "type": "string", "title": "Message" }, "response_type": { "type": "string", "enum": [ "question", "message", "study_plan" ], "title": "Response Type" }, "questions": { "items": { "$ref": "#/components/schemas/PublicPlanningQuestion" }, "type": "array", "title": "Questions" }, "assumptions": { "items": { "type": "string" }, "type": "array", "title": "Assumptions" }, "execution_policy": { "type": "string", "enum": [ "review_before_fieldwork", "draft_only" ], "title": "Execution Policy", "default": "review_before_fieldwork" }, "study": { "$ref": "#/components/schemas/PublicStudySummary" } }, "type": "object", "required": [ "message", "response_type", "study" ], "title": "PublicCustomizeStudyResponse", "description": "The next Customize Plan message plus the study's resulting state." }, "PublicEvidenceCoverage": { "properties": { "text": { "type": "string", "title": "Text", "default": "" }, "sample_adequacy": { "anyOf": [ { "$ref": "#/components/schemas/SampleAdequacy" }, { "type": "null" } ] }, "learning_goal_evaluations": { "items": { "$ref": "#/components/schemas/GoalAssessment" }, "type": "array", "title": "Learning Goal Evaluations" }, "evidence_gaps": { "items": { "$ref": "#/components/schemas/PublicEvidenceGap" }, "type": "array", "title": "Evidence Gaps" } }, "type": "object", "title": "PublicEvidenceCoverage" }, "PublicEvidenceGap": { "properties": { "id": { "type": "string", "title": "Id" }, "priority": { "type": "integer", "title": "Priority" }, "title": { "type": "string", "title": "Title" }, "learning_goal_ids": { "items": { "type": "string" }, "type": "array", "title": "Learning Goal Ids" }, "finding_ids": { "items": { "type": "string" }, "type": "array", "title": "Finding Ids" }, "description": { "type": "string", "title": "Description" }, "decision_relevance": { "type": "string", "title": "Decision Relevance" }, "evidence_needed": { "type": "string", "title": "Evidence Needed", "default": "" }, "priority_rationale": { "type": "string", "title": "Priority Rationale", "default": "" }, "kind": { "type": "string", "enum": [ "research", "operational" ], "title": "Kind", "default": "research" }, "resolution_scope": { "type": "string", "enum": [ "same_plan_more_interviews", "new_study", "not_applicable" ], "title": "Resolution Scope", "default": "not_applicable" }, "required_changes": { "items": { "type": "string" }, "type": "array", "title": "Required Changes" }, "recommended_study_slug": { "anyOf": [ { "type": "string", "enum": [ "in-depth-interview", "concept-test", "prototype-test" ] }, { "type": "null" } ], "title": "Recommended Study Slug" }, "reference_ids": { "items": { "type": "string" }, "type": "array", "title": "Reference Ids" } }, "type": "object", "required": [ "id", "priority", "title", "description", "decision_relevance" ], "title": "PublicEvidenceGap" }, "PublicExternalPanelConfig": { "properties": { "provider": { "type": "string", "enum": [ "prolific", "cint", "cloudresearch", "terac", "custom" ], "title": "Provider", "default": "custom" }, "respondent_id_param": { "type": "string", "title": "Respondent Id Param", "default": "respondent_id" }, "respondent_id_placeholder": { "type": "string", "title": "Respondent Id Placeholder", "default": "{{RESPONDENT_ID}}" }, "session_id_param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id Param" }, "session_id_placeholder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id Placeholder" }, "external_study_id_param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Study Id Param" }, "external_study_id_placeholder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Study Id Placeholder" }, "complete_redirect_url": { "type": "string", "title": "Complete Redirect Url" }, "screenout_redirect_url": { "type": "string", "title": "Screenout Redirect Url" }, "quota_full_redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quota Full Redirect Url" }, "technical_redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Technical Redirect Url" }, "id": { "type": "string", "title": "Id" }, "study_id": { "type": "string", "title": "Study Id" }, "entry_url": { "type": "string", "title": "Entry Url" } }, "type": "object", "required": [ "complete_redirect_url", "screenout_redirect_url", "id", "study_id", "entry_url" ], "title": "PublicExternalPanelConfig" }, "PublicFeasibilityRequest": { "properties": { "id": { "type": "string", "title": "Id" }, "target_audience": { "type": "string", "title": "Target Audience" }, "country_code": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Country Code" }, "target": { "type": "integer", "title": "Target" }, "incident_rate": { "type": "number", "title": "Incident Rate" }, "study_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Id" }, "estimated_total_cost_per_interview_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Estimated Total Cost Per Interview Usd" }, "estimated_total_cost_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Estimated Total Cost Usd" }, "estimated_timeline_hours": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Estimated Timeline Hours" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "responded_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Responded At" }, "cancelled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Cancelled At" }, "expected_response_by": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expected Response By", "description": "Review deadline when one has been committed; null means no deadline has been set." }, "status": { "$ref": "#/components/schemas/FeasibilityRequestStatus" } }, "type": "object", "required": [ "id", "target_audience", "target", "incident_rate", "created_at", "status" ], "title": "PublicFeasibilityRequest" }, "PublicFeasibilityRequestCreate": { "properties": { "target_audience": { "type": "string", "minLength": 1, "title": "Target Audience", "description": "Description of the audience to recruit" }, "country_code": { "anyOf": [ { "items": { "type": "string", "enum": [ "AR", "AU", "AT", "BE", "BO", "BR", "CA", "CL", "CN", "CO", "CR", "CZ", "DK", "DO", "EC", "EG", "FI", "FR", "DE", "GR", "HK", "HU", "IN", "ID", "IE", "IT", "JP", "KE", "KR", "LU", "MY", "MX", "NL", "NZ", "NG", "NO", "PK", "PE", "PH", "PL", "PT", "RO", "RU", "SA", "SG", "SK", "ZA", "ES", "SE", "CH", "TW", "TH", "TR", "UG", "AE", "GB", "US", "VN" ] }, "type": "array" }, { "type": "null" } ], "title": "Country Code", "description": "Optional ISO 3166-1 alpha-2 country codes. Omit for no country restriction." }, "target": { "type": "integer", "exclusiveMinimum": 0.0, "title": "Target", "description": "Target number of completed interviews" }, "incident_rate": { "type": "number", "maximum": 100.0, "minimum": 0.0, "title": "Incident Rate", "description": "Expected audience incidence rate as percentage points (for example, 8.5 means 8.5%)." }, "study_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Id", "description": "Optional existing study ID" } }, "additionalProperties": false, "type": "object", "required": [ "target_audience", "target", "incident_rate" ], "title": "PublicFeasibilityRequestCreate" }, "PublicFeasibilityRequestList": { "properties": { "requests": { "items": { "$ref": "#/components/schemas/PublicFeasibilityRequest" }, "type": "array", "title": "Requests" }, "total_count": { "type": "integer", "title": "Total Count" }, "page": { "type": "integer", "title": "Page" }, "page_size": { "type": "integer", "title": "Page Size" } }, "type": "object", "required": [ "requests", "total_count", "page", "page_size" ], "title": "PublicFeasibilityRequestList" }, "PublicFieldingProgress": { "properties": { "study_id": { "type": "string", "title": "Study Id" }, "fielding_status": { "type": "string", "title": "Fielding Status" }, "completed": { "type": "integer", "title": "Completed", "description": "Qualifying completions in the current target cycle" }, "target": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Target", "description": "Current target; null when no target cycle exists" }, "quality_mix": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Quality Mix", "description": "Visible completed interviews by quality grade" }, "expected_finish_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expected Finish At", "description": "Rate-based UTC estimate; null until enough progress exists" } }, "type": "object", "required": [ "study_id", "fielding_status", "completed", "quality_mix" ], "title": "PublicFieldingProgress" }, "PublicFindingPrevalence": { "properties": { "n": { "type": "integer", "minimum": 0.0, "title": "N" }, "of": { "type": "integer", "minimum": 0.0, "title": "Of" } }, "type": "object", "required": [ "n", "of" ], "title": "PublicFindingPrevalence" }, "PublicFindingQuote": { "properties": { "text": { "type": "string", "title": "Text" }, "reference_id": { "type": "string", "title": "Reference Id" }, "interview_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Interview Id" }, "turn_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Turn Id" }, "start_s": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "null" } ], "title": "Start S" } }, "type": "object", "required": [ "text", "reference_id" ], "title": "PublicFindingQuote" }, "PublicInterview": { "properties": { "id": { "type": "string", "title": "Id" }, "study_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Id", "description": "The study this interview belongs to" }, "participant": { "anyOf": [ { "$ref": "#/components/schemas/PublicInterviewParticipant" }, { "type": "null" } ], "description": "null for synthetic, anonymous panel, external-panel, or open-link interviews" }, "participant_source": { "type": "string", "enum": [ "byop", "panel", "external_panel", "link", "synthetic", "unknown" ], "title": "Participant Source", "description": "Recruitment source; synthetic, anonymous panel and open-link respondents have no public person identity" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "quality": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quality", "description": "Quality rating: Excellent, Good, Fair, or Poor" }, "ended_because": { "anyOf": [ { "type": "string", "enum": [ "completed", "participant_left", "time_limit", "technical_error", "screened_out" ] }, { "type": "null" } ], "title": "Ended Because", "description": "Why the interview ended; null if the stored reason cannot be classified" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "Date and time the interview took place" }, "ended_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Ended At", "description": "Date and time the interview ended" }, "interview_format": { "anyOf": [ { "type": "string", "enum": [ "chat", "video", "voice" ] }, { "type": "null" } ], "title": "Interview Format", "description": "Stored interview mode; null when the historical mode is unknown" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language", "description": "Current configured study language, not a detected transcript language; historical interviews may have used an earlier configuration" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds", "description": "Interview length in seconds (ended_at - started_at)" }, "pii_redacted": { "type": "boolean", "title": "Pii Redacted", "description": "True when common structured identifiers were masked and direct identity/media links omitted; this does not guarantee all PII was detected", "default": false }, "messages": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicTranscriptSegment" }, "type": "array" }, { "type": "null" } ], "title": "Messages", "description": "Spoken segments (up to message_limit and about 20 KB). Each has id, role, message, text_offset, and start_s/end_s when stored timing exists." }, "total_message_segments": { "type": "integer", "title": "Total Message Segments", "default": 0 }, "next_message_offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Next Message Offset" }, "audio_recording_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audio Recording Url" }, "video_recording_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Video Recording Url" }, "screener_responses": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicScreenerResponse" }, "type": "array" }, { "type": "null" } ], "title": "Screener Responses", "description": "The participant's screener answers for this interview." } }, "type": "object", "required": [ "id", "participant_source" ], "title": "PublicInterview", "description": "Interview detail with bounded, paged speech segments." }, "PublicInterviewList": { "properties": { "interviews": { "items": { "$ref": "#/components/schemas/PublicInterviewSummary" }, "type": "array", "title": "Interviews" }, "total_count": { "type": "integer", "title": "Total Count" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page" }, "page_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page Size" } }, "type": "object", "required": [ "interviews", "total_count" ], "title": "PublicInterviewList" }, "PublicInterviewMode": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "description" ], "title": "PublicInterviewMode" }, "PublicInterviewParticipant": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "BYOP invitation ID, not a deduplicated person ID" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" } }, "type": "object", "title": "PublicInterviewParticipant" }, "PublicInterviewSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "study_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Id", "description": "The study this interview belongs to" }, "participant": { "anyOf": [ { "$ref": "#/components/schemas/PublicInterviewParticipant" }, { "type": "null" } ], "description": "null for synthetic, anonymous panel, external-panel, or open-link interviews" }, "participant_source": { "type": "string", "enum": [ "byop", "panel", "external_panel", "link", "synthetic", "unknown" ], "title": "Participant Source", "description": "Recruitment source; synthetic, anonymous panel and open-link respondents have no public person identity" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "quality": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quality", "description": "Quality rating: Excellent, Good, Fair, or Poor" }, "ended_because": { "anyOf": [ { "type": "string", "enum": [ "completed", "participant_left", "time_limit", "technical_error", "screened_out" ] }, { "type": "null" } ], "title": "Ended Because", "description": "Why the interview ended; null if the stored reason cannot be classified" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "Date and time the interview took place" }, "ended_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Ended At", "description": "Date and time the interview ended" }, "interview_format": { "anyOf": [ { "type": "string", "enum": [ "chat", "video", "voice" ] }, { "type": "null" } ], "title": "Interview Format", "description": "Stored interview mode; null when the historical mode is unknown" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language", "description": "Current configured study language, not a detected transcript language; historical interviews may have used an earlier configuration" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds", "description": "Interview length in seconds (ended_at - started_at)" } }, "type": "object", "required": [ "id", "participant_source" ], "title": "PublicInterviewSummary", "description": "Lightweight interview shape returned by the list endpoint (transcript,\nrecordings, and analysis are stripped \u2014 fetch by id to get them)." }, "PublicInterviewUsage": { "properties": { "total_interviews": { "type": "integer", "title": "Total Interviews" }, "total_units": { "type": "number", "title": "Total Units" }, "usage_stats": { "items": { "$ref": "#/components/schemas/PublicUsageBucket" }, "type": "array", "title": "Usage Stats" }, "scope": { "$ref": "#/components/schemas/UsageStatsScope" } }, "additionalProperties": false, "type": "object", "required": [ "total_interviews", "total_units", "usage_stats", "scope" ], "title": "PublicInterviewUsage" }, "PublicJob": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed" ], "title": "Status" }, "completed": { "type": "boolean", "title": "Completed", "description": "True when work has finished successfully" }, "result_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result Url", "description": "Fetch the created resource after success" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Requested participant count for a batch" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "A safe failure summary; internal details are never returned" } }, "type": "object", "required": [ "job_id", "status", "completed" ], "title": "PublicJob" }, "PublicLanguage": { "properties": { "code": { "type": "string", "title": "Code" }, "name": { "type": "string", "title": "Name" }, "native_name": { "type": "string", "title": "Native Name" } }, "additionalProperties": false, "type": "object", "required": [ "code", "name", "native_name" ], "title": "PublicLanguage" }, "PublicLearningGoal": { "properties": { "id": { "type": "string", "title": "Id" }, "question": { "type": "string", "title": "Question" }, "evidence_needed": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Evidence Needed", "description": "Evidence requirements; null for legacy plans that did not record them." } }, "type": "object", "required": [ "id", "question" ], "title": "PublicLearningGoal" }, "PublicLearningGoalFindings": { "properties": { "learning_goal_id": { "type": "string", "title": "Learning Goal Id" }, "learning_goal": { "type": "string", "title": "Learning Goal" }, "findings": { "items": { "$ref": "#/components/schemas/PublicStudyFinding" }, "type": "array", "title": "Findings" } }, "type": "object", "required": [ "learning_goal_id", "learning_goal" ], "title": "PublicLearningGoalFindings" }, "PublicPanelCountry": { "properties": { "code": { "type": "string", "title": "Code", "description": "Country code, e.g. US" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Country name" }, "language_options": { "items": { "$ref": "#/components/schemas/PublicCountryLanguage" }, "type": "array", "title": "Language Options" } }, "type": "object", "required": [ "code" ], "title": "PublicPanelCountry" }, "PublicPanelCreate": { "properties": { "target": { "type": "integer", "maximum": 1000.0, "exclusiveMinimum": 0.0, "title": "Target", "description": "Target number of completed responses (maximum 1,000 for direct launch; request feasibility for larger studies)" }, "incident_rate": { "type": "number", "maximum": 100.0, "minimum": 0.0, "title": "Incident Rate", "description": "Expected audience incidence rate as percentage points (10 means 10%). Rates below 10% require a feasibility request." }, "country_code": { "type": "string", "enum": [ "AR", "AU", "AT", "BE", "BO", "BR", "CA", "CL", "CN", "CO", "CR", "CZ", "DK", "DO", "EC", "EG", "FI", "FR", "DE", "GR", "HK", "HU", "IN", "ID", "IE", "IT", "JP", "KE", "KR", "LU", "MY", "MX", "NL", "NZ", "NG", "NO", "PK", "PE", "PH", "PL", "PT", "RO", "RU", "SA", "SG", "SK", "ZA", "ES", "SE", "CH", "TW", "TH", "TR", "UG", "AE", "GB", "US", "VN" ], "title": "Country Code", "description": "Target country (one of the supported countries). Required for every public Panel estimate and launch; no country is inferred." }, "frequency": { "type": "string", "enum": [ "one-time", "weekly", "monthly", "quarterly" ], "title": "Frequency", "description": "Recurring schedule, or one-time.", "default": "one-time" }, "targeting_attributes": { "items": { "$ref": "#/components/schemas/PublicPanelTargetingAttribute" }, "type": "array", "title": "Targeting Attributes", "description": "Optional launch-specific targets for single-select panel attributes. Each target must be a positive whole number; per-attribute totals may not exceed target; and an under-filled attribute must leave an option open." }, "dry_run": { "type": "boolean", "title": "Dry Run", "description": "Return a cost estimate without provisioning the panel", "default": false }, "estimate_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Estimate Id", "description": "Short-lived estimate identifier required for a paid launch; obtain it from estimatePanel" } }, "additionalProperties": false, "type": "object", "required": [ "target", "incident_rate", "country_code" ], "title": "PublicPanelCreate", "description": "Field a paid panel for a Panel-type study. The interview language is taken\nfrom the study (not set here)." }, "PublicPanelOptionTarget": { "properties": { "option_id": { "type": "integer", "title": "Option Id", "description": "Option id from GET /targeting-attributes" }, "target": { "type": "integer", "title": "Target", "description": "Fixed number of completed interviews for this option" } }, "additionalProperties": false, "type": "object", "required": [ "option_id", "target" ], "title": "PublicPanelOptionTarget", "description": "Playground-safe representation of one fixed option target." }, "PublicPanelResponse": { "properties": { "study_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Id" }, "panel_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Panel Status" }, "dry_run": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Dry Run" }, "target": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Target" }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country Code", "description": "Resolved ISO country code used for the estimate or launch." }, "language_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language Code", "description": "Resolved lowercase panel language code used for the estimate or launch." }, "estimated_total_cost_per_interview_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Estimated Total Cost Per Interview Usd", "description": "Per-interview cost in USD (interview credit cost + participant reward)." }, "estimated_total_cost_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Estimated Total Cost Usd", "description": "Total estimated cost in USD (per-interview \u00d7 target)." }, "estimated_timeline_hours": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Estimated Timeline Hours", "description": "Heuristic time to complete, in whole hours (rounded up); audience and country may change actual timing." }, "credit_cost_per_interview": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Credit Cost Per Interview" }, "total_credit_cost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Credit Cost" }, "available_credit_balance": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Available Credit Balance" }, "credit_deficit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Credit Deficit" }, "sufficient_credits": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Sufficient Credits" }, "reward_per_interview_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Reward Per Interview Usd" }, "card_hold_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Card Hold Usd" }, "frequency": { "anyOf": [ { "type": "string", "enum": [ "one-time", "weekly", "monthly", "quarterly" ] }, { "type": "null" } ], "title": "Frequency", "description": "Estimate applies to one cycle of this recurrence; later cycles may be repriced." }, "assumptions": { "items": { "type": "string" }, "type": "array", "title": "Assumptions" }, "estimate_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Estimate Id", "description": "Fingerprint of the study version, launch inputs, and current estimated price" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "Estimate expiry; request a new estimate after this time" } }, "type": "object", "title": "PublicPanelResponse", "description": "Either a launch acknowledgement (study_id + panel_status) or, for\n``dry_run``, a cost + timeline estimate." }, "PublicPanelStudyCreate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "title": "Name", "description": "Study display name (maximum 40 characters)" }, "study_type": { "type": "string", "enum": [ "in-depth-interview", "concept-test", "prototype-test" ], "title": "Study Type", "description": "Study-type template slug", "default": "in-depth-interview" }, "recruiting_method": { "anyOf": [ { "type": "string", "const": "panel" }, { "type": "null" } ], "enum": [ "panel" ], "title": "Recruiting Method", "description": "Must be panel when supplied." }, "interview_format": { "anyOf": [ { "type": "string", "enum": [ "chat", "video", "voice" ] }, { "type": "null" } ], "title": "Interview Format", "description": "chat, video, or voice" }, "voice": { "anyOf": [ { "type": "string", "enum": [ "male", "female" ] }, { "type": "null" } ], "title": "Voice", "description": "Interviewer voice: male (Elliot) or female (Clara)" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "enum": [ "auto", "af", "am", "ar", "as", "az", "bg", "bn", "bs", "ca", "cs", "cy", "da", "de", "el", "en", "es", "et", "eu", "fa", "fi", "fil", "fr", "ga", "gl", "gu", "he", "hi", "hr", "hu", "hy", "id", "is", "it", "iu", "ja", "jv", "ka", "kk", "km", "kn", "ko", "lo", "lt", "lv", "mk", "ml", "mn", "mr", "ms", "mt", "my", "nb", "ne", "nl", "or", "pa", "pl", "ps", "pt", "ro", "ru", "si", "sk", "sl", "so", "sq", "sr", "su", "sv", "sw", "ta", "te", "th", "tr", "uk", "ur", "uz", "vi", "wuu", "yue", "zh", "zu" ], "title": "Language", "description": "Interview language: an ISO 639-1 code, or 'auto' to auto-detect. Must be one of the supported options." }, "study_plan": { "anyOf": [ { "$ref": "#/components/schemas/PublicStudyPlan" }, { "type": "null" } ], "description": "Interview instructions as named sections." }, "expected_duration_seconds": { "anyOf": [ { "type": "integer", "minimum": 300.0 }, { "type": "null" } ], "title": "Expected Duration Seconds", "description": "Maximum planned interview duration in seconds, including all sections, transitions, and likely follow-up probes. Estimate this from the completed study plan; it is not a guaranteed participant completion time." }, "screener_questions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicScreenerQuestionInput" }, "type": "array" }, { "type": "null" } ], "title": "Screener Questions" }, "targeting_attributes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicTargetingAttribute" }, "type": "array" }, { "type": "null" } ], "title": "Targeting Attributes", "description": "Target the panel by demographic qualifications (panel studies)." } }, "additionalProperties": false, "type": "object", "title": "PublicPanelStudyCreate", "description": "Study fields for create-and-launch-panel \u2014 no incentive config (always a\npanel study, so incentives don't apply)." }, "PublicPanelTargetingAttribute": { "properties": { "qualification_id": { "type": "integer", "title": "Qualification Id", "description": "Qualification id from GET /targeting-attributes" }, "option_targets": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicPanelOptionTarget" }, "type": "array" }, { "additionalProperties": { "type": "integer" }, "type": "object" } ], "title": "Option Targets", "description": "Fixed interview targets. The playground uses [{option_id, target}]; direct API callers may also send an object keyed by option_id. Omitted options remain open." } }, "additionalProperties": false, "type": "object", "required": [ "qualification_id" ], "title": "PublicPanelTargetingAttribute", "description": "Launch-specific targets for qualifying options of one panel attribute.\n\n``qualification_id`` and the keys in ``option_targets`` come from the\ntargeting-attributes catalog. Options omitted from ``option_targets`` stay\nopen and share the remaining panel capacity." }, "PublicParticipant": { "properties": { "external_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "External Id", "description": "Customer ID, unique among active BYOP invitations in this study" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "Up to 20 scalar CRM fields and 4 KiB total" }, "id": { "type": "string", "title": "Id" }, "study_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Id", "description": "The study this participant belongs to" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "interview_link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Interview Link", "description": "Personal interview link for this invitation; usable when the study is provisioned and active" }, "status": { "type": "string", "enum": [ "created", "invited", "started", "completed", "screened_out" ], "title": "Status", "description": "Invitation and interview progress; created means no invitation email was sent" }, "interview_count": { "type": "integer", "title": "Interview Count", "description": "Visible non-test interview sessions for this invitation, not unique people", "default": 0 }, "reward_sent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Reward Sent" }, "reward_sent_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Reward Sent At" }, "invite_sent_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Invite Sent At", "description": "When this participant's invitation email was sent" }, "invite_created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Invite Created At", "description": "When this participant invitation was created" } }, "type": "object", "required": [ "id", "status" ], "title": "PublicParticipant", "description": "A BYOP invitation/participation record, not a deduplicated person.\n\nPanel recruiting is represented by the panel endpoints, not by synthetic\nparticipant records on this resource." }, "PublicParticipantInviteInput": { "properties": { "external_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "External Id", "description": "Customer ID, unique among active BYOP invitations in this study" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "Up to 20 scalar CRM fields and 4 KiB total" }, "email": { "type": "string", "format": "email", "title": "Email" }, "silent": { "type": "boolean", "title": "Silent", "description": "Create the participant without sending an invitation email", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "email" ], "title": "PublicParticipantInviteInput", "description": "One participant in a bulk participant creation request." }, "PublicParticipantLearningGoalResponse": { "properties": { "learning_goal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Learning Goal Id" }, "learning_goal_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Learning Goal Index" }, "learning_goal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Learning Goal" }, "assessment_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assessment State" }, "unavailability_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unavailability Reason" }, "explored": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Explored" }, "answered": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Answered" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "quote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quote" } }, "type": "object", "title": "PublicParticipantLearningGoalResponse" }, "PublicParticipantList": { "properties": { "participants": { "items": { "$ref": "#/components/schemas/PublicParticipant" }, "type": "array", "title": "Participants" }, "total_count": { "type": "integer", "title": "Total Count" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page" }, "page_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page Size" } }, "type": "object", "required": [ "participants", "total_count" ], "title": "PublicParticipantList" }, "PublicParticipantPatch": { "properties": { "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "title": "Email", "description": "New email, or null to clear the email" }, "external_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "External Id" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" } }, "additionalProperties": false, "type": "object", "title": "PublicParticipantPatch" }, "PublicParticipantProfileAnswer": { "properties": { "answer": { "type": "string", "title": "Answer" }, "participants": { "type": "integer", "minimum": 0.0, "title": "Participants" }, "percentage": { "type": "integer", "maximum": 100.0, "minimum": 0.0, "title": "Percentage" } }, "type": "object", "required": [ "answer", "participants", "percentage" ], "title": "PublicParticipantProfileAnswer" }, "PublicParticipantProfileSearchResult": { "properties": { "content_id": { "type": "string", "title": "Content Id" }, "report_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Report Id" }, "report_generated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Report Generated At" }, "research_period": { "anyOf": [ { "$ref": "#/components/schemas/PublicResearchPeriod" }, { "type": "null" } ], "description": "Start and end timestamps of interviews included in the indexed report; null for legacy or undated evidence" }, "content_type": { "type": "string", "const": "participant_profile", "title": "Content Type" }, "content": { "$ref": "#/components/schemas/PublicParticipantProfileSection" } }, "type": "object", "required": [ "content_id", "content_type", "content" ], "title": "PublicParticipantProfileSearchResult" }, "PublicParticipantProfileSection": { "properties": { "heading": { "type": "string", "title": "Heading" }, "content": { "items": { "$ref": "#/components/schemas/PublicParticipantProfileAnswer" }, "type": "array", "title": "Content" }, "reference_ids": { "items": { "type": "string" }, "type": "array", "title": "Reference Ids" } }, "type": "object", "required": [ "heading" ], "title": "PublicParticipantProfileSection" }, "PublicParticipantResponse": { "properties": { "interview_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Interview Id", "description": "Public interview record ID" }, "overall_takeaways": { "items": { "type": "string" }, "type": "array", "title": "Overall Takeaways" }, "learning_goal_responses": { "items": { "$ref": "#/components/schemas/PublicParticipantLearningGoalResponse" }, "type": "array", "title": "Learning Goal Responses" } }, "type": "object", "title": "PublicParticipantResponse" }, "PublicParticipantResponseSearchResult": { "properties": { "content_id": { "type": "string", "title": "Content Id" }, "report_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Report Id" }, "report_generated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Report Generated At" }, "research_period": { "anyOf": [ { "$ref": "#/components/schemas/PublicResearchPeriod" }, { "type": "null" } ], "description": "Start and end timestamps of interviews included in the indexed report; null for legacy or undated evidence" }, "content_type": { "type": "string", "const": "participant_response", "title": "Content Type" }, "interview_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Interview Id", "description": "Public interview ID to use with get_interview" }, "content": { "$ref": "#/components/schemas/PublicParticipantResponse" } }, "type": "object", "required": [ "content_id", "content_type", "content" ], "title": "PublicParticipantResponseSearchResult" }, "PublicParticipantUpdate": { "properties": { "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "title": "Email" } }, "additionalProperties": false, "type": "object", "title": "PublicParticipantUpdate" }, "PublicParticipantsCreate": { "properties": { "study_id": { "type": "string", "title": "Study Id", "description": "The study to invite these participants to" }, "participants": { "items": { "$ref": "#/components/schemas/PublicParticipantInviteInput" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Participants" } }, "additionalProperties": false, "type": "object", "required": [ "study_id", "participants" ], "title": "PublicParticipantsCreate", "description": "Create multiple participants for one study." }, "PublicPlanningQuestion": { "properties": { "id": { "type": "string", "title": "Id" }, "text": { "type": "string", "title": "Text" }, "options": { "items": { "type": "string" }, "type": "array", "title": "Options" }, "default": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default" } }, "type": "object", "required": [ "id", "text" ], "title": "PublicPlanningQuestion" }, "PublicRecommendedNextStep": { "properties": { "gap_ids": { "items": { "type": "string" }, "type": "array", "title": "Gap Ids" }, "action": { "type": "string", "title": "Action" }, "study_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Slug" }, "title": { "type": "string", "title": "Title" }, "rationale": { "type": "string", "title": "Rationale" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context" } }, "type": "object", "required": [ "action", "title", "rationale" ], "title": "PublicRecommendedNextStep" }, "PublicRecommendedNextStepSearchResult": { "properties": { "content_id": { "type": "string", "title": "Content Id" }, "report_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Report Id" }, "report_generated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Report Generated At" }, "research_period": { "anyOf": [ { "$ref": "#/components/schemas/PublicResearchPeriod" }, { "type": "null" } ], "description": "Start and end timestamps of interviews included in the indexed report; null for legacy or undated evidence" }, "content_type": { "type": "string", "const": "recommended_next_step", "title": "Content Type" }, "content": { "$ref": "#/components/schemas/PublicRecommendedNextStep" } }, "type": "object", "required": [ "content_id", "content_type", "content" ], "title": "PublicRecommendedNextStepSearchResult" }, "PublicReport": { "properties": { "schema_version": { "type": "string", "const": "report-v2", "title": "Schema Version", "default": "report-v2" }, "structure_status": { "type": "string", "enum": [ "structured", "legacy_partial" ], "title": "Structure Status", "description": "Whether learning-goal findings can be joined to the saved evidence snapshot", "default": "legacy_partial" }, "report_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Report Id", "description": "Persisted report ID" }, "study_id": { "type": "string", "title": "Study Id", "description": "The study this report was generated for" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "Short executive summary in overview responses" }, "summary_truncated": { "type": "boolean", "title": "Summary Truncated", "default": false }, "included_sections": { "items": { "type": "string" }, "type": "array", "title": "Included Sections" }, "available_sections": { "items": { "type": "string" }, "type": "array", "title": "Available Sections" }, "based_on_interview_ids_included": { "type": "boolean", "title": "Based On Interview Ids Included", "default": false }, "references": { "items": { "$ref": "#/components/schemas/PublicReportReference" }, "type": "array", "title": "References" }, "study_findings": { "$ref": "#/components/schemas/PublicStudyFindings" }, "participant_profiles": { "items": { "$ref": "#/components/schemas/PublicReportParticipantProfileSection" }, "type": "array", "title": "Participant Profiles", "description": "Participant-profile questions with stable question IDs and answer/count/percentage arrays" }, "participant_responses": { "items": { "$ref": "#/components/schemas/PublicParticipantResponse" }, "type": "array", "title": "Participant Responses" }, "evidence_coverage": { "$ref": "#/components/schemas/PublicEvidenceCoverage" }, "recommended_next_steps": { "items": { "$ref": "#/components/schemas/PublicRecommendedNextStep" }, "type": "array", "title": "Recommended Next Steps" }, "recommendation_status": { "type": "string", "enum": [ "available", "partial", "unavailable" ], "title": "Recommendation Status", "default": "unavailable" }, "interview_count": { "type": "integer", "title": "Interview Count", "description": "Number of interviews included in the report", "default": 0 }, "based_on_interview_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Based On Interview Ids", "description": "Interview IDs included in the saved report evidence; null when unavailable for a legacy report" }, "interview_count_basis": { "type": "string", "enum": [ "saved_evidence", "legacy_unverified" ], "title": "Interview Count Basis", "default": "legacy_unverified" }, "is_stale": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Stale", "description": "True if the report's inputs drifted since it was generated (regenerate to refresh); None = unknown" }, "stale_reason": { "anyOf": [ { "type": "string", "enum": [ "inputs_changed", "fingerprint_unavailable", "comparison_unavailable" ] }, { "type": "null" } ], "title": "Stale Reason" }, "new_interviews_since": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "New Interviews Since" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "study_id" ], "title": "PublicReport" }, "PublicReportParticipantProfileSection": { "properties": { "heading": { "type": "string", "title": "Heading" }, "content": { "items": { "$ref": "#/components/schemas/PublicParticipantProfileAnswer" }, "type": "array", "title": "Content" }, "reference_ids": { "items": { "type": "string" }, "type": "array", "title": "Reference Ids" }, "question_id": { "type": "string", "title": "Question Id", "description": "Stable identifier derived from the profile question heading" } }, "type": "object", "required": [ "heading", "question_id" ], "title": "PublicReportParticipantProfileSection" }, "PublicReportReference": { "properties": { "reference_id": { "type": "string", "title": "Reference Id", "description": "Citation id used in the report text" }, "interview_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Interview Id", "description": "The interview this reference quotes" }, "audio_recording_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audio Recording Url" }, "video_recording_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Video Recording Url" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "When the interview started" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds", "description": "Interview length in seconds" }, "message_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message Text", "description": "The quoted message text" }, "turn_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Turn Id", "description": "Transcript turn ID, when available" }, "start_s": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "null" } ], "title": "Start S", "description": "Seconds into the interview, when stored timing exists" } }, "type": "object", "required": [ "reference_id" ], "title": "PublicReportReference", "description": "A citation in the report, resolved to the interview + message it quotes." }, "PublicReportSection": { "properties": { "heading": { "type": "string", "title": "Heading" }, "content": { "type": "string", "title": "Content", "default": "" }, "reference_ids": { "items": { "type": "string" }, "type": "array", "title": "Reference Ids", "description": "Citation IDs that resolve through the report's references array" } }, "type": "object", "required": [ "heading" ], "title": "PublicReportSection" }, "PublicResearchPeriod": { "properties": { "start": { "type": "string", "format": "date-time", "title": "Start" }, "end": { "type": "string", "format": "date-time", "title": "End" } }, "type": "object", "required": [ "start", "end" ], "title": "PublicResearchPeriod" }, "PublicResearchSearchFilters": { "properties": { "study_ids": { "items": { "type": "string" }, "type": "array", "maxItems": 20, "minItems": 1, "title": "Study Ids" }, "content_types": { "anyOf": [ { "items": { "type": "string", "enum": [ "study_plan", "study_finding", "participant_profile", "participant_response", "recommended_next_step" ] }, "type": "array" }, { "type": "null" } ], "title": "Content Types" }, "research_date_from": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Research Date From", "description": "Include research whose interview period overlaps this UTC date or later; legacy undated records are excluded" }, "research_date_to": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Research Date To", "description": "Include research whose interview period overlaps this UTC date or earlier; legacy undated records are excluded" } }, "type": "object", "required": [ "study_ids" ], "title": "PublicResearchSearchFilters" }, "PublicResearchSearchRequest": { "properties": { "query": { "type": "string", "maxLength": 2000, "minLength": 1, "title": "Query" }, "filters": { "$ref": "#/components/schemas/PublicResearchSearchFilters" }, "limit": { "type": "integer", "maximum": 50.0, "minimum": 1.0, "title": "Limit", "default": 10 }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor", "description": "Reserved for future pagination. The first release accepts only null." } }, "type": "object", "required": [ "query", "filters" ], "title": "PublicResearchSearchRequest" }, "PublicResearchSearchResponse": { "properties": { "studies": { "items": { "$ref": "#/components/schemas/PublicResearchStudyResults" }, "type": "array", "title": "Studies" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "generated_content_returned": { "type": "boolean", "const": false, "title": "Generated Content Returned", "default": false } }, "type": "object", "title": "PublicResearchSearchResponse" }, "PublicResearchStudyResults": { "properties": { "study_id": { "type": "string", "title": "Study Id" }, "index_status": { "type": "string", "enum": [ "ready", "updating", "not_indexed" ], "title": "Index Status" }, "latest_report_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Report Id" }, "indexed_report_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Indexed Report Id" }, "results": { "items": { "anyOf": [ { "$ref": "#/components/schemas/PublicStudyPlanSearchResult" }, { "$ref": "#/components/schemas/PublicStudyFindingSearchResult" }, { "$ref": "#/components/schemas/PublicParticipantProfileSearchResult" }, { "$ref": "#/components/schemas/PublicParticipantResponseSearchResult" }, { "$ref": "#/components/schemas/PublicRecommendedNextStepSearchResult" } ] }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "study_id", "index_status" ], "title": "PublicResearchStudyResults" }, "PublicResolvedTargeting": { "properties": { "qualification_id": { "type": "integer", "title": "Qualification Id" }, "attribute": { "type": "string", "title": "Attribute" }, "include": { "items": { "type": "string" }, "type": "array", "title": "Include" }, "exclude": { "items": { "type": "string" }, "type": "array", "title": "Exclude" }, "applies_to": { "type": "string", "const": "panel", "title": "Applies To", "default": "panel" }, "active": { "type": "boolean", "title": "Active", "description": "False when the study is currently using invitation-based recruitment" }, "approximation_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approximation Note" } }, "type": "object", "required": [ "qualification_id", "attribute", "active" ], "title": "PublicResolvedTargeting" }, "PublicScreenerOption": { "properties": { "id": { "type": "string", "title": "Id" }, "text": { "type": "string", "title": "Text" }, "disqualify": { "type": "boolean", "title": "Disqualify" }, "selection_rule": { "anyOf": [ { "type": "string", "enum": [ "must_select", "may_select", "reject" ] }, { "type": "null" } ], "title": "Selection Rule", "description": "multi_select only. must_select requires the participant to select this option; may_select makes it optional; reject disqualifies the participant when selected." } }, "type": "object", "required": [ "id", "text", "disqualify" ], "title": "PublicScreenerOption" }, "PublicScreenerOptionInput": { "properties": { "text": { "type": "string", "title": "Text" }, "disqualify": { "type": "boolean", "title": "Disqualify", "default": false }, "selection_rule": { "anyOf": [ { "type": "string", "enum": [ "must_select", "may_select", "reject" ] }, { "type": "null" } ], "title": "Selection Rule", "description": "multi_select only. must_select requires the participant to select this option; may_select makes it optional; reject disqualifies the participant when selected." }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" } }, "additionalProperties": false, "type": "object", "required": [ "text" ], "title": "PublicScreenerOptionInput", "description": "Inbound screener option. ``id`` is auto-generated if omitted." }, "PublicScreenerQuestion": { "properties": { "id": { "type": "string", "title": "Id" }, "text": { "type": "string", "title": "Text" }, "type": { "type": "string", "enum": [ "single_select", "multi_select", "text_input" ], "title": "Type" }, "order": { "type": "integer", "title": "Order" }, "options": { "items": { "$ref": "#/components/schemas/PublicScreenerOption" }, "type": "array", "title": "Options" }, "input_mode": { "anyOf": [ { "type": "string", "enum": [ "integers_only", "unrestricted" ] }, { "type": "null" } ], "title": "Input Mode", "description": "text_input only. Which characters the field accepts." }, "numeric_ranges": { "anyOf": [ { "items": { "$ref": "#/components/schemas/NumericRange" }, "type": "array" }, { "type": "null" } ], "title": "Numeric Ranges", "description": "text_input + integers_only only. Optional minimum and/or maximum shown to the participant; empty/absent accepts any integer." } }, "type": "object", "required": [ "id", "text", "type", "order" ], "title": "PublicScreenerQuestion" }, "PublicScreenerQuestionInput": { "properties": { "text": { "type": "string", "title": "Text" }, "type": { "type": "string", "enum": [ "single_select", "multi_select", "text_input" ], "title": "Type", "default": "single_select" }, "options": { "items": { "$ref": "#/components/schemas/PublicScreenerOptionInput" }, "type": "array", "title": "Options" }, "order": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Order" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "input_mode": { "anyOf": [ { "type": "string", "enum": [ "integers_only", "unrestricted" ] }, { "type": "null" } ], "title": "Input Mode", "description": "text_input only. Which characters the field accepts." }, "numeric_ranges": { "anyOf": [ { "items": { "$ref": "#/components/schemas/NumericRange" }, "type": "array" }, { "type": "null" } ], "title": "Numeric Ranges", "description": "text_input + integers_only only. Optional minimum and/or maximum shown to the participant; empty/absent accepts any integer." } }, "additionalProperties": false, "type": "object", "required": [ "text" ], "title": "PublicScreenerQuestionInput", "description": "Inbound screener question. ``id``/``order`` are auto-generated if omitted.", "examples": [ { "options": [ { "selection_rule": "must_select", "text": "Required tool" }, { "selection_rule": "may_select", "text": "Optional tool" }, { "selection_rule": "reject", "text": "Disqualifying tool" } ], "text": "Which tools do you use?", "type": "multi_select" } ] }, "PublicScreenerResponse": { "properties": { "question": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Question", "description": "The screener question text" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type", "description": "single_select, multi_select, or text_input" }, "answer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Answer", "description": "The participant's answer (option text(s) or free text)" } }, "type": "object", "title": "PublicScreenerResponse" }, "PublicSearchStudyFinding": { "properties": { "heading": { "type": "string", "title": "Heading" }, "content": { "type": "string", "title": "Content", "default": "" }, "reference_ids": { "items": { "type": "string" }, "type": "array", "title": "Reference Ids", "description": "Citation IDs that resolve through the report's references array" }, "finding_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Finding Id" }, "learning_goal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Learning Goal Id" } }, "type": "object", "required": [ "heading" ], "title": "PublicSearchStudyFinding" }, "PublicStudy": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "title": "Name" }, "study_type": { "type": "string", "enum": [ "in-depth-interview", "concept-test", "prototype-test" ], "title": "Study Type", "description": "Current study-type template slug" }, "use_case": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Use Case", "description": "Historical study-type label when it is outside the current catalog" }, "recruiting_method": { "anyOf": [ { "type": "string", "enum": [ "panel", "byop", "synthetic_respondents" ] }, { "type": "null" } ], "enum": [ "panel", "byop", "synthetic_respondents" ], "title": "Recruiting Method", "description": "panel, byop, or synthetic_respondents" }, "interview_format": { "anyOf": [ { "type": "string", "enum": [ "chat", "video", "voice" ] }, { "type": "null" } ], "title": "Interview Format", "description": "chat, video, or voice" }, "voice": { "anyOf": [ { "type": "string", "enum": [ "male", "female" ] }, { "type": "null" } ], "title": "Voice", "description": "male or female" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language", "description": "Interview language code, e.g. 'en'" }, "expected_duration_seconds": { "type": "integer", "minimum": 300.0, "title": "Expected Duration Seconds", "description": "Maximum planned interview duration in seconds, including transitions and likely follow-up probes. This is an estimate, not a guaranteed length.", "default": 900 }, "byop_config": { "$ref": "#/components/schemas/PublicByopConfigOut" }, "study_link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Link", "description": "Live participant interview link; null until the interviewer is provisioned. This is not a researcher preview URL." }, "dashboard_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dashboard Url", "description": "Researcher management link for the study" }, "provisioning_status": { "type": "string", "enum": [ "draft", "ready", "provisioned" ], "title": "Provisioning Status", "description": "draft when required interviewer settings are missing, ready when the study can be provisioned, and provisioned when interviews can run" }, "fielding_status": { "type": "string", "enum": [ "not_started", "starting", "collecting", "fielding", "paused", "complete", "partial", "failed", "stopped", "unavailable", "not_applicable", "unknown" ], "title": "Fielding Status", "description": "Recruitment state, separate from interviewer provisioning. Panel studies report their persisted lifecycle. BYOP studies are collecting once the interviewer is provisioned, and can be paused or stopped; invitation delivery is tracked per participant. Synthetic respondents are not_applicable." }, "missing_requirements": { "items": { "type": "string" }, "type": "array", "title": "Missing Requirements", "description": "Fields still required before the study can be provisioned" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" }, "interview_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Interview Count", "description": "Completed visible non-test interviews satisfying quality criteria, matching list_interviews(status=completed)." }, "report_status": { "anyOf": [ { "type": "string", "enum": [ "available", "not_generated" ] }, { "type": "null" } ], "title": "Report Status" }, "study_plan": { "anyOf": [ { "$ref": "#/components/schemas/PublicStudyPlanOut" }, { "type": "null" } ] }, "screener_questions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicScreenerQuestion" }, "type": "array" }, { "type": "null" } ], "title": "Screener Questions" }, "targeting_attributes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicTargetingAttribute" }, "type": "array" }, { "type": "null" } ], "title": "Targeting Attributes" }, "resolved_targeting": { "items": { "$ref": "#/components/schemas/PublicResolvedTargeting" }, "type": "array", "title": "Resolved Targeting", "description": "Human-readable interpretation of the configured panel targeting" }, "concept_links": { "items": { "$ref": "#/components/schemas/PublicConceptLink" }, "type": "array", "title": "Concept Links" }, "concept_images": { "items": { "$ref": "#/components/schemas/PublicConceptImage" }, "type": "array", "title": "Concept Images" }, "invitation_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Invitation Count", "description": "Invitation records for this study. A panel launch may use one invitation for many participants." }, "interview_attempt_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Interview Attempt Count", "description": "Interview attempts, including attempts that did not yield a quality interview." }, "quality_interview_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Quality Interview Count", "description": "Interviews that passed the study quality criteria." } }, "type": "object", "required": [ "id", "study_type", "provisioning_status", "fielding_status" ], "title": "PublicStudy", "description": "Full study shape returned by get-by-id (includes the heavy fields)." }, "PublicStudyCreate": { "properties": { "name": { "type": "string", "maxLength": 40, "minLength": 1, "title": "Name" }, "study_type": { "type": "string", "enum": [ "in-depth-interview", "concept-test", "prototype-test" ], "title": "Study Type", "description": "Study-type template slug", "default": "in-depth-interview" }, "recruiting_method": { "type": "string", "enum": [ "panel", "byop", "synthetic_respondents" ], "title": "Recruiting Method" }, "interview_format": { "anyOf": [ { "type": "string", "enum": [ "chat", "video", "voice" ] }, { "type": "null" } ], "title": "Interview Format", "description": "chat, video, or voice. Defaults to chat and only accepts chat when recruiting_method is synthetic_respondents." }, "voice": { "anyOf": [ { "type": "string", "enum": [ "male", "female" ] }, { "type": "null" } ], "title": "Voice", "description": "Interviewer voice: male (Elliot) or female (Clara)" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "enum": [ "auto", "af", "am", "ar", "as", "az", "bg", "bn", "bs", "ca", "cs", "cy", "da", "de", "el", "en", "es", "et", "eu", "fa", "fi", "fil", "fr", "ga", "gl", "gu", "he", "hi", "hr", "hu", "hy", "id", "is", "it", "iu", "ja", "jv", "ka", "kk", "km", "kn", "ko", "lo", "lt", "lv", "mk", "ml", "mn", "mr", "ms", "mt", "my", "nb", "ne", "nl", "or", "pa", "pl", "ps", "pt", "ro", "ru", "si", "sk", "sl", "so", "sq", "sr", "su", "sv", "sw", "ta", "te", "th", "tr", "uk", "ur", "uz", "vi", "wuu", "yue", "zh", "zu" ], "title": "Language", "description": "Interview language: an ISO 639-1 code, or 'auto' to auto-detect. Must be one of the supported options." }, "study_plan": { "anyOf": [ { "$ref": "#/components/schemas/PublicStudyPlan" }, { "type": "null" } ], "description": "Interview instructions as named sections." }, "expected_duration_seconds": { "anyOf": [ { "type": "integer", "minimum": 300.0 }, { "type": "null" } ], "title": "Expected Duration Seconds", "description": "Maximum planned interview duration in seconds, including all sections, transitions, and likely follow-up probes. Estimate this from the completed study plan; it is not a guaranteed participant completion time." }, "screener_questions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicScreenerQuestionInput" }, "type": "array" }, { "type": "null" } ], "title": "Screener Questions" }, "targeting_attributes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicTargetingAttribute" }, "type": "array" }, { "type": "null" } ], "title": "Targeting Attributes", "description": "Target the panel by demographic qualifications (panel studies)." } }, "additionalProperties": false, "type": "object", "required": [ "name", "recruiting_method" ], "title": "PublicStudyCreate", "description": "Create a study. Unknown fields, including incentive settings, are rejected." }, "PublicStudyEditConflict": { "properties": { "detail": { "$ref": "#/components/schemas/PublicStudyEditConflictDetail" } }, "type": "object", "required": [ "detail" ], "title": "PublicStudyEditConflict" }, "PublicStudyEditConflictDetail": { "properties": { "code": { "type": "string", "const": "active_panel_must_be_paused_or_stopped", "title": "Code" }, "message": { "type": "string", "title": "Message" }, "actions": { "$ref": "#/components/schemas/PublicStudyLifecycleActions" } }, "type": "object", "required": [ "code", "message", "actions" ], "title": "PublicStudyEditConflictDetail" }, "PublicStudyEmbedCode": { "properties": { "type": { "type": "string", "enum": [ "widget", "button" ], "title": "Type" }, "code": { "type": "string", "title": "Code", "description": "Copy-ready HTML embed code" }, "study_link": { "type": "string", "title": "Study Link", "description": "Universal interview link used by the embed" } }, "type": "object", "required": [ "type", "code", "study_link" ], "title": "PublicStudyEmbedCode", "description": "Copy-ready HTML for embedding a study on another website." }, "PublicStudyFinding": { "properties": { "heading": { "type": "string", "title": "Heading" }, "content": { "type": "string", "title": "Content", "default": "" }, "reference_ids": { "items": { "type": "string" }, "type": "array", "title": "Reference Ids", "description": "Citation IDs that resolve through the report's references array" }, "finding_id": { "type": "string", "title": "Finding Id" }, "prevalence": { "anyOf": [ { "$ref": "#/components/schemas/PublicFindingPrevalence" }, { "type": "null" } ] }, "quotes": { "items": { "$ref": "#/components/schemas/PublicFindingQuote" }, "type": "array", "title": "Quotes" }, "supporting_evidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Supporting Evidence" }, "contrary_evidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contrary Evidence" }, "limitations": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Limitations" } }, "type": "object", "required": [ "heading", "finding_id" ], "title": "PublicStudyFinding" }, "PublicStudyFindingSearchResult": { "properties": { "content_id": { "type": "string", "title": "Content Id" }, "report_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Report Id" }, "report_generated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Report Generated At" }, "research_period": { "anyOf": [ { "$ref": "#/components/schemas/PublicResearchPeriod" }, { "type": "null" } ], "description": "Start and end timestamps of interviews included in the indexed report; null for legacy or undated evidence" }, "content_type": { "type": "string", "const": "study_finding", "title": "Content Type" }, "content": { "$ref": "#/components/schemas/PublicSearchStudyFinding" } }, "type": "object", "required": [ "content_id", "content_type", "content" ], "title": "PublicStudyFindingSearchResult" }, "PublicStudyFindings": { "properties": { "executive_summary": { "anyOf": [ { "$ref": "#/components/schemas/PublicReportSection" }, { "type": "null" } ] }, "key_metrics": { "anyOf": [ { "$ref": "#/components/schemas/PublicReportSection" }, { "type": "null" } ] }, "learning_goals": { "items": { "$ref": "#/components/schemas/PublicLearningGoalFindings" }, "type": "array", "title": "Learning Goals" }, "additional_observations": { "anyOf": [ { "$ref": "#/components/schemas/PublicReportSection" }, { "type": "null" } ] }, "other_sections": { "items": { "$ref": "#/components/schemas/PublicReportSection" }, "type": "array", "title": "Other Sections" } }, "type": "object", "title": "PublicStudyFindings" }, "PublicStudyLifecycleAction": { "properties": { "method": { "type": "string", "const": "POST", "title": "Method" }, "endpoint": { "type": "string", "title": "Endpoint" }, "documentation_url": { "type": "string", "title": "Documentation Url" } }, "type": "object", "required": [ "method", "endpoint", "documentation_url" ], "title": "PublicStudyLifecycleAction", "description": "A public API action offered to resolve a study lifecycle conflict." }, "PublicStudyLifecycleActions": { "properties": { "pause": { "$ref": "#/components/schemas/PublicStudyLifecycleAction" }, "stop": { "$ref": "#/components/schemas/PublicStudyLifecycleAction" } }, "type": "object", "required": [ "pause", "stop" ], "title": "PublicStudyLifecycleActions" }, "PublicStudyList": { "properties": { "studies": { "items": { "$ref": "#/components/schemas/PublicStudySummary" }, "type": "array", "title": "Studies" }, "total_count": { "type": "integer", "title": "Total Count" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page" }, "page_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page Size" } }, "type": "object", "required": [ "studies", "total_count" ], "title": "PublicStudyList" }, "PublicStudyPlan": { "properties": { "objectives": { "type": "string", "title": "Objectives", "description": "What the study is trying to learn and the decision it informs." }, "conversation_flow": { "type": "string", "title": "Conversation Flow", "description": "How the interview should flow \u2014 topics/clusters with example prompts." }, "background": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Background", "description": "Context about the company/product/market." }, "learning_goals": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Learning Goals", "description": "Answerable questions as ### Learning goal N: headings, each followed by **Evidence needed:** requirements." }, "study_specific_rules": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Specific Rules", "description": "Operational guardrails and neutrality notes." }, "study_improvements": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Improvements", "description": "Accepted additions to guide future interviews." } }, "additionalProperties": false, "type": "object", "required": [ "objectives", "conversation_flow" ], "title": "PublicStudyPlan", "description": "The interview instructions, as named sections. ``objectives`` and\n``conversation_flow`` are required; the rest are optional. Each value is\nfree-form text/markdown (bullets allowed)." }, "PublicStudyPlanOut": { "properties": { "objectives": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Objectives" }, "conversation_flow": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Flow" }, "background": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Background" }, "learning_goals": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Learning Goals" }, "learning_goals_structured": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicLearningGoal" }, "type": "array" }, { "type": "null" } ], "title": "Learning Goals Structured", "description": "Stable goals whose IDs match report learning_goal_id values. Older plans also return goal IDs; evidence_needed is null if no requirements were recorded." }, "study_specific_rules": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Specific Rules" }, "study_improvements": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Improvements" } }, "type": "object", "title": "PublicStudyPlanOut", "description": "Response variant \u2014 all sections optional (a study's stored prompt may not\ncontain every section)." }, "PublicStudyPlanSearchResult": { "properties": { "content_id": { "type": "string", "title": "Content Id" }, "report_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Report Id" }, "report_generated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Report Generated At" }, "research_period": { "anyOf": [ { "$ref": "#/components/schemas/PublicResearchPeriod" }, { "type": "null" } ], "description": "Start and end timestamps of interviews included in the indexed report; null for legacy or undated evidence" }, "content_type": { "type": "string", "const": "study_plan", "title": "Content Type" }, "content": { "$ref": "#/components/schemas/PublicStudyPlanOut" } }, "type": "object", "required": [ "content_id", "content_type", "content" ], "title": "PublicStudyPlanSearchResult" }, "PublicStudySummary": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "title": "Name" }, "study_type": { "type": "string", "enum": [ "in-depth-interview", "concept-test", "prototype-test" ], "title": "Study Type", "description": "Current study-type template slug" }, "use_case": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Use Case", "description": "Historical study-type label when it is outside the current catalog" }, "recruiting_method": { "anyOf": [ { "type": "string", "enum": [ "panel", "byop", "synthetic_respondents" ] }, { "type": "null" } ], "enum": [ "panel", "byop", "synthetic_respondents" ], "title": "Recruiting Method", "description": "panel, byop, or synthetic_respondents" }, "interview_format": { "anyOf": [ { "type": "string", "enum": [ "chat", "video", "voice" ] }, { "type": "null" } ], "title": "Interview Format", "description": "chat, video, or voice" }, "voice": { "anyOf": [ { "type": "string", "enum": [ "male", "female" ] }, { "type": "null" } ], "title": "Voice", "description": "male or female" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language", "description": "Interview language code, e.g. 'en'" }, "expected_duration_seconds": { "type": "integer", "minimum": 300.0, "title": "Expected Duration Seconds", "description": "Maximum planned interview duration in seconds, including transitions and likely follow-up probes. This is an estimate, not a guaranteed length.", "default": 900 }, "byop_config": { "$ref": "#/components/schemas/PublicByopConfigOut" }, "study_link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Link", "description": "Live participant interview link; null until the interviewer is provisioned. This is not a researcher preview URL." }, "dashboard_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dashboard Url", "description": "Researcher management link for the study" }, "provisioning_status": { "type": "string", "enum": [ "draft", "ready", "provisioned" ], "title": "Provisioning Status", "description": "draft when required interviewer settings are missing, ready when the study can be provisioned, and provisioned when interviews can run" }, "fielding_status": { "type": "string", "enum": [ "not_started", "starting", "collecting", "fielding", "paused", "complete", "partial", "failed", "stopped", "unavailable", "not_applicable", "unknown" ], "title": "Fielding Status", "description": "Recruitment state, separate from interviewer provisioning. Panel studies report their persisted lifecycle. BYOP studies are collecting once the interviewer is provisioned, and can be paused or stopped; invitation delivery is tracked per participant. Synthetic respondents are not_applicable." }, "missing_requirements": { "items": { "type": "string" }, "type": "array", "title": "Missing Requirements", "description": "Fields still required before the study can be provisioned" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" }, "interview_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Interview Count", "description": "Completed visible non-test interviews satisfying quality criteria, matching list_interviews(status=completed)." }, "report_status": { "anyOf": [ { "type": "string", "enum": [ "available", "not_generated" ] }, { "type": "null" } ], "title": "Report Status" } }, "type": "object", "required": [ "id", "study_type", "provisioning_status", "fielding_status" ], "title": "PublicStudySummary", "description": "Lightweight study shape returned by the list endpoint (heavy fields such\nas the study plan and screener questions are stripped \u2014 fetch by id)." }, "PublicStudyType": { "properties": { "id": { "type": "string", "title": "Id" }, "slug": { "type": "string", "title": "Slug" }, "title": { "type": "string", "title": "Title" }, "description": { "type": "string", "title": "Description" }, "example_question": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Example Question" } }, "additionalProperties": false, "type": "object", "required": [ "id", "slug", "title", "description" ], "title": "PublicStudyType" }, "PublicStudyTypeList": { "properties": { "study_types": { "items": { "$ref": "#/components/schemas/PublicStudyType" }, "type": "array", "title": "Study Types" }, "total_count": { "type": "integer", "title": "Total Count" }, "page": { "type": "integer", "title": "Page" }, "page_size": { "type": "integer", "title": "Page Size" }, "recommended_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recommended Slug" } }, "additionalProperties": false, "type": "object", "required": [ "study_types", "total_count", "page", "page_size" ], "title": "PublicStudyTypeList" }, "PublicStudyUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "title": "Name", "description": "Study display name (maximum 40 characters)" }, "study_type": { "type": "string", "enum": [ "in-depth-interview", "concept-test", "prototype-test" ], "title": "Study Type", "description": "Study-type template slug", "default": "in-depth-interview" }, "recruiting_method": { "anyOf": [ { "type": "string", "enum": [ "panel", "byop", "synthetic_respondents" ] }, { "type": "null" } ], "enum": [ "panel", "byop", "synthetic_respondents" ], "title": "Recruiting Method", "description": "panel (recruit from the panel), byop (bring your own participants), or synthetic_respondents (AI respondents; chat interviews only)" }, "interview_format": { "anyOf": [ { "type": "string", "enum": [ "chat", "video", "voice" ] }, { "type": "null" } ], "title": "Interview Format", "description": "chat, video, or voice. Defaults to chat and only accepts chat when recruiting_method is synthetic_respondents." }, "voice": { "anyOf": [ { "type": "string", "enum": [ "male", "female" ] }, { "type": "null" } ], "title": "Voice", "description": "Interviewer voice: male (Elliot) or female (Clara)" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "enum": [ "auto", "af", "am", "ar", "as", "az", "bg", "bn", "bs", "ca", "cs", "cy", "da", "de", "el", "en", "es", "et", "eu", "fa", "fi", "fil", "fr", "ga", "gl", "gu", "he", "hi", "hr", "hu", "hy", "id", "is", "it", "iu", "ja", "jv", "ka", "kk", "km", "kn", "ko", "lo", "lt", "lv", "mk", "ml", "mn", "mr", "ms", "mt", "my", "nb", "ne", "nl", "or", "pa", "pl", "ps", "pt", "ro", "ru", "si", "sk", "sl", "so", "sq", "sr", "su", "sv", "sw", "ta", "te", "th", "tr", "uk", "ur", "uz", "vi", "wuu", "yue", "zh", "zu" ], "title": "Language", "description": "Interview language: an ISO 639-1 code, or 'auto' to auto-detect. Must be one of the supported options." }, "study_plan": { "anyOf": [ { "$ref": "#/components/schemas/PublicStudyPlan" }, { "type": "null" } ], "description": "Interview instructions as named sections." }, "expected_duration_seconds": { "anyOf": [ { "type": "integer", "minimum": 300.0 }, { "type": "null" } ], "title": "Expected Duration Seconds", "description": "Maximum planned interview duration in seconds, including all sections, transitions, and likely follow-up probes. Estimate this from the completed study plan; it is not a guaranteed participant completion time." }, "screener_questions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicScreenerQuestionInput" }, "type": "array" }, { "type": "null" } ], "title": "Screener Questions" }, "targeting_attributes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicTargetingAttribute" }, "type": "array" }, { "type": "null" } ], "title": "Targeting Attributes", "description": "Target the panel by demographic qualifications (panel studies)." }, "byop_config": { "anyOf": [ { "$ref": "#/components/schemas/PublicByopConfig" }, { "type": "null" } ], "description": "Incentive settings (BYOP only)." } }, "additionalProperties": false, "type": "object", "title": "PublicStudyUpdate", "description": "Update a study (PATCH semantics \u2014 only provided fields change)." }, "PublicTargetingAttribute": { "properties": { "qualification_id": { "type": "integer", "title": "Qualification Id", "description": "Qualification id (from GET /targeting-attributes)" }, "allowed_options": { "items": { "type": "integer" }, "type": "array", "title": "Allowed Options", "description": "option_ids to allow" }, "disallowed_options": { "items": { "type": "integer" }, "type": "array", "title": "Disallowed Options", "description": "option_ids to disqualify" } }, "additionalProperties": false, "type": "object", "required": [ "qualification_id" ], "title": "PublicTargetingAttribute", "description": "Target the panel by a qualification's answer options. Option-id rules:\n- both lists empty \u2192 allow all options;\n- only allowed \u2192 disqualify any option not listed;\n- only disallowed \u2192 allow any option not listed (can't disallow them all);\n- both \u2192 allowed are kept, disallowed are disqualified, and together they\n must cover every option_id of the qualification.\nLook up qualification_id / option_id via GET /targeting-attributes." }, "PublicTargetingAttributeCatalog": { "properties": { "qualification_id": { "type": "integer", "title": "Qualification Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "description": "Filterable catalog category, such as Demographics or Financial" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type", "description": "Question input type used for this targeting attribute" }, "question_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Question Text" }, "options": { "items": { "$ref": "#/components/schemas/PublicTargetingOptionCatalog" }, "type": "array", "title": "Options" } }, "type": "object", "required": [ "qualification_id" ], "title": "PublicTargetingAttributeCatalog", "description": "One qualification in the targeting catalog (GET /targeting-attributes)." }, "PublicTargetingOptionCatalog": { "properties": { "option_id": { "type": "integer", "title": "Option Id" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text" } }, "type": "object", "required": [ "option_id" ], "title": "PublicTargetingOptionCatalog" }, "PublicTranscriptSegment": { "properties": { "id": { "type": "string", "title": "Id", "description": "Original transcript turn ID; split segments retain the same ID" }, "role": { "type": "string", "enum": [ "participant", "moderator" ], "title": "Role" }, "message": { "type": "string", "title": "Message" }, "text_offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Text Offset", "description": "Character offset within the original turn" }, "start_s": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Start S", "description": "Stored seconds from interview start" }, "end_s": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "End S", "description": "Stored seconds from interview start" } }, "additionalProperties": false, "type": "object", "required": [ "id", "role", "message" ], "title": "PublicTranscriptSegment" }, "PublicUsageBucket": { "properties": { "date": { "type": "string", "format": "date", "title": "Date" }, "interviews": { "type": "integer", "title": "Interviews", "default": 0 }, "audio_interviews": { "type": "integer", "title": "Audio Interviews", "default": 0 }, "video_interviews": { "type": "integer", "title": "Video Interviews", "default": 0 }, "chat_interviews": { "type": "integer", "title": "Chat Interviews", "default": 0 }, "synthetic_respondents": { "type": "integer", "title": "Synthetic Respondents", "default": 0 }, "units": { "type": "number", "title": "Units", "default": 0 } }, "additionalProperties": false, "type": "object", "required": [ "date" ], "title": "PublicUsageBucket" }, "PublicVoiceChoice": { "properties": { "voice": { "type": "string", "title": "Voice" }, "name": { "type": "string", "title": "Name" } }, "additionalProperties": false, "type": "object", "required": [ "voice", "name" ], "title": "PublicVoiceChoice" }, "SampleAdequacy": { "properties": { "supports": { "type": "string", "minLength": 1, "title": "Supports" }, "limits": { "type": "string", "minLength": 1, "title": "Limits" }, "additional_interviews": { "type": "string", "enum": [ "recommended", "not_prioritized", "conditional" ], "title": "Additional Interviews" }, "rationale": { "type": "string", "minLength": 1, "title": "Rationale" } }, "type": "object", "required": [ "supports", "limits", "additional_interviews", "rationale" ], "title": "SampleAdequacy" }, "TremendousRewardResponse": { "properties": { "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" } }, "type": "object", "required": [ "status", "message" ], "title": "TremendousRewardResponse", "description": "Response data returned after sending a Tremendous reward." }, "UsageStatsScope": { "properties": { "app_id": { "type": "string", "title": "App Id", "description": "Resolved app used for this query" }, "start_date": { "type": "string", "format": "date", "title": "Start Date", "description": "Inclusive start date in UTC" }, "end_date": { "type": "string", "format": "date", "title": "End Date", "description": "Inclusive end date in UTC" }, "cadence": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "title": "Cadence" } }, "type": "object", "required": [ "app_id", "start_date", "end_date", "cadence" ], "title": "UsageStatsScope" }, "Webhook": { "properties": { "id": { "type": "string", "title": "Id" }, "hook_url": { "type": "string", "title": "Hook Url" }, "study_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Id" }, "event_types": { "items": { "type": "string" }, "type": "array", "title": "Event Types" }, "signing_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signing Secret", "description": "HMAC secret for verifying delivery signatures. Returned at creation and on a same-key retry within 30 days while current; store it securely" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "id", "hook_url" ], "title": "Webhook" }, "WebhookCreate": { "properties": { "hook_url": { "type": "string", "title": "Hook Url", "description": "HTTPS URL to receive completed-interview data" }, "study_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Id", "description": "Limit delivery to one study; omit for all studies in the account" }, "event_types": { "items": { "type": "string", "enum": [ "interview.completed", "study.completed", "report.ready", "study.paused", "study.resumed", "study.stopped" ] }, "type": "array", "maxItems": 6, "minItems": 1, "title": "Event Types", "description": "Events to deliver to this URL" } }, "additionalProperties": false, "type": "object", "required": [ "hook_url" ], "title": "WebhookCreate" }, "WebhookDelete": { "properties": { "hook_url": { "type": "string", "title": "Hook Url" } }, "additionalProperties": false, "type": "object", "required": [ "hook_url" ], "title": "WebhookDelete" }, "WebhookDeliveryAttempt": { "properties": { "id": { "type": "string", "title": "Id" }, "event_type": { "type": "string", "title": "Event Type" }, "attempted_at": { "type": "string", "format": "date-time", "title": "Attempted At" }, "status_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Status Code" }, "success": { "type": "boolean", "title": "Success" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Code" }, "duration_ms": { "type": "integer", "title": "Duration Ms" } }, "type": "object", "required": [ "id", "event_type", "attempted_at", "success", "duration_ms" ], "title": "WebhookDeliveryAttempt" }, "WebhookDeliveryAttemptList": { "properties": { "attempts": { "items": { "$ref": "#/components/schemas/WebhookDeliveryAttempt" }, "type": "array", "title": "Attempts" }, "total_count": { "type": "integer", "title": "Total Count" }, "page": { "type": "integer", "title": "Page" }, "page_size": { "type": "integer", "title": "Page Size" } }, "type": "object", "required": [ "attempts", "total_count", "page", "page_size" ], "title": "WebhookDeliveryAttemptList" }, "WebhookList": { "properties": { "webhooks": { "items": { "$ref": "#/components/schemas/Webhook" }, "type": "array", "title": "Webhooks" }, "total_count": { "type": "integer", "title": "Total Count" } }, "type": "object", "required": [ "webhooks", "total_count" ], "title": "WebhookList" }, "WebhookTestResult": { "properties": { "success": { "type": "boolean", "title": "Success" }, "status_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Status Code" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Code" } }, "type": "object", "required": [ "success" ], "title": "WebhookTestResult" }, "PublicApiError": { "type": "object", "required": [ "code", "message", "field", "request_id", "outcome", "recovery_action", "docs_url" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request_id": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "not_started", "failed", "unknown" ] }, "recovery_action": { "type": "string" }, "docs_url": { "type": "string", "format": "uri" } } }, "PublicApiErrorResponse": { "type": "object", "required": [ "detail", "error" ], "properties": { "detail": { "description": "Legacy error detail; may be a string, list, or object." }, "error": { "$ref": "#/components/schemas/PublicApiError" } } }, "PublicCustomizeStudyJob": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed" ], "title": "Status" }, "completed": { "type": "boolean", "title": "Completed", "description": "True when work has finished successfully" }, "result_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result Url", "description": "Fetch the created resource after success" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Requested participant count for a batch" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "A safe failure summary; internal details are never returned" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/PublicCustomizeStudyResponse" }, { "type": "null" } ], "description": "The completed planning turn; null until the job succeeds" } }, "type": "object", "required": [ "job_id", "status", "completed" ], "title": "PublicCustomizeStudyJob" }, "PublicInterviewExportJob": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed" ], "title": "Status" }, "completed": { "type": "boolean", "title": "Completed", "description": "True when work has finished successfully" }, "result_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result Url", "description": "Fetch the created resource after success" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Requested participant count for a batch" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "A safe failure summary; internal details are never returned" }, "format": { "type": "string", "enum": [ "csv", "jsonl" ], "title": "Format" }, "record_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Record Count" }, "next_page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Next Page" }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Download Url", "description": "Private signed URL, valid for 15 minutes after polling a successful job" }, "pii_redacted": { "type": "boolean", "title": "Pii Redacted", "description": "Whether common structured identifiers were masked" } }, "type": "object", "required": [ "job_id", "status", "completed", "format", "pii_redacted" ], "title": "PublicInterviewExportJob" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Authenticate with an API key (prefixed `ui_sk_`) or a JWT token from the dashboard." } } } }