{ "openapi": "3.1.0", "info": { "title": "Sprig Public API V2 — Studies", "version": "1.0.0", "description": "Programmatically create and manage Sprig Studies (surveys) and their Questions.", "contact": { "name": "Support", "email": "support@sprig.com" } }, "servers": [ { "url": "https://api.sprig.com" } ], "tags": [ { "name": "Studies", "description": "The root resource for a programmatically managed survey." }, { "name": "Questions", "description": "Questions, with their nested options, owned by a Study." }, { "name": "Invitations", "description": "Invitation codes for a Study that uses link distribution." }, { "name": "Translations", "description": "Asynchronous translation jobs for a Study. Cancellation is best-effort and does not roll back committed output." } ], "components": { "schemas": { "Study": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "SURVEY" ] }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "IN_PROGRESS", "PAUSED", "COMPLETED", "ARCHIVED" ] }, "version": { "type": "integer", "minimum": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "responseSettings": { "type": "object", "properties": { "completion": { "$ref": "#/components/schemas/StudyCompletion" }, "requireIdentifiedRespondent": { "type": "boolean" }, "allowBackwardNavigation": { "type": "boolean" } }, "required": [ "completion", "requireIdentifiedRespondent", "allowBackwardNavigation" ], "additionalProperties": false }, "shareUrl": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "id", "type", "name", "status", "version", "createdAt", "updatedAt", "responseSettings", "shareUrl" ], "additionalProperties": false }, "StudyCompletion": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "FIXED" ] }, "responseLimit": { "type": "integer", "minimum": 1 } }, "required": [ "mode", "responseLimit" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "UNTIL_DATE" ] }, "closeAt": { "type": "string", "format": "date-time" } }, "required": [ "mode", "closeAt" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ONGOING" ] } }, "required": [ "mode" ], "additionalProperties": false } ] }, "ErrorResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "A machine-readable error code (e.g. STUDY_NOT_FOUND)." }, "message": { "type": "string", "description": "A human-readable description of the error." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "string" }, "message": { "type": "string" }, "resource": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": [ "type", "id" ], "description": "The other resource this issue points at, when the issue is not about the request itself." } }, "required": [ "code", "message" ] }, "description": "Per-field validation issues, present when the request itself was malformed." } }, "required": [ "code", "message" ], "description": "Error response returned by the Public API V2." }, "CreateStudyRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SURVEY" ] }, "name": { "type": "string", "minLength": 1 }, "responseSettings": { "$ref": "#/components/schemas/StudyResponseSettings" } }, "required": [ "type", "name" ], "additionalProperties": false }, "StudyResponseSettings": { "type": "object", "properties": { "completion": { "$ref": "#/components/schemas/StudyCompletion" }, "requireIdentifiedRespondent": { "type": "boolean" }, "allowBackwardNavigation": { "type": "boolean" } }, "additionalProperties": false }, "UpdateStudyRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "responseSettings": { "$ref": "#/components/schemas/StudyResponseSettingsPatch" }, "status": { "type": "string", "enum": [ "IN_PROGRESS", "PAUSED", "COMPLETED", "ARCHIVED" ] } }, "additionalProperties": false }, "StudyResponseSettingsPatch": { "type": "object", "properties": { "completion": { "$ref": "#/components/schemas/StudyCompletion" }, "requireIdentifiedRespondent": { "type": "boolean" }, "allowBackwardNavigation": { "type": "boolean" } }, "additionalProperties": false, "minProperties": 1 }, "Question": { "oneOf": [ { "$ref": "#/components/schemas/OpenTextQuestion" }, { "$ref": "#/components/schemas/AiDynamicQuestion" }, { "$ref": "#/components/schemas/SingleSelectQuestion" }, { "$ref": "#/components/schemas/MultipleSelectQuestion" }, { "$ref": "#/components/schemas/RatingScaleQuestion" }, { "$ref": "#/components/schemas/NpsQuestion" }, { "$ref": "#/components/schemas/ValidatedTextQuestion" }, { "$ref": "#/components/schemas/RankOrderQuestion" }, { "$ref": "#/components/schemas/MatrixQuestion" }, { "$ref": "#/components/schemas/TextUrlPromptQuestion" } ], "discriminator": { "propertyName": "type", "mapping": { "OPEN_TEXT": "#/components/schemas/OpenTextQuestion", "AI_DYNAMIC": "#/components/schemas/AiDynamicQuestion", "SINGLE_SELECT": "#/components/schemas/SingleSelectQuestion", "MULTIPLE_SELECT": "#/components/schemas/MultipleSelectQuestion", "RATING_SCALE": "#/components/schemas/RatingScaleQuestion", "NPS": "#/components/schemas/NpsQuestion", "VALIDATED_TEXT": "#/components/schemas/ValidatedTextQuestion", "RANK_ORDER": "#/components/schemas/RankOrderQuestion", "MATRIX": "#/components/schemas/MatrixQuestion", "TEXT_URL_PROMPT": "#/components/schemas/TextUrlPromptQuestion" } }, "description": "Canonical Question resource." }, "OpenTextQuestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "title": { "$ref": "#/components/schemas/QuestionTitle" }, "required": { "type": "boolean" }, "displayLogic": { "anyOf": [ { "$ref": "#/components/schemas/DisplayLogic" }, { "type": "null" } ] }, "skipLogic": { "$ref": "#/components/schemas/SkipLogic" }, "aiFollowUp": { "type": [ "object", "null" ], "properties": { "userPrompt": { "type": [ "string", "null" ] } }, "required": [ "userPrompt" ], "additionalProperties": false }, "randomizePosition": { "type": "boolean" }, "description": { "$ref": "#/components/schemas/QuestionDescription" }, "type": { "type": "string", "enum": [ "OPEN_TEXT" ] }, "responsePlaceholder": { "type": "string", "description": "Placeholder shown in the response field." } }, "required": [ "id", "title", "required", "displayLogic", "skipLogic", "aiFollowUp", "randomizePosition", "type" ], "additionalProperties": false, "description": "Canonical open-text Question resource." }, "QuestionTitle": { "type": "object", "properties": { "html": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/AttributeVariable" }, { "$ref": "#/components/schemas/QuestionResponseVariable" } ], "discriminator": { "propertyName": "type", "mapping": { "ATTRIBUTE": "#/components/schemas/AttributeVariable", "QUESTION_RESPONSE": "#/components/schemas/QuestionResponseVariable" } } } } }, "required": [ "html", "variables" ], "additionalProperties": false, "description": "Canonical rich-text Question title." }, "AttributeVariable": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ATTRIBUTE" ] }, "attribute": { "type": "string", "minLength": 1, "maxLength": 128 }, "fallback": { "type": "string", "maxLength": 500 } }, "required": [ "type", "attribute" ], "additionalProperties": false, "description": "A rich-text replacement sourced from an environment attribute." }, "QuestionResponseVariable": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "QUESTION_RESPONSE" ] }, "question": { "$ref": "#/components/schemas/ResourceRef" }, "fallback": { "type": "string", "maxLength": 500 } }, "required": [ "type", "question" ], "additionalProperties": false, "description": "A rich-text replacement sourced from an earlier Question response." }, "ResourceRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 128 } }, "additionalProperties": false, "description": "A reference by canonical identifier, unique name, or both." }, "DisplayLogic": { "anyOf": [ { "$ref": "#/components/schemas/LogicCondition" }, { "type": "object", "properties": { "all": { "type": "array", "items": { "$ref": "#/components/schemas/LogicExpression" }, "minItems": 1, "maxItems": 20 } }, "required": [ "all" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "array", "items": { "$ref": "#/components/schemas/LogicExpression" }, "minItems": 1, "maxItems": 20 } }, "required": [ "any" ], "additionalProperties": false } ], "description": "Typed display logic owned by a Question." }, "LogicCondition": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/LogicConditionSource" }, "operator": { "$ref": "#/components/schemas/LogicOperator" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "source", "operator" ], "additionalProperties": false, "description": "A single typed condition. Operators that inspect answer state omit value; choice comparisons use immutable Option values." }, "LogicConditionSource": { "oneOf": [ { "$ref": "#/components/schemas/QuestionResponseConditionSource" }, { "$ref": "#/components/schemas/AttributeConditionSource" } ], "discriminator": { "propertyName": "type", "mapping": { "QUESTION_RESPONSE": "#/components/schemas/QuestionResponseConditionSource", "ATTRIBUTE": "#/components/schemas/AttributeConditionSource" } }, "description": "Typed source of a logic condition." }, "QuestionResponseConditionSource": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "QUESTION_RESPONSE" ] }, "question": { "$ref": "#/components/schemas/ResourceRef" } }, "required": [ "type", "question" ], "additionalProperties": false, "description": "A condition sourced from an earlier Question response." }, "AttributeConditionSource": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ATTRIBUTE" ] }, "attribute": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "attribute" ], "additionalProperties": false, "description": "A condition sourced from an environment attribute definition." }, "LogicOperator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "IN", "NOT_IN", "INCLUDES_ALL", "EXACTLY", "CONTAINS", "NOT_CONTAINS", "STARTS_WITH", "ENDS_WITH", "ANSWERED", "SKIPPED", "PARTIALLY_ANSWERED", "EXISTS", "NOT_EXISTS" ], "description": "Uppercase Public API operators. StudyService selects the valid operator/value branch from the source type and referenced Question type." }, "LogicExpression": { "anyOf": [ { "$ref": "#/components/schemas/LogicCondition" }, { "type": "object", "properties": { "all": { "type": "array", "items": { "$ref": "#/components/schemas/LogicExpression" }, "minItems": 1, "maxItems": 20 } }, "required": [ "all" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "array", "items": { "$ref": "#/components/schemas/LogicExpression" }, "minItems": 1, "maxItems": 20 } }, "required": [ "any" ], "additionalProperties": false } ], "description": "Nested display or skip conditions using all/any groups. Maximum depth is 5; each group may contain at most 20 children." }, "SkipLogic": { "type": "array", "items": { "$ref": "#/components/schemas/SkipLogicRule" }, "maxItems": 20, "description": "Ordered skip rules, limited to 20. An empty array clears skip logic." }, "SkipLogicRule": { "type": "object", "properties": { "when": { "$ref": "#/components/schemas/LogicExpression" }, "destination": { "$ref": "#/components/schemas/SkipDestination" } }, "required": [ "when", "destination" ], "additionalProperties": false, "description": "One skip rule with a typed condition and destination." }, "SkipDestination": { "oneOf": [ { "$ref": "#/components/schemas/EndSkipDestination" }, { "$ref": "#/components/schemas/QuestionSkipDestination" } ], "discriminator": { "propertyName": "type", "mapping": { "END": "#/components/schemas/EndSkipDestination", "QUESTION": "#/components/schemas/QuestionSkipDestination" } }, "description": "Public skip destination." }, "EndSkipDestination": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "END" ] } }, "required": [ "type" ], "additionalProperties": false, "description": "Ends the Study." }, "QuestionSkipDestination": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "QUESTION" ] }, "question": { "$ref": "#/components/schemas/ResourceRef" } }, "required": [ "type", "question" ], "additionalProperties": false, "description": "Skips to a Question." }, "QuestionDescription": { "type": "object", "properties": { "html": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/AttributeVariable" }, { "$ref": "#/components/schemas/QuestionResponseVariable" } ], "discriminator": { "propertyName": "type", "mapping": { "ATTRIBUTE": "#/components/schemas/AttributeVariable", "QUESTION_RESPONSE": "#/components/schemas/QuestionResponseVariable" } } } } }, "required": [ "html", "variables" ], "additionalProperties": false, "description": "Canonical respondent-facing Question description." }, "AiDynamicQuestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "title": { "$ref": "#/components/schemas/QuestionTitle" }, "required": { "type": "boolean" }, "displayLogic": { "anyOf": [ { "$ref": "#/components/schemas/DisplayLogic" }, { "type": "null" } ] }, "skipLogic": { "$ref": "#/components/schemas/SkipLogic" }, "aiFollowUp": { "type": [ "object", "null" ], "properties": { "userPrompt": { "type": [ "string", "null" ] } }, "required": [ "userPrompt" ], "additionalProperties": false }, "randomizePosition": { "type": "boolean" }, "description": { "$ref": "#/components/schemas/QuestionDescription" }, "type": { "type": "string", "enum": [ "AI_DYNAMIC" ] }, "userPrompt": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "required", "displayLogic", "skipLogic", "aiFollowUp", "randomizePosition", "type", "userPrompt" ], "additionalProperties": false, "description": "Canonical standalone AI Dynamic Question resource." }, "SingleSelectQuestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "title": { "$ref": "#/components/schemas/QuestionTitle" }, "required": { "type": "boolean" }, "displayLogic": { "anyOf": [ { "$ref": "#/components/schemas/DisplayLogic" }, { "type": "null" } ] }, "skipLogic": { "$ref": "#/components/schemas/SkipLogic" }, "aiFollowUp": { "type": [ "object", "null" ], "properties": { "userPrompt": { "type": [ "string", "null" ] } }, "required": [ "userPrompt" ], "additionalProperties": false }, "randomizePosition": { "type": "boolean" }, "description": { "$ref": "#/components/schemas/QuestionDescription" }, "type": { "type": "string", "enum": [ "SINGLE_SELECT" ] }, "randomizeOptions": { "type": "boolean" }, "presentation": { "type": "string", "enum": [ "LIST", "DROPDOWN" ] }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionOptionResponse" } }, "carryForward": { "$ref": "#/components/schemas/CarryForward" } }, "required": [ "id", "title", "required", "displayLogic", "skipLogic", "aiFollowUp", "randomizePosition", "type", "randomizeOptions", "presentation", "options" ], "additionalProperties": false, "description": "Canonical single-select Question resource." }, "QuestionOptionResponse": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "behavior": { "$ref": "#/components/schemas/QuestionOptionResponseBehavior" }, "textEntryPlaceholder": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false, "description": "Canonical answer Option returned with a choice Question." }, "QuestionOptionResponseBehavior": { "type": "string", "enum": [ "PINNED", "OTHER_TEXT", "NONE_OF_THE_ABOVE" ], "description": "Non-default Option behavior included in a Question response." }, "CarryForward": { "type": "object", "properties": { "sourceQuestion": { "$ref": "#/components/schemas/ResourceRef" }, "qualifyingColumnValues": { "type": "array", "items": { "type": "string" } } }, "required": [ "sourceQuestion" ], "additionalProperties": false, "description": "Carries respondent-selected items from an earlier Question." }, "MultipleSelectQuestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "title": { "$ref": "#/components/schemas/QuestionTitle" }, "required": { "type": "boolean" }, "displayLogic": { "anyOf": [ { "$ref": "#/components/schemas/DisplayLogic" }, { "type": "null" } ] }, "skipLogic": { "$ref": "#/components/schemas/SkipLogic" }, "aiFollowUp": { "type": [ "object", "null" ], "properties": { "userPrompt": { "type": [ "string", "null" ] } }, "required": [ "userPrompt" ], "additionalProperties": false }, "randomizePosition": { "type": "boolean" }, "description": { "$ref": "#/components/schemas/QuestionDescription" }, "type": { "type": "string", "enum": [ "MULTIPLE_SELECT" ] }, "randomizeOptions": { "type": "boolean" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionOptionResponse" } }, "selection": { "$ref": "#/components/schemas/MultipleSelectSelection" }, "displayLimit": { "type": "integer", "minimum": 2, "description": "Total number of authored choices shown to each respondent, including pinned choices." }, "carryForward": { "$ref": "#/components/schemas/CarryForward" } }, "required": [ "id", "title", "required", "displayLogic", "skipLogic", "aiFollowUp", "randomizePosition", "type", "randomizeOptions", "options" ], "additionalProperties": false, "description": "Canonical multiple-select Question resource." }, "MultipleSelectSelection": { "type": "object", "properties": { "min": { "type": "integer", "minimum": 0 }, "max": { "type": "integer", "minimum": 1 } }, "required": [ "min", "max" ], "additionalProperties": false, "description": "Inclusive minimum and maximum number of Options a respondent may select." }, "RatingScaleQuestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "title": { "$ref": "#/components/schemas/QuestionTitle" }, "required": { "type": "boolean" }, "displayLogic": { "anyOf": [ { "$ref": "#/components/schemas/DisplayLogic" }, { "type": "null" } ] }, "skipLogic": { "$ref": "#/components/schemas/SkipLogic" }, "aiFollowUp": { "type": [ "object", "null" ], "properties": { "userPrompt": { "type": [ "string", "null" ] } }, "required": [ "userPrompt" ], "additionalProperties": false }, "randomizePosition": { "type": "boolean" }, "description": { "$ref": "#/components/schemas/QuestionDescription" }, "type": { "type": "string", "enum": [ "RATING_SCALE" ] }, "range": { "$ref": "#/components/schemas/RatingScaleRange" }, "scaleLabelType": { "$ref": "#/components/schemas/RatingScaleLabelType" }, "lowEndLabel": { "type": [ "string", "null" ] }, "highEndLabel": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "required", "displayLogic", "skipLogic", "aiFollowUp", "randomizePosition", "type", "range", "scaleLabelType", "lowEndLabel", "highEndLabel" ], "additionalProperties": false, "description": "Canonical rating-scale Question resource." }, "RatingScaleRange": { "anyOf": [ { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 4 ] }, { "type": "number", "enum": [ 5 ] }, { "type": "number", "enum": [ 7 ] }, { "type": "number", "enum": [ 10 ] } ], "description": "Number of points on the rating scale." }, "RatingScaleLabelType": { "type": "string", "enum": [ "NUMBER", "STAR", "SMILEY" ], "description": "How the rating-scale points are displayed." }, "NpsQuestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "title": { "$ref": "#/components/schemas/QuestionTitle" }, "required": { "type": "boolean" }, "displayLogic": { "anyOf": [ { "$ref": "#/components/schemas/DisplayLogic" }, { "type": "null" } ] }, "skipLogic": { "$ref": "#/components/schemas/SkipLogic" }, "aiFollowUp": { "type": [ "object", "null" ], "properties": { "userPrompt": { "type": [ "string", "null" ] } }, "required": [ "userPrompt" ], "additionalProperties": false }, "randomizePosition": { "type": "boolean" }, "description": { "$ref": "#/components/schemas/QuestionDescription" }, "type": { "type": "string", "enum": [ "NPS" ] }, "lowEndLabel": { "type": "string" }, "highEndLabel": { "type": "string" } }, "required": [ "id", "title", "required", "displayLogic", "skipLogic", "aiFollowUp", "randomizePosition", "type", "lowEndLabel", "highEndLabel" ], "additionalProperties": false, "description": "Canonical Net Promoter Score Question resource." }, "ValidatedTextQuestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "title": { "$ref": "#/components/schemas/QuestionTitle" }, "required": { "type": "boolean" }, "displayLogic": { "anyOf": [ { "$ref": "#/components/schemas/DisplayLogic" }, { "type": "null" } ] }, "skipLogic": { "$ref": "#/components/schemas/SkipLogic" }, "aiFollowUp": { "type": [ "object", "null" ], "properties": { "userPrompt": { "type": [ "string", "null" ] } }, "required": [ "userPrompt" ], "additionalProperties": false }, "randomizePosition": { "type": "boolean" }, "description": { "$ref": "#/components/schemas/QuestionDescription" }, "type": { "type": "string", "enum": [ "VALIDATED_TEXT" ] }, "validation": { "$ref": "#/components/schemas/ValidatedTextValidation" }, "responsePlaceholder": { "type": "string", "description": "Placeholder shown in the response field." }, "validationErrorMessage": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Error shown when the response does not satisfy validation." }, "footer": { "$ref": "#/components/schemas/QuestionFooter" } }, "required": [ "id", "title", "required", "displayLogic", "skipLogic", "aiFollowUp", "randomizePosition", "type", "validation" ], "additionalProperties": false, "description": "Canonical validated-text Question resource." }, "ValidatedTextValidation": { "oneOf": [ { "$ref": "#/components/schemas/EmailValidation" }, { "$ref": "#/components/schemas/UrlValidation" }, { "$ref": "#/components/schemas/RegexValidation" }, { "$ref": "#/components/schemas/NumberValidation" }, { "$ref": "#/components/schemas/PhoneValidation" } ], "discriminator": { "propertyName": "type", "mapping": { "EMAIL": "#/components/schemas/EmailValidation", "URL": "#/components/schemas/UrlValidation", "REGEX": "#/components/schemas/RegexValidation", "NUMBER": "#/components/schemas/NumberValidation", "PHONE": "#/components/schemas/PhoneValidation" } }, "description": "The validation rule applied to a validated-text response." }, "EmailValidation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "EMAIL" ] } }, "required": [ "type" ], "additionalProperties": false, "description": "Requires a valid email address." }, "UrlValidation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "URL" ] } }, "required": [ "type" ], "additionalProperties": false, "description": "Requires a valid URL." }, "RegexValidation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "REGEX" ] }, "pattern": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Regular expression the complete response must match." } }, "required": [ "type", "pattern" ], "additionalProperties": false, "description": "Requires a response matching a custom regular expression." }, "NumberValidation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "NUMBER" ] }, "min": { "type": "number", "description": "Optional inclusive minimum; min and max must be supplied together." }, "max": { "type": "number", "description": "Optional inclusive maximum; min and max must be supplied together." }, "allowDecimals": { "type": "boolean", "default": false, "description": "Whether decimal responses are accepted." } }, "required": [ "type" ], "additionalProperties": false, "description": "Requires a numeric response, optionally within a whole-number range." }, "PhoneValidation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PHONE" ] }, "countries": { "type": "array", "items": { "type": "string", "enum": [ "US", "CA" ] }, "minItems": 1, "description": "Allowed phone-number country or region codes." } }, "required": [ "type", "countries" ], "additionalProperties": false, "description": "Requires a phone number from one of the allowed countries or regions." }, "QuestionFooter": { "type": "object", "properties": { "html": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/AttributeVariable" }, { "$ref": "#/components/schemas/QuestionResponseVariable" } ], "discriminator": { "propertyName": "type", "mapping": { "ATTRIBUTE": "#/components/schemas/AttributeVariable", "QUESTION_RESPONSE": "#/components/schemas/QuestionResponseVariable" } } } } }, "required": [ "html", "variables" ], "additionalProperties": false, "description": "Canonical respondent-facing Question footer." }, "RankOrderQuestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "title": { "$ref": "#/components/schemas/QuestionTitle" }, "required": { "type": "boolean" }, "displayLogic": { "anyOf": [ { "$ref": "#/components/schemas/DisplayLogic" }, { "type": "null" } ] }, "skipLogic": { "$ref": "#/components/schemas/SkipLogic" }, "aiFollowUp": { "type": [ "object", "null" ], "properties": { "userPrompt": { "type": [ "string", "null" ] } }, "required": [ "userPrompt" ], "additionalProperties": false }, "randomizePosition": { "type": "boolean" }, "description": { "$ref": "#/components/schemas/QuestionDescription" }, "type": { "type": "string", "enum": [ "RANK_ORDER" ] }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/RankOrderOption" }, "minItems": 2 }, "randomizeOptions": { "type": "boolean" }, "labelForHighestRank": { "type": "string", "maxLength": 255 }, "labelForLowestRank": { "type": "string", "maxLength": 255 }, "carryForward": { "$ref": "#/components/schemas/CarryForward" } }, "required": [ "id", "title", "required", "displayLogic", "skipLogic", "aiFollowUp", "randomizePosition", "type", "options", "randomizeOptions", "labelForHighestRank", "labelForLowestRank" ], "additionalProperties": false, "description": "Canonical rank-order Question resource." }, "RankOrderOption": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Immutable caller-defined value used by responses and Question logic." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Text shown to respondents." } }, "required": [ "value", "label" ], "additionalProperties": false, "description": "One ordered item returned with a rank-order Question." }, "MatrixQuestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "title": { "$ref": "#/components/schemas/QuestionTitle" }, "required": { "type": "boolean" }, "displayLogic": { "anyOf": [ { "$ref": "#/components/schemas/DisplayLogic" }, { "type": "null" } ] }, "skipLogic": { "$ref": "#/components/schemas/SkipLogic" }, "aiFollowUp": { "type": [ "object", "null" ], "properties": { "userPrompt": { "type": [ "string", "null" ] } }, "required": [ "userPrompt" ], "additionalProperties": false }, "randomizePosition": { "type": "boolean" }, "description": { "$ref": "#/components/schemas/QuestionDescription" }, "type": { "type": "string", "enum": [ "MATRIX" ] }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixItem" }, "minItems": 2 }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixItem" }, "minItems": 2 }, "randomizeRows": { "type": "boolean" }, "displayLimit": { "type": "integer", "minimum": 2, "description": "Total number of authored choices shown to each respondent, including pinned choices." }, "carryForward": { "$ref": "#/components/schemas/CarryForward" } }, "required": [ "id", "title", "required", "displayLogic", "skipLogic", "aiFollowUp", "randomizePosition", "type", "rows", "columns", "randomizeRows" ], "additionalProperties": false, "description": "Canonical Matrix Question resource." }, "MatrixItem": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Immutable caller-defined value used by responses and Question logic." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Text shown to respondents." } }, "required": [ "value", "label" ], "additionalProperties": false, "description": "One ordered Matrix row or column." }, "TextUrlPromptQuestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "title": { "$ref": "#/components/schemas/QuestionTitle" }, "required": { "type": "boolean" }, "displayLogic": { "anyOf": [ { "$ref": "#/components/schemas/DisplayLogic" }, { "type": "null" } ] }, "skipLogic": { "$ref": "#/components/schemas/SkipLogic" }, "aiFollowUp": { "type": [ "object", "null" ], "properties": { "userPrompt": { "type": [ "string", "null" ] } }, "required": [ "userPrompt" ], "additionalProperties": false }, "randomizePosition": { "type": "boolean" }, "description": { "$ref": "#/components/schemas/QuestionDescription" }, "type": { "type": "string", "enum": [ "TEXT_URL_PROMPT" ] }, "action": { "$ref": "#/components/schemas/TextUrlPromptActionResponse" }, "skipButtonText": { "type": "string" } }, "required": [ "id", "title", "required", "displayLogic", "skipLogic", "aiFollowUp", "randomizePosition", "type", "action" ], "additionalProperties": false, "description": "Canonical Text/URL Prompt resource." }, "TextUrlPromptActionResponse": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CONTINUE" ] }, "buttonText": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "EXTERNAL" ] }, "buttonText": { "type": "string" }, "buttonUrl": { "type": "string" } }, "required": [ "type", "buttonText", "buttonUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "NO_BUTTON" ] } }, "required": [ "type" ], "additionalProperties": false } ], "description": "Stored button behavior returned for a Text/URL Prompt." }, "CreateQuestionInput": { "oneOf": [ { "$ref": "#/components/schemas/OpenTextQuestionInput" }, { "$ref": "#/components/schemas/SingleSelectQuestionInput" }, { "$ref": "#/components/schemas/MultipleSelectQuestionInput" }, { "$ref": "#/components/schemas/RatingScaleQuestionInput" }, { "$ref": "#/components/schemas/NpsQuestionInput" }, { "$ref": "#/components/schemas/ValidatedTextQuestionInput" }, { "$ref": "#/components/schemas/RankOrderQuestionInput" }, { "$ref": "#/components/schemas/MatrixQuestionInput" }, { "$ref": "#/components/schemas/TextUrlPromptQuestionInput" }, { "$ref": "#/components/schemas/AiDynamicQuestionInput" } ], "discriminator": { "propertyName": "type", "mapping": { "OPEN_TEXT": "#/components/schemas/OpenTextQuestionInput", "RATING_SCALE": "#/components/schemas/RatingScaleQuestionInput", "NPS": "#/components/schemas/NpsQuestionInput", "VALIDATED_TEXT": "#/components/schemas/ValidatedTextQuestionInput", "TEXT_URL_PROMPT": "#/components/schemas/TextUrlPromptQuestionInput" } }, "description": "Supported Question input for the Study creation API." }, "OpenTextQuestionInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional stable caller-defined name, unique within the Study." }, "title": { "$ref": "#/components/schemas/QuestionTitleInput" }, "required": { "type": "boolean", "default": false, "description": "Whether the respondent must answer the Question." }, "randomizePosition": { "type": "boolean", "description": "Whether this Question participates in layout-position randomization. Defaults to false." }, "position": { "$ref": "#/components/schemas/QuestionPosition" }, "blockId": { "type": "string", "format": "uuid", "description": "Public UUID of the Block that will contain this Question." }, "description": { "$ref": "#/components/schemas/QuestionDescriptionInput" }, "type": { "type": "string", "enum": [ "OPEN_TEXT" ] }, "responsePlaceholder": { "type": "string", "description": "Placeholder shown in the response field." } }, "required": [ "title", "type" ], "additionalProperties": false, "description": "Input for creating an open-text Question." }, "QuestionTitleInput": { "type": "object", "properties": { "html": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Plain text or rich-text HTML for the Question title. Unsupported or unsafe markup is rejected." }, "variables": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/AttributeVariable" }, { "$ref": "#/components/schemas/QuestionResponseVariable" } ], "discriminator": { "propertyName": "type", "mapping": { "ATTRIBUTE": "#/components/schemas/AttributeVariable", "QUESTION_RESPONSE": "#/components/schemas/QuestionResponseVariable" } } }, "default": {} } }, "required": [ "html" ], "additionalProperties": false, "description": "The authored title accepted when creating a Question." }, "QuestionPosition": { "type": "object", "properties": { "placement": { "$ref": "#/components/schemas/QuestionPositionPlacement" }, "anchor": { "$ref": "#/components/schemas/QuestionPositionAnchor" } }, "required": [ "placement", "anchor" ], "additionalProperties": false, "description": "Placement of a Question relative to another Question in the Study." }, "QuestionPositionPlacement": { "type": "string", "enum": [ "BEFORE", "AFTER" ], "description": "Where to place the Question relative to the anchor Question." }, "QuestionPositionAnchor": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Public UUID of the anchor Question." } }, "required": [ "id" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Unique name of the anchor Question." } }, "required": [ "name" ], "additionalProperties": false } ], "description": "Exactly one identifier for an existing Question in the Study." }, "QuestionDescriptionInput": { "type": "object", "properties": { "html": { "type": "string", "minLength": 1, "description": "Plain text or rich-text HTML. Unsupported or unsafe markup is rejected." }, "variables": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/AttributeVariable" }, { "$ref": "#/components/schemas/QuestionResponseVariable" } ], "discriminator": { "propertyName": "type", "mapping": { "ATTRIBUTE": "#/components/schemas/AttributeVariable", "QUESTION_RESPONSE": "#/components/schemas/QuestionResponseVariable" } } }, "default": {} } }, "required": [ "html" ], "additionalProperties": false, "description": "Optional respondent-facing description shown with a Question." }, "SingleSelectQuestionInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional stable caller-defined name, unique within the Study." }, "title": { "$ref": "#/components/schemas/QuestionTitleInput" }, "required": { "type": "boolean", "default": false, "description": "Whether the respondent must answer the Question." }, "randomizePosition": { "type": "boolean", "description": "Whether this Question participates in layout-position randomization. Defaults to false." }, "position": { "$ref": "#/components/schemas/QuestionPosition" }, "blockId": { "type": "string", "format": "uuid", "description": "Public UUID of the Block that will contain this Question." }, "description": { "$ref": "#/components/schemas/QuestionDescriptionInput" }, "type": { "type": "string", "enum": [ "SINGLE_SELECT" ] }, "randomizeOptions": { "type": "boolean", "default": false, "description": "Whether eligible Options are randomized for each respondent." }, "presentation": { "type": "string", "enum": [ "LIST", "DROPDOWN" ], "default": "LIST", "description": "How the Options are presented to respondents." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionOption" }, "minItems": 2 }, "carryForward": { "$ref": "#/components/schemas/CarryForward" } }, "required": [ "title", "type" ], "additionalProperties": false, "description": "Input for creating a single-select Question with ordered Options." }, "QuestionOption": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Immutable caller-defined value used by responses and Question logic." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Text shown to respondents." }, "behavior": { "$ref": "#/components/schemas/QuestionOptionBehavior" }, "textEntryPlaceholder": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Placeholder shown only for OTHER_TEXT Options." } }, "required": [ "value", "label" ], "additionalProperties": false, "description": "One ordered answer Option owned by a choice Question." }, "QuestionOptionBehavior": { "type": "string", "enum": [ "REGULAR", "PINNED", "OTHER_TEXT", "NONE_OF_THE_ABOVE" ], "default": "REGULAR", "description": "REGULAR is ordinary, PINNED stays fixed, OTHER_TEXT accepts additional text, and NONE_OF_THE_ABOVE clears other selections." }, "MultipleSelectQuestionInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional stable caller-defined name, unique within the Study." }, "title": { "$ref": "#/components/schemas/QuestionTitleInput" }, "required": { "type": "boolean", "default": false, "description": "Whether the respondent must answer the Question." }, "randomizePosition": { "type": "boolean", "description": "Whether this Question participates in layout-position randomization. Defaults to false." }, "position": { "$ref": "#/components/schemas/QuestionPosition" }, "blockId": { "type": "string", "format": "uuid", "description": "Public UUID of the Block that will contain this Question." }, "description": { "$ref": "#/components/schemas/QuestionDescriptionInput" }, "type": { "type": "string", "enum": [ "MULTIPLE_SELECT" ] }, "randomizeOptions": { "type": "boolean", "default": false, "description": "Whether eligible Options are randomized for each respondent." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionOption" }, "minItems": 2 }, "carryForward": { "$ref": "#/components/schemas/CarryForward" }, "selection": { "$ref": "#/components/schemas/MultipleSelectSelection" }, "displayLimit": { "type": "integer", "minimum": 2, "description": "Total number of authored choices shown to each respondent, including pinned choices." } }, "required": [ "title", "type" ], "additionalProperties": false, "description": "Input for creating a multiple-select Question with ordered Options." }, "RatingScaleQuestionInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional stable caller-defined name, unique within the Study." }, "title": { "$ref": "#/components/schemas/QuestionTitleInput" }, "required": { "type": "boolean", "default": false, "description": "Whether the respondent must answer the Question." }, "randomizePosition": { "type": "boolean", "description": "Whether this Question participates in layout-position randomization. Defaults to false." }, "position": { "$ref": "#/components/schemas/QuestionPosition" }, "blockId": { "type": "string", "format": "uuid", "description": "Public UUID of the Block that will contain this Question." }, "description": { "$ref": "#/components/schemas/QuestionDescriptionInput" }, "type": { "type": "string", "enum": [ "RATING_SCALE" ] }, "range": { "$ref": "#/components/schemas/RatingScaleRange" }, "scaleLabelType": { "$ref": "#/components/schemas/RatingScaleLabelType" }, "lowEndLabel": { "type": [ "string", "null" ], "maxLength": 255, "description": "Optional label shown at one endpoint of the scale." }, "highEndLabel": { "type": [ "string", "null" ], "maxLength": 255, "description": "Optional label shown at one endpoint of the scale." } }, "required": [ "title", "type", "range", "scaleLabelType" ], "additionalProperties": false, "description": "Input for creating a rating-scale Question." }, "NpsQuestionInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional stable caller-defined name, unique within the Study." }, "title": { "$ref": "#/components/schemas/QuestionTitleInput" }, "required": { "type": "boolean", "default": false, "description": "Whether the respondent must answer the Question." }, "randomizePosition": { "type": "boolean", "description": "Whether this Question participates in layout-position randomization. Defaults to false." }, "position": { "$ref": "#/components/schemas/QuestionPosition" }, "blockId": { "type": "string", "format": "uuid", "description": "Public UUID of the Block that will contain this Question." }, "description": { "$ref": "#/components/schemas/QuestionDescriptionInput" }, "type": { "type": "string", "enum": [ "NPS" ] }, "lowEndLabel": { "type": [ "string", "null" ], "maxLength": 255, "description": "Optional label shown at one endpoint of the scale." }, "highEndLabel": { "type": [ "string", "null" ], "maxLength": 255, "description": "Optional label shown at one endpoint of the scale." } }, "required": [ "title", "type" ], "additionalProperties": false, "description": "Input for creating a Net Promoter Score Question." }, "ValidatedTextQuestionInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional stable caller-defined name, unique within the Study." }, "title": { "$ref": "#/components/schemas/QuestionTitleInput" }, "required": { "type": "boolean", "default": false, "description": "Whether the respondent must answer the Question." }, "randomizePosition": { "type": "boolean", "description": "Whether this Question participates in layout-position randomization. Defaults to false." }, "position": { "$ref": "#/components/schemas/QuestionPosition" }, "blockId": { "type": "string", "format": "uuid", "description": "Public UUID of the Block that will contain this Question." }, "description": { "$ref": "#/components/schemas/QuestionDescriptionInput" }, "type": { "type": "string", "enum": [ "VALIDATED_TEXT" ] }, "validation": { "$ref": "#/components/schemas/ValidatedTextValidation" }, "responsePlaceholder": { "type": "string", "description": "Placeholder shown in the response field." }, "validationErrorMessage": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Error shown when the response does not satisfy validation." }, "footer": { "$ref": "#/components/schemas/QuestionFooterInput" } }, "required": [ "title", "type", "validation" ], "additionalProperties": false, "description": "Input for creating a validated-text Question." }, "QuestionFooterInput": { "type": "object", "properties": { "html": { "type": "string", "minLength": 1, "description": "Plain text or rich-text HTML. Unsupported or unsafe markup is rejected." }, "variables": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/AttributeVariable" }, { "$ref": "#/components/schemas/QuestionResponseVariable" } ], "discriminator": { "propertyName": "type", "mapping": { "ATTRIBUTE": "#/components/schemas/AttributeVariable", "QUESTION_RESPONSE": "#/components/schemas/QuestionResponseVariable" } } }, "default": {} } }, "required": [ "html" ], "additionalProperties": false, "description": "Optional respondent-facing footer shown below the response field." }, "RankOrderQuestionInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional stable caller-defined name, unique within the Study." }, "title": { "$ref": "#/components/schemas/QuestionTitleInput" }, "required": { "type": "boolean", "default": false, "description": "Whether the respondent must answer the Question." }, "randomizePosition": { "type": "boolean", "description": "Whether this Question participates in layout-position randomization. Defaults to false." }, "position": { "$ref": "#/components/schemas/QuestionPosition" }, "blockId": { "type": "string", "format": "uuid", "description": "Public UUID of the Block that will contain this Question." }, "description": { "$ref": "#/components/schemas/QuestionDescriptionInput" }, "type": { "type": "string", "enum": [ "RANK_ORDER" ] }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/RankOrderOptionInput" }, "minItems": 2 }, "carryForward": { "$ref": "#/components/schemas/CarryForward" }, "randomizeOptions": { "type": "boolean", "default": false, "description": "Whether eligible Options are randomized for each respondent." }, "labelForHighestRank": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Label shown above the highest-ranked item." }, "labelForLowestRank": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Label shown below the lowest-ranked item." } }, "required": [ "title", "type", "labelForHighestRank", "labelForLowestRank" ], "additionalProperties": false, "description": "Input for creating a rank-order Question with ordered items." }, "RankOrderOptionInput": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Immutable caller-defined value used by responses and Question logic." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Text shown to respondents." } }, "required": [ "value", "label" ], "additionalProperties": false, "description": "One ordered item to rank. Its value is immutable; its label may be updated." }, "MatrixQuestionInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional stable caller-defined name, unique within the Study." }, "title": { "$ref": "#/components/schemas/QuestionTitleInput" }, "required": { "type": "boolean", "default": false, "description": "Whether the respondent must answer the Question." }, "randomizePosition": { "type": "boolean", "description": "Whether this Question participates in layout-position randomization. Defaults to false." }, "position": { "$ref": "#/components/schemas/QuestionPosition" }, "blockId": { "type": "string", "format": "uuid", "description": "Public UUID of the Block that will contain this Question." }, "description": { "$ref": "#/components/schemas/QuestionDescriptionInput" }, "type": { "type": "string", "enum": [ "MATRIX" ] }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixItemInput" }, "minItems": 2 }, "carryForward": { "$ref": "#/components/schemas/CarryForward" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixItemInput" }, "minItems": 2 }, "randomizeRows": { "type": "boolean", "default": false, "description": "Whether Matrix rows are randomized for each respondent." }, "displayLimit": { "type": "integer", "minimum": 2, "description": "Total number of authored choices shown to each respondent, including pinned choices." } }, "required": [ "title", "type", "columns" ], "additionalProperties": false, "description": "Input for creating a Matrix Question with ordered rows and columns." }, "MatrixItemInput": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Immutable caller-defined value used by responses and Question logic." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Text shown to respondents." } }, "required": [ "value", "label" ], "additionalProperties": false, "description": "One ordered Matrix row or column. Its value is immutable; its label may be updated." }, "TextUrlPromptQuestionInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional stable caller-defined name, unique within the Study." }, "title": { "$ref": "#/components/schemas/QuestionTitleInput" }, "required": { "type": "boolean", "default": false, "description": "Whether the respondent must answer the Question." }, "randomizePosition": { "type": "boolean", "description": "Whether this Question participates in layout-position randomization. Defaults to false." }, "position": { "$ref": "#/components/schemas/QuestionPosition" }, "blockId": { "type": "string", "format": "uuid", "description": "Public UUID of the Block that will contain this Question." }, "description": { "$ref": "#/components/schemas/QuestionDescriptionInput" }, "type": { "type": "string", "enum": [ "TEXT_URL_PROMPT" ] }, "action": { "$ref": "#/components/schemas/TextUrlPromptAction" }, "skipButtonText": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "title", "type", "action" ], "additionalProperties": false, "description": "Input for creating an informational Text/URL Prompt." }, "TextUrlPromptAction": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CONTINUE" ] }, "buttonText": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "EXTERNAL" ] }, "buttonText": { "type": "string", "minLength": 1, "maxLength": 255 }, "buttonUrl": { "type": "string", "format": "uri" } }, "required": [ "type", "buttonText", "buttonUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "NO_BUTTON" ] } }, "required": [ "type" ], "additionalProperties": false } ], "description": "Button behavior for a Text/URL Prompt." }, "AiDynamicQuestionInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional stable caller-defined name, unique within the Study." }, "type": { "type": "string", "enum": [ "AI_DYNAMIC" ] }, "required": { "type": "boolean", "default": false, "description": "Whether the respondent must answer the Question." }, "randomizePosition": { "type": "boolean", "description": "Whether this Question participates in layout-position randomization. Defaults to false." }, "position": { "$ref": "#/components/schemas/QuestionPosition" }, "blockId": { "type": "string", "format": "uuid", "description": "Public UUID of the Block that will contain this Question." }, "userPrompt": { "type": [ "string", "null" ], "default": null, "description": "Optional plain-text guidance for the generated question." } }, "required": [ "type" ], "additionalProperties": false, "description": "Input for creating a standalone AI Dynamic Question." }, "TranslationJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "targetLocale": { "type": "string" }, "mode": { "$ref": "#/components/schemas/TranslationJobMode" }, "status": { "$ref": "#/components/schemas/TranslationJobStatus" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "progress": { "type": "object", "additionalProperties": {} }, "result": { "type": "object", "additionalProperties": {} }, "error": { "$ref": "#/components/schemas/TranslationJobError" } }, "required": [ "id", "targetLocale", "mode", "status", "createdAt", "updatedAt" ], "additionalProperties": false, "description": "Canonical state and result metadata for one asynchronous translation job." }, "TranslationJobMode": { "type": "string", "enum": [ "FILL_MISSING", "REPLACE_ALL" ], "description": "Whether generation fills only missing values or replaces every translated value." }, "TranslationJobStatus": { "type": "string", "enum": [ "PENDING", "RUNNING", "COMPLETED", "FAILED", "CANCELLED" ], "description": "PENDING and RUNNING jobs can be cancelled. CANCELLED means no further translation output will be persisted. COMPLETED and FAILED are terminal. Cancelling does not roll back translations already committed by a completed job." }, "TranslationJobError": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, "CreateInvitationsBody": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many invitations to generate." }, "idempotencyKey": { "type": "string", "minLength": 1, "description": "A key you choose to name this batch. Sending the same key again returns the batch it first created and generates nothing new, even if `count` differs, so a retried request never doubles up on invitations." } }, "required": [ "count", "idempotencyKey" ], "additionalProperties": false, "description": "A request for one batch of invitations." } }, "parameters": {} }, "paths": { "/v2/studies": { "post": { "operationId": "createStudy", "summary": "Create a draft Study", "description": "Creates a draft Study shell. Questions are created separately.", "tags": [ "Studies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStudyRequest" } } } }, "responses": { "201": { "description": "Created", "headers": { "ETag": { "description": "Quoted Study version validator matching surveys.version, for example \"126300\".", "schema": { "type": "string", "example": "\"126300\"" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Study" } } } }, "400": { "description": "The request is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "listStudies", "summary": "List Studies", "description": "Returns a cursor-paginated page of Studies.", "tags": [ "Studies" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 999 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "DRAFT", "IN_PROGRESS", "PAUSED", "COMPLETED", "ARCHIVED" ] }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "OK" }, "400": { "description": "The request is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/studies/{studyId}": { "get": { "operationId": "getStudy", "summary": "Get a Study", "description": "Returns a single Study by id.", "tags": [ "Studies" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "studyId", "in": "path" } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Quoted Study version validator matching surveys.version, for example \"126300\".", "schema": { "type": "string", "example": "\"126300\"" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Study" } } } }, "400": { "description": "The request is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Study not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateStudy", "summary": "Update Study settings or lifecycle status", "description": "A settings PATCH may include `name` and/or `responseSettings`. A lifecycle PATCH must contain only `status`.", "tags": [ "Studies" ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "Quoted Study version last read from ETag or Study.version. Required on mutating Study writes.", "schema": { "type": "string", "example": "\"126300\"" } }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "studyId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStudyRequest" } } } }, "responses": { "204": { "description": "No Content", "headers": { "ETag": { "description": "Quoted Study version validator matching surveys.version, for example \"126300\".", "schema": { "type": "string", "example": "\"126300\"" } } } }, "400": { "description": "The request is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Study not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The Study is not editable in its current status, or the requested lifecycle transition is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match does not match the current Study version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but fails a business-rule validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "428": { "description": "A valid If-Match header is required to update this Study.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteStudy", "summary": "Delete a draft or paused Study", "description": "Deletes a Study. Only DRAFT or PAUSED Studies may be deleted.", "tags": [ "Studies" ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "Quoted Study version last read from ETag or Study.version. Required on mutating Study writes.", "schema": { "type": "string", "example": "\"126300\"" } }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "studyId", "in": "path" } ], "responses": { "204": { "description": "No Content", "headers": { "ETag": { "description": "Quoted Study version validator matching surveys.version, for example \"126300\".", "schema": { "type": "string", "example": "\"126300\"" } } } }, "400": { "description": "The request is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Study not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The Study is not in a deletable state (must be new or draft).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match does not match the current Study version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "428": { "description": "A valid If-Match header is required to update this Study.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/studies/{studyId}/questions": { "post": { "operationId": "createQuestion", "summary": "Create a Question", "description": "Creates a Question, with its options, nested under the given Study.", "tags": [ "Questions" ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "Quoted Study version last read from ETag or Study.version. Required on mutating Study writes.", "schema": { "type": "string", "example": "\"126300\"" } }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "studyId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuestionInput" } } } }, "responses": { "201": { "description": "Created", "headers": { "ETag": { "description": "Quoted Study version validator matching surveys.version, for example \"126300\".", "schema": { "type": "string", "example": "\"126300\"" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Question" } } } }, "400": { "description": "The request is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Study not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The Study is not editable in its current status, or a conflicting update is already in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match does not match the current Study version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but fails a business-rule validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "428": { "description": "A valid If-Match header is required to update this Study.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/studies/{studyId}/validate": { "post": { "operationId": "validateStudy", "summary": "Validate a Study", "description": "Returns the set of issues, if any, blocking the Study from launching.", "tags": [ "Studies" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "studyId", "in": "path" } ], "responses": { "200": { "description": "OK" }, "400": { "description": "The request is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Study not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/studies/{studyId}/invitations": { "get": { "operationId": "listInvitations", "summary": "List invitations", "description": "Returns a cursor-paginated page of invitations for a Study.", "tags": [ "Invitations" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "studyId", "in": "path" }, { "schema": { "type": "string", "enum": [ "OPEN", "SPENT", "EXPIRED" ], "description": "Returns only the invitations in this state. `OPEN` invitations can still be answered, `SPENT` invitations already carry a response, and `EXPIRED` invitations are past the Study close date. A Study that allows unlimited responses per invitation never has `SPENT` invitations." }, "required": true, "description": "Returns only the invitations in this state. `OPEN` invitations can still be answered, `SPENT` invitations already carry a response, and `EXPIRED` invitations are past the Study close date. A Study that allows unlimited responses per invitation never has `SPENT` invitations.", "name": "status", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50, "description": "How many invitations to return per page." }, "required": false, "description": "How many invitations to return per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 999, "description": "The `cursor` returned by the previous page. Omit it to read the first page." }, "required": false, "description": "The `cursor` returned by the previous page. Omit it to read the first page.", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK" }, "400": { "description": "The request is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Study not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but fails a business-rule validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createInvitations", "summary": "Create invitations", "description": "Creates a batch of invitations for a Study.", "tags": [ "Invitations" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "studyId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitationsBody" } } } }, "responses": { "201": { "description": "Created" }, "400": { "description": "The request is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Study not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/studies/{studyId}/translationJobs/{jobId}": { "delete": { "operationId": "cancelTranslationJob", "summary": "Cancel a translation job", "description": "Requests cancellation of an in-progress translation job. Cancellation is best-effort: the study-translation workflow is signalled to stop, and the job is recorded as CANCELLED only while it is still PENDING or RUNNING. CANCELLED means no further translation output will be persisted. Cancelling does not roll back translations already committed by a completed job. Repeating the request for a job that is already CANCELLED returns that job.", "tags": [ "Translations" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "studyId", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "jobId", "in": "path" } ], "responses": { "200": { "description": "The job is CANCELLED. Cancellation is best-effort, and CANCELLED means no further translation output will be persisted. An already-cancelled job returns the same job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationJob" } } } }, "400": { "description": "The request is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The Study or translation job was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The job is COMPLETED or FAILED and cannot be cancelled. Cancelling does not roll back translations already committed by a completed job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "webhooks": {} }