{ "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 — 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" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Page Size" } }, { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by name", "title": "Name" }, "description": "Filter by name" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudyList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "public-studies" ], "summary": "Create Study", "operationId": "createStudy", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudyCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudy" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/public/v1/studies/create-and-launch-panel": { "post": { "tags": [ "public-studies" ], "summary": "Create Study And Launch Panel", "description": "Create a study and immediately launch a panel for it, in one call. The study\nis created as a Panel study and the panel uses the study's interview language.\nSet ``panel.dry_run`` to get a cost estimate without creating or fielding anything.", "operationId": "createStudyAndLaunchPanel", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCreateAndLaunch" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCreateAndLaunchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/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" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudy" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "public-studies" ], "summary": "Replace Study", "description": "Replace a study (RESTful PUT): the body is the full new state — fields you\nomit are cleared.", "operationId": "replaceStudy", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudyUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudy" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "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" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudyUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudy" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "public-studies" ], "summary": "Delete Study", "operationId": "deleteStudy", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudy" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/public/v1/studies/{study_id}/pause": { "post": { "tags": [ "public-studies" ], "summary": "Pause Study", "description": "Pause a study (stops fielding; cancels active panel surveys and settles holds).", "operationId": "pauseStudy", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudy" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/public/v1/studies/{study_id}/resume": { "post": { "tags": [ "public-studies" ], "summary": "Resume Study", "description": "Resume a paused study (relaunches the panel for the remaining target).", "operationId": "resumeStudy", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStudy" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/public/v1/studies/{study_id}/report": { "post": { "tags": [ "public-studies" ], "summary": "Generate Report", "description": "Analyze the study's interview transcripts and return the report.", "operationId": "generateStudyReport", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicReport" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "public-studies" ], "summary": "Get Report", "operationId": "getStudyReport", "parameters": [ { "name": "study_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Study Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicReport" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/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" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPanelCreate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPanelResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/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" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 10, "title": "Page Size" } }, { "name": "study_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by study", "title": "Study Id" }, "description": "Filter by study" }, { "name": "email", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by email", "title": "Email" }, "description": "Filter by email" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicParticipantList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "public-participants" ], "summary": "Create Participant", "operationId": "createParticipant", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicParticipantCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicParticipant" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/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" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicParticipant" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "public-participants" ], "summary": "Update Participant", "operationId": "updateParticipant", "parameters": [ { "name": "participant_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Participant Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicParticipantUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicParticipant" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "public-participants" ], "summary": "Delete Participant", "operationId": "deleteParticipant", "parameters": [ { "name": "participant_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Participant Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/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" } } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/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" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 10, "title": "Page Size" } }, { "name": "study_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by study", "title": "Study Id" }, "description": "Filter by study" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by interview status", "title": "Status" }, "description": "Filter by interview status" }, { "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)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicInterviewList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/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" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicInterview" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/public/v1/webhooks/": { "post": { "tags": [ "public-webhooks" ], "summary": "Create Webhook", "description": "Register an account-wide webhook. When **any** interview in your account is completed, a `POST` request is sent to your `hook_url` containing the completed interview in the public API shape — `study_id`, the `participant`, `status`, `quality`, `messages`, recording links, and screener responses (the same shape returned by `GET /interviews/{interview_id}`).\n\nWebhooks are not scoped to a single study — you do not pass a `study_id`. The response includes a `signing_secret` (shown **once**): every delivery is signed with it via an `X-UI-Signature` header (HMAC-SHA256 of `\".\"`), so your endpoint can verify the request is genuine. See [Webhooks](/api-reference/webhooks/overview) for the full payload schema, signature verification, and delivery behavior.", "operationId": "createWebhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "public-webhooks" ], "summary": "Delete Webhook", "description": "Remove a previously registered webhook. Provide the `hook_url` that was used when the webhook was created. After deletion, completed interviews no longer send requests to that URL. See [Webhooks](/api-reference/webhooks/overview) for details.", "operationId": "deleteWebhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelete" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/public/v1/targeting-attributes/": { "get": { "tags": [ "public-targeting" ], "summary": "List Targeting Attributes", "description": "Catalog of panel targeting attributes (qualifications + their answer options).", "operationId": "listTargetingAttributes", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PublicTargetingAttributeCatalog" }, "type": "array", "title": "Response Listtargetingattributes" } } } } } } }, "/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)", "title": "Language" }, "description": "Filter to countries that support this language (e.g. 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)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicPanelCountry" }, "title": "Response Listpanelcountries" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "Webhook": { "properties": { "id": { "type": "string", "title": "Id" }, "hook_url": { "type": "string", "title": "Hook Url" }, "signing_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signing Secret", "description": "HMAC secret for verifying delivery signatures. Returned once, at creation — store it securely; it is never shown again." }, "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": "Webhook URL to receive completed-interview data for every study in your account" } }, "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" }, "PublicByopConfig": { "properties": { "incentive_amount": { "anyOf": [ { "type": "number", "maximum": 401, "minimum": 5 }, { "type": "null" } ], "title": "Incentive Amount", "description": "Per-participant incentive in USD ($5–$400)." }, "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" }, "PublicCountryLanguage": { "properties": { "code": { "type": "string", "title": "Code", "description": "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": "Create a study and immediately field a panel for it. The study is always\ncreated as a Panel study (recruiting_method is forced to ``panel``; incentives\ndon't apply). Set ``panel.dry_run`` to get a cost estimate without creating or\nfielding anything." }, "PublicCreateAndLaunchResponse": { "properties": { "study": { "anyOf": [ { "$ref": "#/components/schemas/PublicStudy" }, { "type": "null" } ] }, "panel": { "$ref": "#/components/schemas/PublicPanelResponse" } }, "type": "object", "required": [ "panel" ], "title": "PublicCreateAndLaunchResponse" }, "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 panel (anonymous) interviews" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "quality": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quality", "description": "Quality rating: Excellent, Good, Fair, or Poor" }, "end_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Reason", "description": "Why the interview ended" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "Date and time the interview took place" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds", "description": "Interview length in seconds (ended_at - started_at)" }, "messages": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Messages" }, "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" ], "title": "PublicInterview", "description": "Full interview shape returned by get-by-id (includes recordings etc.)." }, "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" }, "PublicInterviewParticipant": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "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 panel (anonymous) interviews" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "quality": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quality", "description": "Quality rating: Excellent, Good, Fair, or Poor" }, "end_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Reason", "description": "Why the interview ended" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "Date and time the interview took place" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds", "description": "Interview length in seconds (ended_at - started_at)" } }, "type": "object", "required": [ "id" ], "title": "PublicInterviewSummary", "description": "Lightweight interview shape returned by the list endpoint (transcript,\nrecordings, and analysis are stripped — fetch by id to get them)." }, "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", "title": "Target", "description": "Target number of completed responses" }, "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).", "default": "US" }, "frequency": { "type": "string", "enum": [ "one-time", "weekly", "monthly", "quarterly" ], "title": "Frequency", "description": "Recurring schedule, or one-time.", "default": "one-time" }, "dry_run": { "type": "boolean", "title": "Dry Run", "description": "Return a cost estimate without provisioning the panel", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "target" ], "title": "PublicPanelCreate", "description": "Field a paid panel for a Panel-type study. The interview language is taken\nfrom the study (not set here)." }, "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" }, "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 × target)." }, "estimated_timeline_hours": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Estimated Timeline Hours", "description": "Estimated time to complete, in whole hours (rounded up)." } }, "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" }, { "type": "null" } ], "title": "Name", "description": "Study display name" }, "study_type": { "type": "string", "const": "in-depth-interview", "title": "Study Type", "description": "Study-type template slug", "default": "in-depth-interview" }, "recruiting_method": { "anyOf": [ { "type": "string", "enum": [ "panel", "byop" ] }, { "type": "null" } ], "title": "Recruiting Method", "description": "panel (recruit from the panel) or byop (bring your own participants)" }, "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", "ar", "bg", "cs", "da", "de", "el", "en", "es", "fi", "fil", "fr", "hi", "hr", "id", "it", "ja", "ko", "ms", "nl", "pl", "pt", "ro", "ru", "sk", "sv", "ta", "tr", "uk", "zh" ], "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." }, "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 — no incentive config (always a\npanel study, so incentives don't apply)." }, "PublicParticipant": { "properties": { "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" }, "panel_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Panel Status", "description": "Panel lifecycle status, if a panel participant" }, "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" }, "sent_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Sent At" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "id" ], "title": "PublicParticipant" }, "PublicParticipantCreate": { "properties": { "study_id": { "type": "string", "title": "Study Id", "description": "The study to invite this participant to" }, "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "title": "Email" }, "silent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Silent", "description": "Skip sending the invitation email", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "study_id" ], "title": "PublicParticipantCreate" }, "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" }, "PublicParticipantUpdate": { "properties": { "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "title": "Email" } }, "additionalProperties": false, "type": "object", "title": "PublicParticipantUpdate" }, "PublicReport": { "properties": { "study_id": { "type": "string", "title": "Study Id", "description": "The study this report was generated for" }, "report": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Report", "description": "Rendered report (the references section is moved to `references`)" }, "references": { "items": { "$ref": "#/components/schemas/PublicReportReference" }, "type": "array", "title": "References" }, "interview_count": { "type": "integer", "title": "Interview Count", "description": "Number of interviews included in the report", "default": 0 }, "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" }, "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" } }, "type": "object", "required": [ "reference_id" ], "title": "PublicReportReference", "description": "A citation in the report, resolved to the interview + message it quotes." }, "PublicScreenerOption": { "properties": { "id": { "type": "string", "title": "Id" }, "text": { "type": "string", "title": "Text" }, "disqualify": { "type": "boolean", "title": "Disqualify" } }, "type": "object", "required": [ "id", "text", "disqualify" ], "title": "PublicScreenerOption" }, "PublicScreenerOptionInput": { "properties": { "text": { "type": "string", "title": "Text" }, "disqualify": { "type": "boolean", "title": "Disqualify", "default": false }, "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", "title": "Type", "description": "single_select, multi_select, or text_input" }, "order": { "type": "integer", "title": "Order" }, "options": { "items": { "$ref": "#/components/schemas/PublicScreenerOption" }, "type": "array", "title": "Options" }, "text_values": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Text Values" }, "disallowed_text_values": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Disallowed Text Values" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } }, "type": "object", "required": [ "id", "text", "type", "order" ], "title": "PublicScreenerQuestion" }, "PublicScreenerQuestionInput": { "properties": { "text": { "type": "string", "title": "Text" }, "type": { "type": "string", "title": "Type", "description": "single_select, multi_select, or text_input", "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" }, "text_values": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Text Values" }, "disallowed_text_values": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Disallowed Text Values" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } }, "additionalProperties": false, "type": "object", "required": [ "text" ], "title": "PublicScreenerQuestionInput", "description": "Inbound screener question. ``id``/``order`` are auto-generated if omitted." }, "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" }, "PublicStudy": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "study_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Type", "description": "Study-type template slug" }, "recruiting_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recruiting Method", "description": "panel or byop" }, "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'" }, "byop_config": { "$ref": "#/components/schemas/PublicByopConfigOut" }, "study_link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Link", "description": "Universal interview link for the study" }, "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" }, "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" }, "total_invites": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Invites" }, "total_calls": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Calls" }, "quality_calls": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Quality Calls", "description": "Number of quality interviews" } }, "type": "object", "required": [ "id" ], "title": "PublicStudy", "description": "Full study shape returned by get-by-id (includes the heavy fields)." }, "PublicStudyCreate": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Study display name" }, "study_type": { "type": "string", "const": "in-depth-interview", "title": "Study Type", "description": "Study-type template slug", "default": "in-depth-interview" }, "recruiting_method": { "anyOf": [ { "type": "string", "enum": [ "panel", "byop" ] }, { "type": "null" } ], "title": "Recruiting Method", "description": "panel (recruit from the panel) or byop (bring your own participants)" }, "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", "ar", "bg", "cs", "da", "de", "el", "en", "es", "fi", "fil", "fr", "hi", "hr", "id", "it", "ja", "ko", "ms", "nl", "pl", "pt", "ro", "ru", "sk", "sv", "ta", "tr", "uk", "zh" ], "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." }, "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": "PublicStudyCreate", "description": "Create a study. Unknown fields are rejected." }, "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 — 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": "The critical things to learn (bullets)." }, "key_questions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Key Questions", "description": "The specific questions to answer (bullets)." }, "study_specific_rules": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Specific Rules", "description": "Operational guardrails and neutrality notes." } }, "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" }, "key_questions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Key Questions" }, "study_specific_rules": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Specific Rules" } }, "type": "object", "title": "PublicStudyPlanOut", "description": "Response variant — all sections optional (a study's stored prompt may not\ncontain every section)." }, "PublicStudySummary": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "study_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Type", "description": "Study-type template slug" }, "recruiting_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recruiting Method", "description": "panel or byop" }, "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'" }, "byop_config": { "$ref": "#/components/schemas/PublicByopConfigOut" }, "study_link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Study Link", "description": "Universal interview link for the study" }, "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" ], "title": "PublicStudySummary", "description": "Lightweight study shape returned by the list endpoint (heavy fields such\nas the study plan and screener questions are stripped — fetch by id)." }, "PublicStudyUpdate": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Study display name" }, "study_type": { "type": "string", "const": "in-depth-interview", "title": "Study Type", "description": "Study-type template slug", "default": "in-depth-interview" }, "recruiting_method": { "anyOf": [ { "type": "string", "enum": [ "panel", "byop" ] }, { "type": "null" } ], "title": "Recruiting Method", "description": "panel (recruit from the panel) or byop (bring your own participants)" }, "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", "ar", "bg", "cs", "da", "de", "el", "en", "es", "fi", "fil", "fr", "hi", "hr", "id", "it", "ja", "ko", "ms", "nl", "pl", "pt", "ro", "ru", "sk", "sv", "ta", "tr", "uk", "zh" ], "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." }, "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 — 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 → allow all options;\n- only allowed → disqualify any option not listed;\n- only disallowed → allow any option not listed (can't disallow them all);\n- both → 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" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "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" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Authenticate with an API key (prefixed `ui_sk_`) or a JWT token from the dashboard." } } } }