{"openapi":"3.1.0","info":{"title":"QuestionPunk Public API","version":"1.0.0","description":"Programmatic access to QuestionPunk surveys, questions, responses, and webhooks. Authenticate with a Bearer token (API key or OAuth access token). Operations list the scopes they need in `x-required-scopes`. Requests are limited to 100 per fixed 60-second window per client IP; every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","contact":{"email":"support@questionpunk.com"}},"servers":[{"url":"https://app.questionpunk.com/api/public/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key or OAuth2 access token"}},"parameters":{"SurveyId":{"name":"surveyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"QuestionId":{"name":"questionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"ResponseId":{"name":"responseId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"WebhookId":{"name":"webhookId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"RequestId":{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Number of items per page (max 100)"},"Cursor":{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor for keyset pagination"},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Client-provided idempotency key for create replay safety. Reusing the same key returns the same recruitment request."}},"schemas":{"PaginationMeta":{"type":"object","properties":{"cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["validation_error","authentication_error","permission_error","not_found","conflict","rate_limit_error","server_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"doc_url":{"type":"string","format":"uri"}},"required":["type","code","message"]}},"required":["error"]},"User":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":["string","null"]},"plan":{"type":["string","null"]},"teams":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"role":{"type":"string"}}}},"auth":{"type":"object","properties":{"method":{"type":"string","enum":["api_key","oauth"]},"scopes":{"type":"array","items":{"type":"string"}}}}}},"SurveySummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["draft","published","unpublished","archived"]},"title":{"type":"string"},"survey_mode":{"type":"string","enum":["chat","sequential","traditional"]},"custom_url":{"type":["string","null"]},"response_count":{"type":"integer"},"response_limit":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SurveyDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["draft","published","unpublished","archived"]},"title":{"type":"string"},"survey_mode":{"type":"string","enum":["chat","sequential","traditional"]},"custom_url":{"type":["string","null"]},"response_count":{"type":"integer"},"response_limit":{"type":["integer","null"]},"share_url":{"type":"string","format":"uri"},"settings":{"type":"object","properties":{"anonymous_mode":{"type":"boolean"},"open_at":{"type":["string","null"],"format":"date-time"},"close_at":{"type":["string","null"],"format":"date-time"},"is_branding_enabled":{"type":"boolean"},"is_cookie_consent_enabled":{"type":"boolean"},"is_progress_bar_enabled":{"type":"boolean"},"show_language_selector":{"type":"boolean"},"completion_redirect_url":{"type":["string","null"]},"disabled_incognito":{"type":"boolean"},"disabled_multiple_submission":{"type":"boolean"},"session_resumption_enabled":{"type":"boolean"},"session_resumption_ttl_hours":{"type":["integer","null"]}}},"design":{"type":"object","properties":{"background_color":{"type":["string","null"]},"chat_background_color":{"type":["string","null"]},"welcome_screen_details":{},"thank_screen_details":{}}},"questions":{"type":"array","items":{"$ref":"#/components/schemas/Question"}},"question_groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":["string","null"]},"order":{"type":"integer"},"parent_group_id":{"type":["string","null"]},"configuration":{}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"AnswerType":{"type":"string","description":"Question types accepted when creating or updating questions. Not accepted, because each needs something a question payload cannot carry: `design` (a linked design asset), `concept_test`, `concept_explore`, `concept_converge` and `concept_final` (a provisioned concept test), and `usability_test` (a screen-share section).","enum":["opinion_scale","slider","slider_matrix","rating","multiple_choice","ai_interview","ai_audio_interview","ai_question","long_text","short_text","email","phone_number","matrix","address","date","contact_form","dropdown","chat_message","page","chat_reset","website","ranking","numeric","audio_record","video_record","constant_sum","button","ai_moderated_interview","distribution_builder","van_westendorp","max_diff","card_sorting","conjoint_analysis","vignette_experiment","list_experiment","heatmap_click","text_highlight","signature","file_upload","photo_response","payment","consent","ai_image_generation","linkedin_verification","google_verification","email_verification","phone_verification"]},"QuestionTextDetails":{"type":"object","additionalProperties":true,"description":"Translatable content of the question in the survey's primary language: choice labels (`answer_options`), matrix `rows`/`columns`, scale labels (`min_value_label`, `max_value_label`, ...), a consent `statement`/`agree_label`, and so on. The accepted keys depend on `answer_type` and match the QuestionPunk editor's text fields for that type; unknown keys and wrongly typed values are rejected with 400 (`param` names the field, e.g. `text_details.answer_options`). On create it is merged over the type's defaults; on update it is merged over the stored primary-language values (or over the new type's defaults when `answer_type` changes). Arrays replace, objects merge. Other survey languages keep their own translations.","examples":[{"answer_options":["Free","Pro","Enterprise"]},{"rows":["Speed","Price","Support"],"columns":["Poor","Fair","Good","Excellent"]}]},"Question":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"answer_type":{"type":"string","description":"Question type. Questions created through this API use an AnswerType value; surveys built in the QuestionPunk app can hold other types (for example design or concept_test), so treat unrecognized values as opaque."},"text":{"type":"string"},"required":{"type":"boolean"},"order":{"type":"integer"},"group_id":{"type":["string","null"]},"internal_name":{"type":["string","null"]},"details":{"type":"object","additionalProperties":true},"text_details":{"type":"object","additionalProperties":true,"description":"Translatable content in the survey's primary language (see QuestionTextDetails)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ResponseSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["started","completed","abandoned"]},"response_type":{"type":"string","enum":["real","synthetic"]},"fraud":{"$ref":"#/components/schemas/FraudInfo"},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"geo":{"$ref":"#/components/schemas/Geo"}}},"ResponseDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"survey_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["started","completed","abandoned"]},"response_type":{"type":"string","enum":["real","synthetic"]},"fraud":{"$ref":"#/components/schemas/FraudInfo"},"answers":{"type":"array","items":{"$ref":"#/components/schemas/Answer"}},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"geo":{"$ref":"#/components/schemas/Geo"}}},"FraudInfo":{"type":"object","properties":{"suspicious_level":{"type":["string","null"],"enum":["low","medium","high",null]},"manual_label":{"type":["string","null"],"enum":["fraud","not_fraud",null]},"reasons":{"type":"array","items":{"type":"string"}}}},"Answer":{"type":"object","properties":{"question_id":{"type":["string","null"]},"question_text":{"type":"string"},"answer_type":{"type":"string"},"answer":{},"order":{"type":"integer"}}},"Geo":{"type":["object","null"],"properties":{"country":{"type":["string","null"]},"region":{"type":["string","null"]}}},"WebhookSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"fail_count":{"type":"integer"},"last_failed_at":{"type":["string","null"],"format":"date-time"},"paused_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"WebhookDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"fail_count":{"type":"integer"},"last_failed_at":{"type":["string","null"],"format":"date-time"},"paused_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"deliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"event":{"type":"string"},"http_status":{"type":["integer","null"]},"delivered_at":{"type":["string","null"],"format":"date-time"},"attempt_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}}}}},"WebhookEventSubscription":{"type":"array","minItems":1,"items":{"type":"string","enum":["response.completed","response.started","survey.published","survey.unpublished","survey.response_limit_reached","recruitment.started","recruitment.fulfilled","recruitment.partial","recruitment.failed","panel.submission.approved","panel.submission.rejected","panel.submission.payout_released","panel.submission.paid","*"]},"description":"Event types to deliver, or [\"*\"] on its own for every event, including event types added later."},"WebhookCreated":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"secret":{"type":"string","description":"HMAC signing secret (shown only on creation)"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"PanelWebhookEnvelope":{"type":"object","required":["id","version","type","occurred_at","data"],"properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"integer","enum":[1]},"type":{"type":"string","enum":["recruitment.started","recruitment.fulfilled","recruitment.partial","recruitment.failed","panel.submission.approved","panel.submission.rejected","panel.submission.payout_released","panel.submission.paid"]},"occurred_at":{"type":"string","format":"date-time"},"data":{"oneOf":[{"$ref":"#/components/schemas/RecruitmentStartedWebhookData"},{"$ref":"#/components/schemas/RecruitmentProgressWebhookData"},{"$ref":"#/components/schemas/RecruitmentFailedWebhookData"},{"$ref":"#/components/schemas/PanelSubmissionDecisionWebhookData"},{"$ref":"#/components/schemas/PanelSubmissionPaidWebhookData"}]}}},"RecruitmentStartedWebhookData":{"type":"object","required":["request_id","survey_id","status","target_responses","allocated_count"],"properties":{"request_id":{"type":"string","format":"uuid"},"survey_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"target_responses":{"type":"integer","minimum":1},"allocated_count":{"type":"integer","minimum":0}}},"RecruitmentProgressWebhookData":{"type":"object","required":["request_id","survey_id","status","target_responses","allocated_count","submitted_count","approved_count"],"properties":{"request_id":{"type":"string","format":"uuid"},"survey_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["fulfilled","partial","in_flight"]},"target_responses":{"type":"integer","minimum":1},"allocated_count":{"type":"integer","minimum":0},"submitted_count":{"type":"integer","minimum":0},"approved_count":{"type":"integer","minimum":0}}},"RecruitmentFailedWebhookData":{"type":"object","required":["request_id","survey_id","status","reason_code"],"properties":{"request_id":{"type":"string","format":"uuid"},"survey_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"reason_code":{"type":"string"}}},"PanelSubmissionDecisionWebhookData":{"type":"object","required":["submission_id","chat_survey_id","survey_id","status","reason_code"],"properties":{"submission_id":{"type":"string","format":"uuid"},"chat_survey_id":{"type":"string","format":"uuid"},"survey_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["approved","rejected"]},"reason_code":{"type":"string"}}},"PanelSubmissionPaidWebhookData":{"type":"object","required":["submission_id","chat_survey_id","survey_id","status","reservation_id"],"properties":{"submission_id":{"type":"string","format":"uuid"},"chat_survey_id":{"type":"string","format":"uuid"},"survey_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["paid"]},"reason_code":{"type":"string"},"reservation_id":{"type":"string","format":"uuid"},"payout_order_id":{"type":"string"}}},"PanelRespondent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["real","synthetic","imported"]},"name":{"type":"string"},"description":{"type":"string"},"personaDetails":{"type":"object","additionalProperties":true},"email":{"type":"string","format":"email"},"externalId":{"type":"string"},"source":{"type":"string"},"phone":{"type":"string"},"linkedinUrl":{"type":"string","format":"uri"},"notes":{"type":"string"},"archivedAt":{"type":["string","null"],"format":"date-time"},"country":{"type":"string"},"region":{"type":"string"},"city":{"type":"string"},"age":{"type":"integer"},"sex":{"type":"string"},"nationality":{"type":"string"},"ethnicity":{"type":"string"},"studentStatus":{"type":"string"},"employmentStatus":{"type":"string"},"demographicsImportedAt":{"type":"string","format":"date-time"},"demographicsSource":{"type":"string"}}},"PanelRespondentRegisterRequest":{"type":"object","required":["survey_id"],"properties":{"survey_id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"external_id":{"type":"string","minLength":1,"maxLength":200},"name":{"type":"string","minLength":1,"maxLength":200},"source":{"type":"string","minLength":1,"maxLength":100},"country":{"type":"string","minLength":1,"maxLength":100},"region":{"type":"string","minLength":1,"maxLength":200},"city":{"type":"string","minLength":1,"maxLength":200}},"description":"Either email or external_id is required."},"PanelRespondentRegisterResponse":{"type":"object","properties":{"respondent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":["string","null"],"format":"email"},"external_id":{"type":["string","null"]},"name":{"type":"string"},"source":{"type":["string","null"]},"country":{"type":["string","null"]},"region":{"type":["string","null"]},"city":{"type":["string","null"]}},"required":["id","name"]},"start_url":{"type":"string","format":"uri"}},"required":["respondent","start_url"]},"PanelRecruitmentStatus":{"type":"string","enum":["draft","launched","in_flight","fulfilled","partial","cancelled","failed"]},"PanelTargetingSnapshot":{"type":"object","properties":{"search":{"type":"string"},"audience_id":{"type":"string","format":"uuid"},"source":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"city":{"type":"string"},"include_archived":{"type":"boolean"},"taken_survey_id":{"type":"string","format":"uuid"},"answer_survey_id":{"type":"string","format":"uuid"},"answer_survey_item_id":{"type":"string","format":"uuid"},"answer_value":{"type":"string"},"answer_match":{"type":"string","enum":["contains","exact"]},"answer_completed_only":{"type":"boolean"}},"additionalProperties":false},"PanelRecruitmentCounters":{"type":"object","properties":{"allocated":{"type":"integer","minimum":0},"started":{"type":"integer","minimum":0},"submitted":{"type":"integer","minimum":0},"approved":{"type":"integer","minimum":0}},"required":["allocated","started","submitted","approved"]},"PanelRecruitmentRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"survey_id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/PanelRecruitmentStatus"},"target_responses":{"type":"integer","minimum":1},"targeting_snapshot":{"$ref":"#/components/schemas/PanelRecruitmentFrozenSnapshot"},"counters":{"$ref":"#/components/schemas/PanelRecruitmentCounters"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","survey_id","status","target_responses","targeting_snapshot","counters","created_at","updated_at"]},"PanelRecruitmentFrozenSnapshotV1":{"type":"object","required":["version","allow_repeat","targeting"],"properties":{"version":{"type":"integer","enum":[1]},"allow_repeat":{"type":"boolean"},"targeting":{"$ref":"#/components/schemas/PanelTargetingSnapshot"}}},"PanelProfileCriterionV2":{"type":"object","required":["question_id","question_key","question_version_id","question_label","operator","option_ids","option_codes","option_labels","max_age_days"],"properties":{"question_id":{"type":"string","format":"uuid"},"question_key":{"type":"string"},"question_version_id":{"type":"string","format":"uuid"},"question_label":{"type":"string"},"operator":{"type":"string","enum":["one_of","all_of","none_of","equals","greater_than_or_equal","less_than_or_equal"]},"option_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"option_codes":{"type":"array","items":{"type":"string"}},"option_labels":{"type":"array","items":{"type":"string"}},"number_value":{"type":"number"},"text_value":{"type":"string"},"max_age_days":{"type":["integer","null"],"minimum":1}},"additionalProperties":false},"PanelRecruitmentRequirementsV2":{"type":"object","required":["reward_cents","currency","provider_mode","estimated_duration_minutes","devices"],"properties":{"reward_cents":{"type":"integer","minimum":1},"currency":{"type":"string","enum":["USD","UAH"]},"provider_mode":{"type":"string","enum":["giftbit","manual_phone_topup"]},"estimated_duration_minutes":{"type":"integer","minimum":1},"devices":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["desktop","mobile","tablet"]}}},"additionalProperties":false},"PanelRecruitmentFrozenSnapshotV2":{"type":"object","required":["version","allow_repeat","profile_criteria","requirements","study_screener"],"properties":{"version":{"type":"integer","enum":[2]},"allow_repeat":{"type":"boolean"},"profile_criteria":{"type":"array","items":{"$ref":"#/components/schemas/PanelProfileCriterionV2"}},"requirements":{"$ref":"#/components/schemas/PanelRecruitmentRequirementsV2"},"study_screener":{"type":"null","description":"Reserved for a future allocation-scoped screener. It is never an ordinary survey or a source of global profile answers."}},"additionalProperties":false},"PanelRecruitmentFrozenSnapshot":{"oneOf":[{"$ref":"#/components/schemas/PanelRecruitmentFrozenSnapshotV1"},{"$ref":"#/components/schemas/PanelRecruitmentFrozenSnapshotV2"}],"discriminator":{"propertyName":"version","mapping":{"1":"#/components/schemas/PanelRecruitmentFrozenSnapshotV1","2":"#/components/schemas/PanelRecruitmentFrozenSnapshotV2"}}},"PanelRecruitmentCancelResponse":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["cancelled"]},"idempotent":{"type":"boolean"}},"required":["request_id","status","idempotent"]}},"responses":{"BadRequest":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"Conflict (e.g. wrong status transition)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InsufficientScopes":{"description":"The API key or OAuth token lacks a scope listed in the operation's x-required-scopes (`insufficient_scopes`). A token that carries any panel:* scope also needs a Pro or Enterprise plan (`panel_entitlement_required`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missingScope":{"value":{"error":{"type":"permission_error","code":"insufficient_scopes","message":"Missing required scopes: surveys:write"}}}}}}},"TooManyRequests":{"description":"Rate limit exceeded (`rate_limited`): more than 100 requests from this client IP in the current 60-second window.","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, when the current window ends","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rateLimited":{"value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests. Please retry after the period indicated by Retry-After."}}}}}}}}},"paths":{"/me":{"get":{"tags":["Account"],"summary":"Get current user info","operationId":"getMe","responses":{"200":{"description":"Current user profile and auth context","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/User"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/surveys":{"get":{"tags":["Surveys"],"summary":"List surveys","operationId":"listSurveys","x-required-scopes":["surveys:read"],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","published","unpublished","archived"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["created_at","updated_at"],"default":"created_at"}},{"name":"team_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Paginated list of surveys","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SurveySummary"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"tags":["Surveys"],"summary":"Create a survey","operationId":"createSurvey","x-required-scopes":["surveys:write"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","minLength":1,"maxLength":200},"survey_mode":{"type":"string","enum":["chat","sequential","traditional"]},"team_id":{"type":["string","null"],"format":"uuid"}}}}}},"responses":{"201":{"description":"Survey created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SurveySummary"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/surveys/generate":{"post":{"tags":["Surveys"],"summary":"Generate a draft survey from a prompt","description":"Creates a draft survey and has AI write its title and questions from a plain-language description. Generation runs before the response returns, so the call can take several seconds. Used by the Zapier and Make integrations.","operationId":"generateSurvey","x-required-scopes":["surveys:write"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","minLength":1,"maxLength":2000,"description":"What the survey should cover. Also stored as the survey description."}}}}}},"responses":{"201":{"description":"Draft survey created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["id","title","status","question_count"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"status":{"type":"string","enum":["draft"]},"question_count":{"type":"integer","minimum":0},"editor_url":{"type":"string","format":"uri","description":"Link to the survey in the QuestionPunk editor"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/surveys/{surveyId}":{"get":{"tags":["Surveys"],"summary":"Get survey detail","operationId":"getSurvey","x-required-scopes":["surveys:read"],"parameters":[{"$ref":"#/components/parameters/SurveyId"}],"responses":{"200":{"description":"Full survey detail including questions and settings","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SurveyDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"tags":["Surveys"],"summary":"Update a survey","description":"Updates survey metadata and settings. Unknown fields are rejected. Status is not writable here: use POST /surveys/{surveyId}/publish and POST /surveys/{surveyId}/unpublish.","operationId":"updateSurvey","x-required-scopes":["surveys:write"],"parameters":[{"$ref":"#/components/parameters/SurveyId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"custom_url":{"type":["string","null"],"minLength":1,"maxLength":100},"response_limit":{"type":["integer","null"],"minimum":1},"settings":{"type":"object","properties":{"open_at":{"type":["string","null"],"format":"date-time"},"close_at":{"type":["string","null"],"format":"date-time"},"anonymous_mode":{"type":"boolean"},"is_branding_enabled":{"type":"boolean"},"is_cookie_consent_enabled":{"type":"boolean"},"is_progress_bar_enabled":{"type":"boolean"},"show_language_selector":{"type":"boolean"},"completion_redirect_url":{"type":["string","null"],"format":"uri"},"disabled_incognito":{"type":"boolean"},"disabled_multiple_submission":{"type":"boolean"},"session_resumption_enabled":{"type":"boolean"},"session_resumption_ttl_hours":{"type":"integer","minimum":1,"maximum":720}}}}}}}},"responses":{"200":{"description":"Updated survey","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SurveySummary"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"tags":["Surveys"],"summary":"Delete a draft survey","operationId":"deleteSurvey","x-required-scopes":["surveys:write"],"parameters":[{"$ref":"#/components/parameters/SurveyId"}],"responses":{"200":{"description":"Survey deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/surveys/{surveyId}/publish":{"post":{"tags":["Surveys"],"summary":"Publish a survey","operationId":"publishSurvey","x-required-scopes":["surveys:write"],"parameters":[{"$ref":"#/components/parameters/SurveyId"}],"responses":{"200":{"description":"Survey published","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SurveySummary"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/surveys/{surveyId}/unpublish":{"post":{"tags":["Surveys"],"summary":"Unpublish a survey","operationId":"unpublishSurvey","x-required-scopes":["surveys:write"],"parameters":[{"$ref":"#/components/parameters/SurveyId"}],"responses":{"200":{"description":"Survey unpublished (taken offline; republish to go live again)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SurveySummary"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/surveys/{surveyId}/questions":{"get":{"tags":["Questions"],"summary":"List questions for a survey","operationId":"listQuestions","x-required-scopes":["surveys:read"],"parameters":[{"$ref":"#/components/parameters/SurveyId"}],"responses":{"200":{"description":"Array of questions ordered by position","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Question"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"tags":["Questions"],"summary":"Create a question","operationId":"createQuestion","x-required-scopes":["surveys:write"],"parameters":[{"$ref":"#/components/parameters/SurveyId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["answer_type","text"],"properties":{"answer_type":{"$ref":"#/components/schemas/AnswerType"},"text":{"type":"string","maxLength":10000},"required":{"type":"boolean","default":false},"order":{"type":"integer","minimum":0},"group_id":{"type":["string","null"],"format":"uuid"},"internal_name":{"type":["string","null"],"maxLength":255},"details":{"type":"object","additionalProperties":true,"description":"Type-specific configuration (merged with defaults)"},"text_details":{"$ref":"#/components/schemas/QuestionTextDetails"}}},"examples":{"multiple_choice":{"summary":"Multiple choice with answer options","value":{"answer_type":"multiple_choice","text":"Which plan are you on?","required":true,"details":{"multiple_selection":false},"text_details":{"answer_options":["Free","Pro","Enterprise"]}}},"matrix":{"summary":"Matrix with rows and columns","value":{"answer_type":"matrix","text":"How satisfied are you with each area?","text_details":{"rows":["Speed","Price","Support"],"columns":["Poor","Fair","Good","Excellent"]}}}}}}},"responses":{"201":{"description":"Question created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Question"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/surveys/{surveyId}/questions/bulk":{"post":{"tags":["Questions"],"summary":"Bulk-create questions","operationId":"bulkCreateQuestions","x-required-scopes":["surveys:write"],"parameters":[{"$ref":"#/components/parameters/SurveyId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["questions"],"properties":{"questions":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["answer_type","text"],"properties":{"answer_type":{"$ref":"#/components/schemas/AnswerType"},"text":{"type":"string","maxLength":10000},"required":{"type":"boolean","default":false},"details":{"type":"object","additionalProperties":true},"text_details":{"$ref":"#/components/schemas/QuestionTextDetails"},"internal_name":{"type":["string","null"],"maxLength":255}}}}}}}}},"responses":{"201":{"description":"Questions created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Question"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/surveys/{surveyId}/questions/reorder":{"post":{"tags":["Questions"],"summary":"Reorder questions in a survey","operationId":"reorderQuestions","x-required-scopes":["surveys:write"],"parameters":[{"$ref":"#/components/parameters/SurveyId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order"],"properties":{"order":{"type":"array","minItems":1,"items":{"type":"string","format":"uuid"},"description":"Question IDs in the new order. Must list every question in the survey exactly once; a duplicate, foreign, or missing ID is rejected with 400 (`duplicate_question_ids`, `invalid_question_id`, `missing_question_ids`). The order is applied within each question group."}}}}}},"responses":{"200":{"description":"Questions reordered","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"reordered":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/surveys/{surveyId}/questions/{questionId}":{"patch":{"tags":["Questions"],"summary":"Update a question","operationId":"updateQuestion","x-required-scopes":["surveys:write"],"parameters":[{"$ref":"#/components/parameters/SurveyId"},{"$ref":"#/components/parameters/QuestionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"answer_type":{"$ref":"#/components/schemas/AnswerType"},"text":{"type":"string","maxLength":10000},"required":{"type":"boolean"},"internal_name":{"type":["string","null"],"maxLength":255},"details":{"type":"object","additionalProperties":true},"text_details":{"$ref":"#/components/schemas/QuestionTextDetails"}}},"examples":{"answer_options":{"summary":"Replace the answer options","value":{"text_details":{"answer_options":["Free","Pro","Team","Enterprise"]}}}}}}},"responses":{"200":{"description":"Updated question","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Question"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"tags":["Questions"],"summary":"Delete a question","operationId":"deleteQuestion","x-required-scopes":["surveys:write"],"parameters":[{"$ref":"#/components/parameters/SurveyId"},{"$ref":"#/components/parameters/QuestionId"}],"responses":{"200":{"description":"Question deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/surveys/{surveyId}/responses":{"get":{"tags":["Responses"],"summary":"List responses for a survey","operationId":"listResponses","x-required-scopes":["responses:read"],"parameters":[{"$ref":"#/components/parameters/SurveyId"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"status","in":"query","schema":{"type":"string","enum":["started","completed","abandoned"]}},{"name":"type","in":"query","schema":{"type":"string","enum":["real","synthetic"]}},{"name":"suspicious_level","in":"query","schema":{"type":"string","enum":["low","medium","high"]}},{"name":"manual_label","in":"query","schema":{"type":"string","enum":["fraud","not_fraud"]}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only return responses created at or after this timestamp"}],"responses":{"200":{"description":"Paginated list of responses","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResponseSummary"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/surveys/{surveyId}/export":{"post":{"tags":["Responses"],"summary":"Bulk export responses (JSON or CSV)","operationId":"exportResponses","x-required-scopes":["responses:read"],"parameters":[{"$ref":"#/components/parameters/SurveyId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["format"],"properties":{"format":{"type":"string","enum":["json","csv"]},"limit":{"type":"integer","minimum":1,"maximum":10000,"default":10000,"description":"Maximum number of responses to export"},"filters":{"type":"object","properties":{"status":{"type":"string","enum":["started","completed","abandoned"]},"type":{"type":"string","enum":["real","synthetic"]},"since":{"type":"string","format":"date-time"}}}}}}}},"responses":{"200":{"description":"Export data. Returns `application/json` for JSON format or `text/csv` for CSV format.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"response_type":{"type":"string"},"fraud":{"$ref":"#/components/schemas/FraudInfo"},"answers":{"type":"array","items":{"$ref":"#/components/schemas/Answer"}},"completed_at":{"type":["string","null"]},"created_at":{"type":"string"},"geo":{"$ref":"#/components/schemas/Geo"}}}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}},"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/responses/{responseId}":{"get":{"tags":["Responses"],"summary":"Get response detail with answers","operationId":"getResponse","x-required-scopes":["responses:read"],"parameters":[{"$ref":"#/components/parameters/ResponseId"}],"responses":{"200":{"description":"Response with full answer data","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ResponseDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"tags":["Responses"],"summary":"Delete a response","operationId":"deleteResponse","x-required-scopes":["responses:write"],"parameters":[{"$ref":"#/components/parameters/ResponseId"}],"responses":{"200":{"description":"Response deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The response has a reserved or paid incentive reward and cannot be deleted (`incentive_reservation_active`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"incentiveReservationActive":{"value":{"error":{"type":"conflict","code":"incentive_reservation_active","message":"This response has a reserved or paid incentive reward and cannot be deleted. Resolve the incentive first."}}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/panel/respondents/register":{"post":{"tags":["Panel"],"summary":"Register or find a panel respondent for a survey","description":"Requires panel respondent write scope. Creates or reuses a respondent using email/external_id dedupe and returns the canonical survey start URL.","operationId":"panelRegisterRespondent","security":[{"bearerAuth":[]}],"x-required-scopes":["panel:respondents:write"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PanelRespondentRegisterRequest"},"examples":{"basic":{"value":{"survey_id":"11111111-1111-4111-8111-111111111111","email":"participant@example.com","source":"partner_campaign","country":"UA"}}}}}},"responses":{"201":{"description":"Respondent created or reused","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PanelRespondentRegisterResponse"}}},"examples":{"created":{"value":{"data":{"respondent":{"id":"22222222-2222-4222-8222-222222222222","email":"participant@example.com","external_id":null,"name":"participant","source":"partner_campaign","country":"UA","region":null,"city":null},"start_url":"https://app.questionpunk.com/chat/panel-onboarding?respondent_id=22222222-2222-4222-8222-222222222222"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missingScope":{"value":{"error":{"type":"permission_error","code":"insufficient_scopes","message":"Missing required scopes: panel:respondents:write"}}}}}}},"404":{"description":"Panel API disabled or survey not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"panelDisabled":{"value":{"error":{"type":"not_found","code":"panel_api_disabled","message":"Panel API is not enabled"}}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/panel/respondents":{"get":{"tags":["Panel"],"summary":"List panel respondents with targeting filters","description":"Requires panel respondent read scope. Supports audience, location, participation, and answer filters with access-safe semantics.","operationId":"panelListRespondents","security":[{"bearerAuth":[]}],"x-required-scopes":["panel:respondents:read"],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"search","in":"query","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"audience_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"source","in":"query","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"country","in":"query","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"region","in":"query","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"city","in":"query","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_archived","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"taken_survey_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"answer_survey_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"answer_survey_item_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"answer_value","in":"query","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"answer_match","in":"query","schema":{"type":"string","enum":["contains","exact"]}},{"name":"answer_completed_only","in":"query","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Paginated respondents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PanelRespondent"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"examples":{"defaultList":{"value":{"data":[{"id":"22222222-2222-4222-8222-222222222222","createdAt":"2026-07-14T12:00:00.000Z","updatedAt":"2026-07-14T12:00:00.000Z","type":"real","name":"Participant","email":"participant@example.com","externalId":"ext-001","source":"panel_api","country":"UA","region":null,"city":null,"archivedAt":null}],"meta":{"cursor":"eyJpZCI6IjIyMjIyMjIyLTIyMjItNDIyMi04MjIyLTIyMjIyMjIyMjIyMiIsInNvcnRWYWx1ZSI6IjIwMjYtMDctMTRUMTI6MDA6MDAuMDAwWiJ9","has_more":false}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"description":"Panel API disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"panelDisabled":{"value":{"error":{"type":"not_found","code":"panel_api_disabled","message":"Panel API is not enabled"}}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/panel/recruitment/requests":{"post":{"tags":["Panel"],"summary":"Replay a legacy recruitment request","description":"Deprecated compatibility endpoint. New raw-targeting requests are rejected. A caller that already created a legacy request may replay its original Idempotency-Key to retrieve that request. Launch new global-profile recruitment from Survey → Share → Recruit.","deprecated":true,"operationId":"panelReplayLegacyRecruitmentRequest","security":[{"bearerAuth":[]}],"x-required-scopes":["panel:recruitment:write"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Existing legacy request replayed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["request","idempotent"],"properties":{"request":{"$ref":"#/components/schemas/PanelRecruitmentRequest"},"idempotent":{"type":"boolean","enum":[true]}}}}},"examples":{"replay":{"value":{"data":{"request":{"id":"44444444-4444-4444-8444-444444444444","survey_id":"11111111-1111-4111-8111-111111111111","status":"launched","target_responses":100,"targeting_snapshot":{"version":1,"allow_repeat":false,"targeting":{"country":"UA"}},"counters":{"allocated":75,"started":0,"submitted":0,"approved":0},"created_at":"2026-07-14T12:30:00.000Z","updated_at":"2026-07-14T12:30:00.000Z"},"idempotent":true}}}}}}},"400":{"description":"Validation error (including missing Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missingIdempotencyKey":{"value":{"error":{"type":"validation_error","code":"missing_idempotency_key","message":"Idempotency-Key header is required","param":"Idempotency-Key"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Panel API disabled or request not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"panelDisabled":{"value":{"error":{"type":"not_found","code":"panel_api_disabled","message":"Panel API is not enabled"}}}}}}},"409":{"description":"No legacy request exists for the supplied idempotency key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"upgradeRequired":{"value":{"error":{"type":"conflict","code":"panel_recruitment_v1_upgrade_required","message":"Creating recruitment requests through the v1 raw-targeting contract is no longer supported. Use Survey > Share > Recruit to launch against reusable Panel Profile criteria."}}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"get":{"tags":["Panel"],"summary":"List recruitment requests","description":"Requires panel recruitment read scope.","operationId":"panelListRecruitmentRequests","security":[{"bearerAuth":[]}],"x-required-scopes":["panel:recruitment:read"],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/PanelRecruitmentStatus"}},{"name":"survey_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Paginated recruitment requests","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PanelRecruitmentRequest"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"examples":{"list":{"value":{"data":[{"id":"44444444-4444-4444-8444-444444444444","survey_id":"11111111-1111-4111-8111-111111111111","status":"launched","target_responses":100,"targeting_snapshot":{"version":1,"allow_repeat":false,"targeting":{"country":"UA"}},"counters":{"allocated":75,"started":20,"submitted":8,"approved":6},"created_at":"2026-07-14T12:30:00.000Z","updated_at":"2026-07-14T13:00:00.000Z"}],"meta":{"cursor":null,"has_more":false}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/panel/recruitment/requests/{requestId}":{"get":{"tags":["Panel"],"summary":"Get a recruitment request","description":"Requires panel recruitment read scope.","operationId":"panelGetRecruitmentRequest","security":[{"bearerAuth":[]}],"x-required-scopes":["panel:recruitment:read"],"parameters":[{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"Recruitment request detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PanelRecruitmentRequest"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Panel API disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"panelDisabled":{"value":{"error":{"type":"not_found","code":"panel_api_disabled","message":"Panel API is not enabled"}}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/panel/recruitment/requests/{requestId}/cancel":{"post":{"tags":["Panel"],"summary":"Cancel a recruitment request","description":"Requires panel recruitment write scope. Idempotent: cancelling an already cancelled request returns idempotent=true.","operationId":"panelCancelRecruitmentRequest","security":[{"bearerAuth":[]}],"x-required-scopes":["panel:recruitment:write"],"parameters":[{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"Request cancelled or already cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PanelRecruitmentCancelResponse"}}},"examples":{"cancelled":{"value":{"data":{"request_id":"44444444-4444-4444-8444-444444444444","status":"cancelled","idempotent":false}}},"alreadyCancelled":{"value":{"data":{"request_id":"44444444-4444-4444-8444-444444444444","status":"cancelled","idempotent":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Panel API disabled or request not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"panelDisabled":{"value":{"error":{"type":"not_found","code":"panel_api_disabled","message":"Panel API is not enabled"}}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhook subscriptions","operationId":"listWebhooks","x-required-scopes":["webhooks:manage"],"responses":{"200":{"description":"Array of webhook subscriptions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSummary"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"tags":["Webhooks"],"summary":"Create a webhook subscription","operationId":"createWebhook","x-required-scopes":["webhooks:manage"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"$ref":"#/components/schemas/WebhookEventSubscription"}}}}}},"responses":{"201":{"description":"Webhook created. The `secret` field is only returned on creation — store it securely.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookCreated"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"externalDocs":{"description":"Deliveries are signed with X-QP-Signature over the raw request body and include X-QP-Event, X-QP-Event-Id, X-QP-Delivery-Attempt-Id, X-QP-Occurred-At, and X-QP-Event-Version headers. Consumers must verify the raw-body HMAC and dedupe retries on X-QP-Event-Id.","url":"https://docs.questionpunk.com/api/webhooks"}}},"/webhooks/{webhookId}":{"get":{"tags":["Webhooks"],"summary":"Get webhook detail with recent deliveries","operationId":"getWebhook","x-required-scopes":["webhooks:manage"],"parameters":[{"$ref":"#/components/parameters/WebhookId"}],"responses":{"200":{"description":"Webhook subscription with last 50 deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"tags":["Webhooks"],"summary":"Update a webhook subscription","operationId":"updateWebhook","x-required-scopes":["webhooks:manage"],"parameters":[{"$ref":"#/components/parameters/WebhookId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"$ref":"#/components/schemas/WebhookEventSubscription"},"is_active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated webhook subscription","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookSummary"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook subscription","operationId":"deleteWebhook","x-required-scopes":["webhooks:manage"],"parameters":[{"$ref":"#/components/parameters/WebhookId"}],"responses":{"200":{"description":"Webhook deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/webhooks/{webhookId}/test":{"post":{"tags":["Webhooks"],"summary":"Send a test webhook event","description":"Delivers an event of type `test` to the subscription URL, in the same `{ id, version, type, occurred_at, data }` envelope and with the same headers as real deliveries.","operationId":"testWebhook","x-required-scopes":["webhooks:manage"],"parameters":[{"$ref":"#/components/parameters/WebhookId"}],"responses":{"200":{"description":"Test delivery result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"http_status":{"type":["integer","null"]},"response_time_ms":{"type":["number","null"]}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/webhooks/subscribe":{"post":{"tags":["Webhooks"],"summary":"Subscribe a REST hook (Zapier)","description":"REST-hook subscribe endpoint used by the Zapier integration. Creates a subscription with no signing secret, so its deliveries carry no X-QP-Signature header. Use POST /webhooks for signed deliveries.","operationId":"subscribeRestHook","x-required-scopes":["webhooks:manage"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"$ref":"#/components/schemas/WebhookEventSubscription"},"target_app":{"type":"string","description":"Optional metadata sent by Zapier. Accepted and ignored."}}}}}},"responses":{"201":{"description":"Subscription created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/webhooks/subscribe/{webhookId}":{"delete":{"tags":["Webhooks"],"summary":"Unsubscribe a REST hook (Zapier)","description":"REST-hook unsubscribe endpoint used by the Zapier integration. Deletes the webhook subscription with this ID.","operationId":"unsubscribeRestHook","x-required-scopes":["webhooks:manage"],"parameters":[{"$ref":"#/components/parameters/WebhookId"}],"responses":{"204":{"description":"Subscription deleted. No response body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScopes"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}},"tags":[{"name":"Account","description":"Current user and authentication context"},{"name":"Surveys","description":"Create, read, update, delete, publish, and unpublish surveys"},{"name":"Questions","description":"Manage questions within a survey"},{"name":"Responses","description":"Read, export, and delete survey responses"},{"name":"Panel","description":"Respondent registration and recruitment APIs. Requires panel:* scopes: panel:respondents:read/write and panel:recruitment:read/write."},{"name":"Webhooks","description":"Manage webhook subscriptions for real-time event delivery"}]}