openapi: 3.0.3 info: title: PostHog actions surveys API version: 1.0.0 description: '' tags: - name: surveys paths: /api/projects/{project_id}/surveys/: get: operationId: surveys_list parameters: - in: query name: archived schema: type: boolean - name: limit required: false in: query description: Number of results to return per page. schema: type: integer - name: offset required: false in: query description: The initial index from which to return the results. schema: type: integer - $ref: '#/components/parameters/ProjectIdPath' - name: search required: false in: query description: A search term. schema: type: string tags: - surveys security: - PersonalAPIKeyAuth: - survey:read responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedSurveyList' description: '' x-explicit-tags: - surveys post: operationId: surveys_create parameters: - $ref: '#/components/parameters/ProjectIdPath' tags: - surveys requestBody: content: application/json: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnlySchema' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnlySchema' multipart/form-data: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnlySchema' required: true security: - PersonalAPIKeyAuth: - survey:write responses: '201': content: application/json: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' description: '' x-explicit-tags: - surveys /api/projects/{project_id}/surveys/{id}/: get: operationId: surveys_retrieve parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this survey. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - surveys security: - PersonalAPIKeyAuth: - survey:read responses: '200': content: application/json: schema: $ref: '#/components/schemas/Survey' description: '' x-explicit-tags: - surveys put: operationId: surveys_update parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this survey. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - surveys requestBody: content: application/json: schema: $ref: '#/components/schemas/Survey' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Survey' multipart/form-data: schema: $ref: '#/components/schemas/Survey' required: true security: - PersonalAPIKeyAuth: - survey:write responses: '200': content: application/json: schema: $ref: '#/components/schemas/Survey' description: '' x-explicit-tags: - surveys patch: operationId: surveys_partial_update parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this survey. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - surveys requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedSurveySerializerCreateUpdateOnlySchema' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedSurveySerializerCreateUpdateOnlySchema' multipart/form-data: schema: $ref: '#/components/schemas/PatchedSurveySerializerCreateUpdateOnlySchema' security: - PersonalAPIKeyAuth: - survey:write responses: '200': content: application/json: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' description: '' x-explicit-tags: - surveys delete: operationId: surveys_destroy parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this survey. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - surveys security: - PersonalAPIKeyAuth: - survey:write responses: '204': description: No response body x-explicit-tags: - surveys /api/projects/{project_id}/surveys/{id}/activity/: get: operationId: surveys_activity_retrieve parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this survey. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - surveys security: - PersonalAPIKeyAuth: - activity_log:read responses: '200': description: No response body x-explicit-tags: - surveys /api/projects/{project_id}/surveys/{id}/archived-response-uuids/: get: operationId: surveys_archived_response_uuids_retrieve description: 'Get list of archived response UUIDs for HogQL filtering. Returns list of UUIDs that the frontend can use to filter out archived responses in HogQL queries.' parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this survey. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - surveys security: - PersonalAPIKeyAuth: - survey:read responses: '200': description: No response body x-explicit-tags: - surveys /api/projects/{project_id}/surveys/{id}/duplicate_to_projects/: post: operationId: surveys_duplicate_to_projects_create description: 'Duplicate a survey to multiple projects in a single transaction. Accepts a list of target team IDs and creates a copy of the survey in each project. Uses an all-or-nothing approach - if any duplication fails, all changes are rolled back.' parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this survey. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - surveys requestBody: content: application/json: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' multipart/form-data: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' required: true security: - PersonalAPIKeyAuth: - survey:write responses: '200': description: No response body x-explicit-tags: - surveys /api/projects/{project_id}/surveys/{id}/generate_translations/: post: operationId: surveys_generate_translations_create parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this survey. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - surveys requestBody: content: application/json: schema: $ref: '#/components/schemas/GenerateSurveyTranslationsRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/GenerateSurveyTranslationsRequest' multipart/form-data: schema: $ref: '#/components/schemas/GenerateSurveyTranslationsRequest' required: true security: - PersonalAPIKeyAuth: - survey:write responses: '200': content: application/json: schema: $ref: '#/components/schemas/GenerateSurveyTranslationsResponse' description: '' x-explicit-tags: - surveys /api/projects/{project_id}/surveys/{id}/responses/{response_uuid}/archive/: post: operationId: surveys_responses_archive_create description: Archive a single survey response. parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this survey. required: true - $ref: '#/components/parameters/ProjectIdPath' - in: path name: response_uuid schema: type: string pattern: ^[^/]+$ required: true tags: - surveys requestBody: content: application/json: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' multipart/form-data: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' required: true security: - PersonalAPIKeyAuth: - survey:write responses: '200': description: No response body x-explicit-tags: - surveys /api/projects/{project_id}/surveys/{id}/responses/{response_uuid}/unarchive/: post: operationId: surveys_responses_unarchive_create description: Unarchive a single survey response. parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this survey. required: true - $ref: '#/components/parameters/ProjectIdPath' - in: path name: response_uuid schema: type: string pattern: ^[^/]+$ required: true tags: - surveys requestBody: content: application/json: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' multipart/form-data: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' required: true security: - PersonalAPIKeyAuth: - survey:write responses: '200': description: No response body x-explicit-tags: - surveys /api/projects/{project_id}/surveys/{id}/stats/: get: operationId: surveys_stats_retrieve description: "Get survey response statistics for a specific survey.\n\nArgs:\n date_from: Optional ISO timestamp for start date (e.g. 2024-01-01T00:00:00Z)\n date_to: Optional ISO timestamp for end date (e.g. 2024-01-31T23:59:59Z)\n exclude_archived: Optional boolean to exclude archived responses (default: false, includes archived)\n\nReturns:\n Survey statistics including event counts, unique respondents, and conversion rates" parameters: - in: query name: date_from schema: type: string format: date-time description: Optional ISO timestamp for start date (e.g. 2024-01-01T00:00:00Z) - in: query name: date_to schema: type: string format: date-time description: Optional ISO timestamp for end date (e.g. 2024-01-31T23:59:59Z) - in: path name: id schema: type: string format: uuid description: A UUID string identifying this survey. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - surveys security: - PersonalAPIKeyAuth: - survey:read responses: '200': content: application/json: schema: $ref: '#/components/schemas/SurveyStatsResponse' description: '' x-explicit-tags: - surveys /api/projects/{project_id}/surveys/{id}/summarize_responses/: post: operationId: surveys_summarize_responses_create parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this survey. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - surveys requestBody: content: application/json: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' multipart/form-data: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' required: true security: - PersonalAPIKeyAuth: - survey:read responses: '200': description: No response body x-explicit-tags: - surveys /api/projects/{project_id}/surveys/{id}/summary_headline/: post: operationId: surveys_summary_headline_create parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this survey. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - surveys requestBody: content: application/json: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' multipart/form-data: schema: $ref: '#/components/schemas/SurveySerializerCreateUpdateOnly' required: true security: - PersonalAPIKeyAuth: - survey:read responses: '200': description: No response body x-explicit-tags: - surveys /api/projects/{project_id}/surveys/activity/: get: operationId: surveys_all_activity_retrieve parameters: - $ref: '#/components/parameters/ProjectIdPath' tags: - surveys security: - PersonalAPIKeyAuth: - activity_log:read responses: '200': description: No response body x-explicit-tags: - surveys /api/projects/{project_id}/surveys/responses_count/: get: operationId: surveys_responses_count_retrieve description: "Get response counts for all surveys.\n\nArgs:\n exclude_archived: Optional boolean to exclude archived responses (default: false, includes archived)\n survey_ids: Optional comma-separated list of survey IDs to filter by\n\nReturns:\n Dictionary mapping survey IDs to response counts" parameters: - $ref: '#/components/parameters/ProjectIdPath' tags: - surveys security: - PersonalAPIKeyAuth: - survey:read responses: '200': description: No response body x-explicit-tags: - surveys /api/projects/{project_id}/surveys/stats/: get: operationId: surveys_global_stats_retrieve description: "Get aggregated response statistics across all surveys.\n\nArgs:\n date_from: Optional ISO timestamp for start date (e.g. 2024-01-01T00:00:00Z)\n date_to: Optional ISO timestamp for end date (e.g. 2024-01-31T23:59:59Z)\n\nReturns:\n Aggregated statistics across all surveys including total counts and rates" parameters: - in: query name: date_from schema: type: string format: date-time description: Optional ISO timestamp for start date (e.g. 2024-01-01T00:00:00Z) - in: query name: date_to schema: type: string format: date-time description: Optional ISO timestamp for end date (e.g. 2024-01-31T23:59:59Z) - $ref: '#/components/parameters/ProjectIdPath' tags: - surveys security: - PersonalAPIKeyAuth: - survey:read responses: '200': content: application/json: schema: $ref: '#/components/schemas/SurveyGlobalStatsResponse' description: '' x-explicit-tags: - surveys components: schemas: FeatureFlagFilterPropertyMultiContainsSchemaOperatorEnum: enum: - icontains_multi - not_icontains_multi type: string description: '* `icontains_multi` - icontains_multi * `not_icontains_multi` - not_icontains_multi' FeatureFlagFilterPropertySemverSchema: type: object properties: key: type: string description: Property key used in this feature flag condition. type: allOf: - $ref: '#/components/schemas/PropertyGroupTypeEnum' description: 'Property filter type. Common values are ''person'' and ''cohort''. * `cohort` - cohort * `person` - person * `group` - group' cohort_name: type: string nullable: true description: Resolved cohort name for cohort-type filters. group_type_index: type: integer nullable: true description: Group type index when using group-based filters. operator: allOf: - $ref: '#/components/schemas/FeatureFlagFilterPropertySemverSchemaOperatorEnum' description: 'Semantic version comparison operator. * `semver_gt` - semver_gt * `semver_gte` - semver_gte * `semver_lt` - semver_lt * `semver_lte` - semver_lte * `semver_eq` - semver_eq * `semver_neq` - semver_neq * `semver_tilde` - semver_tilde * `semver_caret` - semver_caret * `semver_wildcard` - semver_wildcard' value: type: string description: Semantic version string. required: - key - operator - value SurveyResponseBasedBranching: type: object properties: type: allOf: - $ref: '#/components/schemas/SurveyResponseBasedBranchingTypeEnum' description: 'Branch based on the selected or entered response. * `response_based` - response_based' responseValues: type: object additionalProperties: oneOf: - type: integer minimum: 0 - type: string enum: - end description: Response-based branching map. Values can be a question index or 'end'. required: - responseValues - type SurveyResponseBasedBranchingTypeEnum: enum: - response_based type: string description: '* `response_based` - response_based' FeatureFlagFilterPropertyCohortInSchemaOperatorEnum: enum: - in - not_in type: string description: '* `in` - in * `not_in` - not_in' SurveySerializerCreateUpdateOnlySchema: type: object properties: id: type: string format: uuid readOnly: true name: type: string description: Survey name. maxLength: 400 minLength: 1 description: type: string description: Survey description. type: allOf: - $ref: '#/components/schemas/SurveyType' description: 'Survey type. * `popover` - popover * `widget` - widget * `external_survey` - external survey * `api` - api' schedule: nullable: true description: 'Survey scheduling behavior: ''once'' = show once per user (default), ''recurring'' = repeat based on iteration_count and iteration_frequency_days settings, ''always'' = show every time conditions are met (mainly for widget surveys) * `once` - once * `recurring` - recurring * `always` - always' oneOf: - $ref: '#/components/schemas/ScheduleEnum' - $ref: '#/components/schemas/NullEnum' linked_flag: allOf: - $ref: '#/components/schemas/MinimalFeatureFlag' readOnly: true linked_flag_id: type: integer writeOnly: true nullable: true description: The feature flag linked to this survey. linked_insight_id: type: integer writeOnly: true nullable: true targeting_flag_id: type: integer writeOnly: true description: An existing targeting flag to use for this survey. targeting_flag: allOf: - $ref: '#/components/schemas/MinimalFeatureFlag' readOnly: true internal_targeting_flag: allOf: - $ref: '#/components/schemas/MinimalFeatureFlag' readOnly: true targeting_flag_filters: allOf: - $ref: '#/components/schemas/FeatureFlagFiltersSchema' writeOnly: true nullable: true description: 'Target specific users based on their properties. Example: {groups: [{properties: [{key: ''email'', value: [''@company.com''], operator: ''icontains''}], rollout_percentage: 100}]}' remove_targeting_flag: type: boolean writeOnly: true nullable: true description: Set to true to completely remove all targeting filters from the survey, making it visible to all users (subject to other display conditions like URL matching). questions: type: array items: $ref: '#/components/schemas/SurveyQuestionInputSchema' nullable: true description: "\n The `array` of questions included in the survey. Each question must conform to one of the defined question types: Basic, Link, Rating, or Multiple Choice.\n\n Basic (open-ended question)\n - `id`: The question ID\n - `type`: `open`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Link (a question with a link)\n - `id`: The question ID\n - `type`: `link`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `link`: The URL associated with the question.\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Rating (a question with a rating scale)\n - `id`: The question ID\n - `type`: `rating`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `display`: Display style of the rating (`number` or `emoji`).\n - `scale`: The scale of the rating (`number`).\n - `lowerBoundLabel`: Label for the lower bound of the scale.\n - `upperBoundLabel`: Label for the upper bound of the scale.\n - `isNpsQuestion`: Whether the question is an NPS rating.\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Multiple choice\n - `id`: The question ID\n - `type`: `single_choice` or `multiple_choice`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `choices`: An array of choices for the question.\n - `shuffleOptions`: Whether to shuffle the order of the choices (`boolean`).\n - `hasOpenChoice`: Whether the question allows an open-ended response (`boolean`).\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Branching logic can be one of the following types:\n\n Next question: Proceeds to the next question\n ```json\n {\n \"type\": \"next_question\"\n }\n ```\n\n End: Ends the survey, optionally displaying a confirmation message.\n ```json\n {\n \"type\": \"end\"\n }\n ```\n\n Response-based: Branches based on the response values. Available for the `rating` and `single_choice` question types.\n ```json\n {\n \"type\": \"response_based\",\n \"responseValues\": {\n \"responseKey\": \"value\"\n }\n }\n ```\n\n Specific question: Proceeds to a specific question by index.\n ```json\n {\n \"type\": \"specific_question\",\n \"index\": 2\n }\n ```\n\n Translations: Each question can include inline translations.\n - `translations`: Object mapping language codes to translated fields.\n - Language codes: Any string - allows customers to use their own language keys (e.g., \"es\", \"es-MX\", \"english\", \"french\")\n - Translatable fields: `question`, `description`, `buttonText`, `choices`, `lowerBoundLabel`, `upperBoundLabel`, `link`\n\n Example with translations:\n ```json\n {\n \"id\": \"uuid\",\n \"type\": \"rating\",\n \"question\": \"How satisfied are you?\",\n \"lowerBoundLabel\": \"Not satisfied\",\n \"upperBoundLabel\": \"Very satisfied\",\n \"translations\": {\n \"es\": {\n \"question\": \"¿Qué tan satisfecho estás?\",\n \"lowerBoundLabel\": \"No satisfecho\",\n \"upperBoundLabel\": \"Muy satisfecho\"\n },\n \"fr\": {\n \"question\": \"Dans quelle mesure êtes-vous satisfait?\"\n }\n }\n }\n ```\n " conditions: allOf: - $ref: '#/components/schemas/SurveyConditionsSchema' nullable: true description: Display and targeting conditions for the survey. appearance: allOf: - $ref: '#/components/schemas/SurveyAppearanceSchema' nullable: true description: Survey appearance customization. created_at: type: string format: date-time readOnly: true created_by: allOf: - $ref: '#/components/schemas/UserBasic' readOnly: true start_date: type: string format: date-time nullable: true description: Setting this will launch the survey immediately. Don't add a start_date unless explicitly requested to do so. end_date: type: string format: date-time nullable: true description: When the survey stopped being shown to users. Setting this will complete the survey. archived: type: boolean description: Archive state for the survey. responses_limit: type: integer nullable: true description: The maximum number of responses before automatically stopping the survey. iteration_count: type: integer maximum: 500 minimum: 1 nullable: true description: For a recurring schedule, this field specifies the number of times the survey should be shown to the user. Use 1 for 'once every X days', higher numbers for multiple repetitions. Works together with iteration_frequency_days to determine the overall survey schedule. iteration_frequency_days: type: integer maximum: 365 minimum: 1 nullable: true description: For a recurring schedule, this field specifies the interval in days between each survey instance shown to the user, used alongside iteration_count for precise scheduling. iteration_start_dates: type: array items: type: string format: date-time nullable: true nullable: true current_iteration: type: integer maximum: 2147483647 minimum: 0 nullable: true current_iteration_start_date: type: string format: date-time nullable: true response_sampling_start_date: type: string format: date-time nullable: true response_sampling_interval_type: nullable: true oneOf: - $ref: '#/components/schemas/ResponseSamplingIntervalTypeEnum' - $ref: '#/components/schemas/BlankEnum' - $ref: '#/components/schemas/NullEnum' response_sampling_interval: type: integer maximum: 2147483647 minimum: 0 nullable: true response_sampling_limit: type: integer maximum: 2147483647 minimum: 0 nullable: true response_sampling_daily_limits: nullable: true enable_partial_responses: type: boolean nullable: true description: When at least one question is answered, the response is stored (true). The response is stored when all questions are answered (false). enable_iframe_embedding: type: boolean nullable: true translations: nullable: true _create_in_folder: type: string writeOnly: true title: ' create in folder' form_content: nullable: true required: - created_at - created_by - id - internal_targeting_flag - linked_flag - name - targeting_flag - type RoleAtOrganizationEnum: enum: - engineering - data - product - founder - leadership - marketing - sales - other type: string description: '* `engineering` - Engineering * `data` - Data * `product` - Product Management * `founder` - Founder * `leadership` - Leadership * `marketing` - Marketing * `sales` - Sales / Success * `other` - Other' SurveyStatsResponse: type: object properties: survey_id: type: string description: The survey ID these stats belong to. start_date: type: string format: date-time nullable: true description: When the survey started collecting responses. end_date: type: string format: date-time nullable: true description: When the survey stopped collecting responses. stats: type: object additionalProperties: true description: Event counts keyed by event name (survey shown, survey dismissed, survey sent). rates: type: object additionalProperties: true description: Calculated response and dismissal rates. required: - end_date - rates - start_date - stats - survey_id SurveySpecificQuestionBranchingTypeEnum: enum: - specific_question type: string description: '* `specific_question` - specific_question' SurveyAppearanceSchema: type: object properties: backgroundColor: type: string submitButtonColor: type: string textColor: type: string submitButtonText: type: string submitButtonTextColor: type: string descriptionTextColor: type: string ratingButtonColor: type: string ratingButtonActiveColor: type: string ratingButtonHoverColor: type: string whiteLabel: type: boolean autoDisappear: type: boolean displayThankYouMessage: type: boolean thankYouMessageHeader: type: string thankYouMessageDescription: type: string thankYouMessageDescriptionContentType: $ref: '#/components/schemas/DescriptionContentTypeEnum' thankYouMessageCloseButtonText: type: string borderColor: type: string placeholder: type: string shuffleQuestions: type: boolean surveyPopupDelaySeconds: type: integer widgetType: $ref: '#/components/schemas/WidgetTypeEnum' widgetSelector: type: string widgetLabel: type: string widgetColor: type: string fontFamily: type: string maxWidth: type: string zIndex: type: string disabledButtonOpacity: type: string boxPadding: type: string SurveySingleChoiceQuestionSchema: type: object properties: type: $ref: '#/components/schemas/SurveySingleChoiceQuestionSchemaTypeEnum' question: type: string description: Question text shown to respondents. description: type: string description: Optional helper text. descriptionContentType: allOf: - $ref: '#/components/schemas/DescriptionContentTypeEnum' description: 'Format for the description field. * `text` - text * `html` - html' optional: type: boolean description: Whether respondents may skip this question. buttonText: type: string description: Custom button label. choices: type: array items: type: string description: Array of choice options. Choice indices (0, 1, 2, ...) are used for branching logic. maxItems: 20 minItems: 2 shuffleOptions: type: boolean description: Whether to randomize the order of choices for each respondent. hasOpenChoice: type: boolean description: Whether the final option should be an open-text choice (for example, 'Other'). branching: allOf: - $ref: '#/components/schemas/SurveyBranchingSchema' nullable: true required: - choices - question - type SurveyNextQuestionBranching: type: object properties: type: allOf: - $ref: '#/components/schemas/SurveyNextQuestionBranchingTypeEnum' description: 'Continue to the next question in sequence. * `next_question` - next_question' required: - type NullEnum: enum: - null FeatureFlagFilterPropertyExistsSchema: type: object properties: key: type: string description: Property key used in this feature flag condition. type: allOf: - $ref: '#/components/schemas/PropertyGroupTypeEnum' description: 'Property filter type. Common values are ''person'' and ''cohort''. * `cohort` - cohort * `person` - person * `group` - group' cohort_name: type: string nullable: true description: Resolved cohort name for cohort-type filters. group_type_index: type: integer nullable: true description: Group type index when using group-based filters. operator: allOf: - $ref: '#/components/schemas/ExistenceOperatorEnum' description: 'Existence operator. * `is_set` - is_set * `is_not_set` - is_not_set' value: description: Optional value. Runtime behavior determines whether this is ignored. required: - key - operator FeatureFlagConditionGroupSchema: type: object properties: properties: type: array items: $ref: '#/components/schemas/FeatureFlagFilterPropertySchema' description: Property conditions for this release condition group. rollout_percentage: type: number format: double description: Rollout percentage for this release condition group. variant: type: string nullable: true description: Variant key override for multivariate flags. aggregation_group_type_index: type: integer nullable: true description: Group type index for this condition set. None means person-level aggregation. SurveyEndBranching: type: object properties: type: allOf: - $ref: '#/components/schemas/SurveyEndBranchingTypeEnum' description: 'End the survey. * `end` - end' required: - type UserBasic: type: object properties: id: type: integer readOnly: true uuid: type: string format: uuid readOnly: true distinct_id: type: string nullable: true maxLength: 200 first_name: type: string maxLength: 150 last_name: type: string maxLength: 150 email: type: string format: email title: Email address maxLength: 254 is_email_verified: type: boolean nullable: true hedgehog_config: type: object additionalProperties: true nullable: true readOnly: true role_at_organization: nullable: true oneOf: - $ref: '#/components/schemas/RoleAtOrganizationEnum' - $ref: '#/components/schemas/BlankEnum' - $ref: '#/components/schemas/NullEnum' required: - email - hedgehog_config - id - uuid ResponseSamplingIntervalTypeEnum: enum: - day - week - month type: string description: '* `day` - day * `week` - week * `month` - month' GeneratedSurveyQuestionTranslationPatch: type: object properties: id: type: string description: Survey question id this patch applies to. translations: type: object additionalProperties: $ref: '#/components/schemas/GeneratedSurveyQuestionTranslation' description: Question translation patch keyed by target language. required: - id - translations SurveySingleChoiceQuestionSchemaTypeEnum: enum: - single_choice type: string description: '* `single_choice` - single_choice' SurveyLinkQuestionSchema: type: object properties: type: $ref: '#/components/schemas/SurveyLinkQuestionSchemaTypeEnum' question: type: string description: Question text shown to respondents. description: type: string description: Optional helper text. descriptionContentType: allOf: - $ref: '#/components/schemas/DescriptionContentTypeEnum' description: 'Format for the description field. * `text` - text * `html` - html' optional: type: boolean description: Whether respondents may skip this question. buttonText: type: string description: Custom button label. link: type: string description: HTTPS or mailto URL for link questions. required: - link - question - type DescriptionContentTypeEnum: enum: - html - text type: string description: '* `html` - html * `text` - text' PropertyGroupTypeEnum: enum: - cohort - person - group type: string description: '* `cohort` - cohort * `person` - person * `group` - group' ExistenceOperatorEnum: enum: - is_set - is_not_set type: string description: '* `is_set` - is_set * `is_not_set` - is_not_set' SurveyOpenQuestionSchemaTypeEnum: enum: - open type: string description: '* `open` - open' SurveyRatingQuestionSchema: type: object properties: type: $ref: '#/components/schemas/SurveyRatingQuestionSchemaTypeEnum' question: type: string description: Question text shown to respondents. description: type: string description: Optional helper text. descriptionContentType: allOf: - $ref: '#/components/schemas/DescriptionContentTypeEnum' description: 'Format for the description field. * `text` - text * `html` - html' optional: type: boolean description: Whether respondents may skip this question. buttonText: type: string description: Custom button label. display: allOf: - $ref: '#/components/schemas/SurveyRatingQuestionSchemaDisplayEnum' description: 'Display format: ''number'' shows numeric scale, ''emoji'' shows emoji scale. * `number` - number * `emoji` - emoji' scale: type: integer minimum: 1 description: Rating scale can be one of 3, 5, or 7 lowerBoundLabel: type: string description: Label for the lowest rating (e.g., 'Very Poor') upperBoundLabel: type: string description: Label for the highest rating (e.g., 'Excellent') branching: allOf: - $ref: '#/components/schemas/SurveyBranchingSchema' nullable: true required: - question - type SurveyMultipleChoiceQuestionSchemaTypeEnum: enum: - multiple_choice type: string description: '* `multiple_choice` - multiple_choice' FeatureFlagFilterPropertyMultiContainsSchema: type: object properties: key: type: string description: Property key used in this feature flag condition. type: allOf: - $ref: '#/components/schemas/PropertyGroupTypeEnum' description: 'Property filter type. Common values are ''person'' and ''cohort''. * `cohort` - cohort * `person` - person * `group` - group' cohort_name: type: string nullable: true description: Resolved cohort name for cohort-type filters. group_type_index: type: integer nullable: true description: Group type index when using group-based filters. operator: allOf: - $ref: '#/components/schemas/FeatureFlagFilterPropertyMultiContainsSchemaOperatorEnum' description: 'Multi-contains operator. * `icontains_multi` - icontains_multi * `not_icontains_multi` - not_icontains_multi' value: type: array items: type: string description: List of strings to evaluate against. required: - key - operator - value FeatureFlagFilterPropertyFlagEvaluatesSchema: type: object properties: key: type: string description: Property key used in this feature flag condition. type: allOf: - $ref: '#/components/schemas/FeatureFlagFilterPropertyFlagEvaluatesSchemaTypeEnum' description: 'Flag property type required for flag dependency checks. * `flag` - flag' cohort_name: type: string nullable: true description: Resolved cohort name for cohort-type filters. group_type_index: type: integer nullable: true description: Group type index when using group-based filters. operator: allOf: - $ref: '#/components/schemas/FeatureFlagFilterPropertyFlagEvaluatesSchemaOperatorEnum' description: 'Operator for feature flag dependency evaluation. * `flag_evaluates_to` - flag_evaluates_to' value: description: Value to compare flag evaluation against. required: - key - operator - type - value SurveySpecificQuestionBranching: type: object properties: type: allOf: - $ref: '#/components/schemas/SurveySpecificQuestionBranchingTypeEnum' description: 'Jump to a specific question index. * `specific_question` - specific_question' index: type: integer minimum: 0 description: 0-based index of the next question. required: - index - type EvaluationRuntimeEnum: enum: - server - client - all type: string description: '* `server` - Server * `client` - Client * `all` - All' SurveyEventsConditionSchema: type: object properties: repeatedActivation: type: boolean description: Whether to show the survey every time one of the events is triggered (true), or just once (false). values: type: array items: $ref: '#/components/schemas/SurveyConditionEventValueSchema' description: Array of event names that trigger the survey. SurveyConditionEventValueSchema: type: object properties: name: type: string description: Event name that triggers the survey. required: - name SurveyBranchingSchema: oneOf: - $ref: '#/components/schemas/SurveyNextQuestionBranching' - $ref: '#/components/schemas/SurveyEndBranching' - $ref: '#/components/schemas/SurveySpecificQuestionBranching' - $ref: '#/components/schemas/SurveyResponseBasedBranching' FeatureFlagFilterPropertyCohortInSchemaTypeEnum: enum: - cohort type: string description: '* `cohort` - cohort' SurveyGlobalStatsResponse: type: object properties: stats: type: object additionalProperties: true description: Event counts keyed by event name (survey shown, survey dismissed, survey sent). rates: type: object additionalProperties: true description: Calculated response and dismissal rates. required: - rates - stats Survey: type: object description: Mixin for serializers to add user access control fields properties: id: type: string format: uuid readOnly: true name: type: string maxLength: 400 description: type: string type: $ref: '#/components/schemas/SurveyType' schedule: type: string nullable: true linked_flag: allOf: - $ref: '#/components/schemas/MinimalFeatureFlag' readOnly: true linked_flag_id: type: integer nullable: true linked_insight_id: type: integer nullable: true targeting_flag: allOf: - $ref: '#/components/schemas/MinimalFeatureFlag' readOnly: true internal_targeting_flag: allOf: - $ref: '#/components/schemas/MinimalFeatureFlag' readOnly: true questions: nullable: true description: "\n The `array` of questions included in the survey. Each question must conform to one of the defined question types: Basic, Link, Rating, or Multiple Choice.\n\n Basic (open-ended question)\n - `id`: The question ID\n - `type`: `open`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Link (a question with a link)\n - `id`: The question ID\n - `type`: `link`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `link`: The URL associated with the question.\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Rating (a question with a rating scale)\n - `id`: The question ID\n - `type`: `rating`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `display`: Display style of the rating (`number` or `emoji`).\n - `scale`: The scale of the rating (`number`).\n - `lowerBoundLabel`: Label for the lower bound of the scale.\n - `upperBoundLabel`: Label for the upper bound of the scale.\n - `isNpsQuestion`: Whether the question is an NPS rating.\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Multiple choice\n - `id`: The question ID\n - `type`: `single_choice` or `multiple_choice`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `choices`: An array of choices for the question.\n - `shuffleOptions`: Whether to shuffle the order of the choices (`boolean`).\n - `hasOpenChoice`: Whether the question allows an open-ended response (`boolean`).\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Branching logic can be one of the following types:\n\n Next question: Proceeds to the next question\n ```json\n {\n \"type\": \"next_question\"\n }\n ```\n\n End: Ends the survey, optionally displaying a confirmation message.\n ```json\n {\n \"type\": \"end\"\n }\n ```\n\n Response-based: Branches based on the response values. Available for the `rating` and `single_choice` question types.\n ```json\n {\n \"type\": \"response_based\",\n \"responseValues\": {\n \"responseKey\": \"value\"\n }\n }\n ```\n\n Specific question: Proceeds to a specific question by index.\n ```json\n {\n \"type\": \"specific_question\",\n \"index\": 2\n }\n ```\n\n Translations: Each question can include inline translations.\n - `translations`: Object mapping language codes to translated fields.\n - Language codes: Any string - allows customers to use their own language keys (e.g., \"es\", \"es-MX\", \"english\", \"french\")\n - Translatable fields: `question`, `description`, `buttonText`, `choices`, `lowerBoundLabel`, `upperBoundLabel`, `link`\n\n Example with translations:\n ```json\n {\n \"id\": \"uuid\",\n \"type\": \"rating\",\n \"question\": \"How satisfied are you?\",\n \"lowerBoundLabel\": \"Not satisfied\",\n \"upperBoundLabel\": \"Very satisfied\",\n \"translations\": {\n \"es\": {\n \"question\": \"¿Qué tan satisfecho estás?\",\n \"lowerBoundLabel\": \"No satisfecho\",\n \"upperBoundLabel\": \"Muy satisfecho\"\n },\n \"fr\": {\n \"question\": \"Dans quelle mesure êtes-vous satisfait?\"\n }\n }\n }\n ```\n " conditions: type: object additionalProperties: true nullable: true readOnly: true appearance: nullable: true created_at: type: string format: date-time readOnly: true created_by: allOf: - $ref: '#/components/schemas/UserBasic' readOnly: true start_date: type: string format: date-time nullable: true end_date: type: string format: date-time nullable: true archived: type: boolean responses_limit: type: integer maximum: 2147483647 minimum: 0 nullable: true feature_flag_keys: type: array items: type: object additionalProperties: type: string nullable: true readOnly: true iteration_count: type: integer maximum: 500 minimum: 0 nullable: true iteration_frequency_days: type: integer maximum: 2147483647 minimum: 0 nullable: true iteration_start_dates: type: array items: type: string format: date-time nullable: true nullable: true current_iteration: type: integer maximum: 2147483647 minimum: 0 nullable: true current_iteration_start_date: type: string format: date-time nullable: true response_sampling_start_date: type: string format: date-time nullable: true response_sampling_interval_type: nullable: true oneOf: - $ref: '#/components/schemas/ResponseSamplingIntervalTypeEnum' - $ref: '#/components/schemas/BlankEnum' - $ref: '#/components/schemas/NullEnum' response_sampling_interval: type: integer maximum: 2147483647 minimum: 0 nullable: true response_sampling_limit: type: integer maximum: 2147483647 minimum: 0 nullable: true response_sampling_daily_limits: nullable: true enable_partial_responses: type: boolean nullable: true enable_iframe_embedding: type: boolean nullable: true translations: nullable: true user_access_level: type: string nullable: true readOnly: true description: The effective access level the user has for this object form_content: nullable: true required: - conditions - created_at - created_by - feature_flag_keys - id - internal_targeting_flag - linked_flag - name - targeting_flag - type - user_access_level MinimalFeatureFlag: type: object properties: id: type: integer readOnly: true team_id: type: integer readOnly: true name: type: string key: type: string maxLength: 400 filters: type: object additionalProperties: true deleted: type: boolean active: type: boolean ensure_experience_continuity: type: boolean nullable: true has_encrypted_payloads: type: boolean nullable: true version: type: integer maximum: 2147483647 minimum: -2147483648 nullable: true evaluation_runtime: nullable: true description: 'Specifies where this feature flag should be evaluated * `server` - Server * `client` - Client * `all` - All' oneOf: - $ref: '#/components/schemas/EvaluationRuntimeEnum' - $ref: '#/components/schemas/BlankEnum' - $ref: '#/components/schemas/NullEnum' bucketing_identifier: nullable: true description: 'Identifier used for bucketing users into rollout and variants * `distinct_id` - User ID (default) * `device_id` - Device ID' oneOf: - $ref: '#/components/schemas/BucketingIdentifierEnum' - $ref: '#/components/schemas/BlankEnum' - $ref: '#/components/schemas/NullEnum' evaluation_contexts: type: array items: type: string readOnly: true required: - evaluation_contexts - id - key - team_id FeatureFlagFilterPropertySchema: oneOf: - $ref: '#/components/schemas/FeatureFlagFilterPropertyGenericSchema' - $ref: '#/components/schemas/FeatureFlagFilterPropertyExistsSchema' - $ref: '#/components/schemas/FeatureFlagFilterPropertyDateSchema' - $ref: '#/components/schemas/FeatureFlagFilterPropertySemverSchema' - $ref: '#/components/schemas/FeatureFlagFilterPropertyMultiContainsSchema' - $ref: '#/components/schemas/FeatureFlagFilterPropertyCohortInSchema' - $ref: '#/components/schemas/FeatureFlagFilterPropertyFlagEvaluatesSchema' SurveyQuestionInputSchema: oneOf: - $ref: '#/components/schemas/SurveyOpenQuestionSchema' - $ref: '#/components/schemas/SurveyLinkQuestionSchema' - $ref: '#/components/schemas/SurveyRatingQuestionSchema' - $ref: '#/components/schemas/SurveySingleChoiceQuestionSchema' - $ref: '#/components/schemas/SurveyMultipleChoiceQuestionSchema' FeatureFlagFilterPropertySemverSchemaOperatorEnum: enum: - semver_gt - semver_gte - semver_lt - semver_lte - semver_eq - semver_neq - semver_tilde - semver_caret - semver_wildcard type: string description: '* `semver_gt` - semver_gt * `semver_gte` - semver_gte * `semver_lt` - semver_lt * `semver_lte` - semver_lte * `semver_eq` - semver_eq * `semver_neq` - semver_neq * `semver_tilde` - semver_tilde * `semver_caret` - semver_caret * `semver_wildcard` - semver_wildcard' SurveyType: enum: - popover - widget - external_survey - api type: string description: '* `popover` - popover * `widget` - widget * `external_survey` - external survey * `api` - api' FeatureFlagFiltersSchema: type: object properties: groups: type: array items: $ref: '#/components/schemas/FeatureFlagConditionGroupSchema' description: Release condition groups for the feature flag. multivariate: allOf: - $ref: '#/components/schemas/FeatureFlagMultivariateSchema' nullable: true description: Multivariate configuration for variant-based rollouts. aggregation_group_type_index: type: integer nullable: true description: Group type index for group-based feature flags. payloads: type: object additionalProperties: type: string description: Optional payload values keyed by variant key. super_groups: type: array items: type: object additionalProperties: true description: Additional super condition groups used by experiments. feature_enrollment: type: boolean nullable: true description: Whether this flag has early access feature enrollment enabled. When true, the flag is evaluated against the person property $feature_enrollment/{flag_key}. FeatureFlagFilterPropertyFlagEvaluatesSchemaTypeEnum: enum: - flag type: string description: '* `flag` - flag' FeatureFlagFilterPropertyGenericSchema: type: object properties: key: type: string description: Property key used in this feature flag condition. type: allOf: - $ref: '#/components/schemas/PropertyGroupTypeEnum' description: 'Property filter type. Common values are ''person'' and ''cohort''. * `cohort` - cohort * `person` - person * `group` - group' cohort_name: type: string nullable: true description: Resolved cohort name for cohort-type filters. group_type_index: type: integer nullable: true description: Group type index when using group-based filters. value: description: Comparison value for the property filter. Supports strings, numbers, booleans, and arrays. operator: allOf: - $ref: '#/components/schemas/FeatureFlagFilterPropertyGenericSchemaOperatorEnum' description: 'Operator used to compare the property value. * `exact` - exact * `is_not` - is_not * `icontains` - icontains * `not_icontains` - not_icontains * `regex` - regex * `not_regex` - not_regex * `gt` - gt * `gte` - gte * `lt` - lt * `lte` - lte' required: - key - operator - value FeatureFlagMultivariateSchema: type: object properties: variants: type: array items: $ref: '#/components/schemas/FeatureFlagMultivariateVariantSchema' description: Variant definitions for multivariate feature flags. required: - variants SurveySerializerCreateUpdateOnly: type: object properties: id: type: string format: uuid readOnly: true name: type: string maxLength: 400 description: type: string type: $ref: '#/components/schemas/SurveyType' schedule: type: string nullable: true linked_flag: allOf: - $ref: '#/components/schemas/MinimalFeatureFlag' readOnly: true linked_flag_id: type: integer writeOnly: true nullable: true linked_insight_id: type: integer writeOnly: true nullable: true targeting_flag_id: type: integer writeOnly: true targeting_flag: allOf: - $ref: '#/components/schemas/MinimalFeatureFlag' readOnly: true internal_targeting_flag: allOf: - $ref: '#/components/schemas/MinimalFeatureFlag' readOnly: true targeting_flag_filters: writeOnly: true nullable: true remove_targeting_flag: type: boolean writeOnly: true nullable: true questions: nullable: true description: "\n The `array` of questions included in the survey. Each question must conform to one of the defined question types: Basic, Link, Rating, or Multiple Choice.\n\n Basic (open-ended question)\n - `id`: The question ID\n - `type`: `open`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Link (a question with a link)\n - `id`: The question ID\n - `type`: `link`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `link`: The URL associated with the question.\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Rating (a question with a rating scale)\n - `id`: The question ID\n - `type`: `rating`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `display`: Display style of the rating (`number` or `emoji`).\n - `scale`: The scale of the rating (`number`).\n - `lowerBoundLabel`: Label for the lower bound of the scale.\n - `upperBoundLabel`: Label for the upper bound of the scale.\n - `isNpsQuestion`: Whether the question is an NPS rating.\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Multiple choice\n - `id`: The question ID\n - `type`: `single_choice` or `multiple_choice`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `choices`: An array of choices for the question.\n - `shuffleOptions`: Whether to shuffle the order of the choices (`boolean`).\n - `hasOpenChoice`: Whether the question allows an open-ended response (`boolean`).\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Branching logic can be one of the following types:\n\n Next question: Proceeds to the next question\n ```json\n {\n \"type\": \"next_question\"\n }\n ```\n\n End: Ends the survey, optionally displaying a confirmation message.\n ```json\n {\n \"type\": \"end\"\n }\n ```\n\n Response-based: Branches based on the response values. Available for the `rating` and `single_choice` question types.\n ```json\n {\n \"type\": \"response_based\",\n \"responseValues\": {\n \"responseKey\": \"value\"\n }\n }\n ```\n\n Specific question: Proceeds to a specific question by index.\n ```json\n {\n \"type\": \"specific_question\",\n \"index\": 2\n }\n ```\n\n Translations: Each question can include inline translations.\n - `translations`: Object mapping language codes to translated fields.\n - Language codes: Any string - allows customers to use their own language keys (e.g., \"es\", \"es-MX\", \"english\", \"french\")\n - Translatable fields: `question`, `description`, `buttonText`, `choices`, `lowerBoundLabel`, `upperBoundLabel`, `link`\n\n Example with translations:\n ```json\n {\n \"id\": \"uuid\",\n \"type\": \"rating\",\n \"question\": \"How satisfied are you?\",\n \"lowerBoundLabel\": \"Not satisfied\",\n \"upperBoundLabel\": \"Very satisfied\",\n \"translations\": {\n \"es\": {\n \"question\": \"¿Qué tan satisfecho estás?\",\n \"lowerBoundLabel\": \"No satisfecho\",\n \"upperBoundLabel\": \"Muy satisfecho\"\n },\n \"fr\": {\n \"question\": \"Dans quelle mesure êtes-vous satisfait?\"\n }\n }\n }\n ```\n " conditions: nullable: true appearance: nullable: true created_at: type: string format: date-time readOnly: true created_by: allOf: - $ref: '#/components/schemas/UserBasic' readOnly: true start_date: type: string format: date-time nullable: true end_date: type: string format: date-time nullable: true archived: type: boolean responses_limit: type: integer maximum: 2147483647 minimum: 0 nullable: true iteration_count: type: integer maximum: 500 minimum: 0 nullable: true iteration_frequency_days: type: integer maximum: 2147483647 minimum: 0 nullable: true iteration_start_dates: type: array items: type: string format: date-time nullable: true nullable: true current_iteration: type: integer maximum: 2147483647 minimum: 0 nullable: true current_iteration_start_date: type: string format: date-time nullable: true response_sampling_start_date: type: string format: date-time nullable: true response_sampling_interval_type: nullable: true oneOf: - $ref: '#/components/schemas/ResponseSamplingIntervalTypeEnum' - $ref: '#/components/schemas/BlankEnum' - $ref: '#/components/schemas/NullEnum' response_sampling_interval: type: integer maximum: 2147483647 minimum: 0 nullable: true response_sampling_limit: type: integer maximum: 2147483647 minimum: 0 nullable: true response_sampling_daily_limits: nullable: true enable_partial_responses: type: boolean nullable: true enable_iframe_embedding: type: boolean nullable: true translations: nullable: true _create_in_folder: type: string writeOnly: true title: ' create in folder' form_content: nullable: true required: - created_at - created_by - id - internal_targeting_flag - linked_flag - name - targeting_flag - type FeatureFlagFilterPropertyFlagEvaluatesSchemaOperatorEnum: enum: - flag_evaluates_to type: string description: '* `flag_evaluates_to` - flag_evaluates_to' PaginatedSurveyList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?offset=400&limit=100 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?offset=200&limit=100 results: type: array items: $ref: '#/components/schemas/Survey' SurveyLinkQuestionSchemaTypeEnum: enum: - link type: string description: '* `link` - link' SurveyOpenQuestionSchema: type: object properties: type: $ref: '#/components/schemas/SurveyOpenQuestionSchemaTypeEnum' question: type: string description: Question text shown to respondents. description: type: string description: Optional helper text. descriptionContentType: allOf: - $ref: '#/components/schemas/DescriptionContentTypeEnum' description: 'Format for the description field. * `text` - text * `html` - html' optional: type: boolean description: Whether respondents may skip this question. buttonText: type: string description: Custom button label. required: - question - type GeneratedSurveyQuestionTranslation: type: object properties: question: type: string description: Translated question text. description: type: string description: Translated question description. buttonText: type: string description: Translated submit button text. choices: type: array items: type: string description: Translated choices in the same order as the source choices. lowerBoundLabel: type: string description: Translated lower rating bound label. upperBoundLabel: type: string description: Translated upper rating bound label. link: type: string description: Translated link text or localized URL. SurveyRatingQuestionSchemaDisplayEnum: enum: - number - emoji type: string description: '* `number` - number * `emoji` - emoji' BlankEnum: enum: - '' FeatureFlagFilterPropertyCohortInSchema: type: object properties: key: type: string description: Property key used in this feature flag condition. type: allOf: - $ref: '#/components/schemas/FeatureFlagFilterPropertyCohortInSchemaTypeEnum' description: 'Cohort property type required for in/not_in operators. * `cohort` - cohort' cohort_name: type: string nullable: true description: Resolved cohort name for cohort-type filters. group_type_index: type: integer nullable: true description: Group type index when using group-based filters. operator: allOf: - $ref: '#/components/schemas/FeatureFlagFilterPropertyCohortInSchemaOperatorEnum' description: 'Membership operator for cohort properties. * `in` - in * `not_in` - not_in' value: description: Cohort comparison value (single or list, depending on usage). required: - key - operator - type - value SurveyMultipleChoiceQuestionSchema: type: object properties: type: $ref: '#/components/schemas/SurveyMultipleChoiceQuestionSchemaTypeEnum' question: type: string description: Question text shown to respondents. description: type: string description: Optional helper text. descriptionContentType: allOf: - $ref: '#/components/schemas/DescriptionContentTypeEnum' description: 'Format for the description field. * `text` - text * `html` - html' optional: type: boolean description: Whether respondents may skip this question. buttonText: type: string description: Custom button label. choices: type: array items: type: string description: Array of choice options. Multiple selections allowed. No branching logic supported. maxItems: 20 minItems: 2 shuffleOptions: type: boolean description: Whether to randomize the order of choices for each respondent. hasOpenChoice: type: boolean description: Whether the final option should be an open-text choice (for example, 'Other'). required: - choices - question - type FeatureFlagFilterPropertyGenericSchemaOperatorEnum: enum: - exact - is_not - icontains - not_icontains - regex - not_regex - gt - gte - lt - lte type: string description: '* `exact` - exact * `is_not` - is_not * `icontains` - icontains * `not_icontains` - not_icontains * `regex` - regex * `not_regex` - not_regex * `gt` - gt * `gte` - gte * `lt` - lt * `lte` - lte' FeatureFlagFilterPropertyDateSchema: type: object properties: key: type: string description: Property key used in this feature flag condition. type: allOf: - $ref: '#/components/schemas/PropertyGroupTypeEnum' description: 'Property filter type. Common values are ''person'' and ''cohort''. * `cohort` - cohort * `person` - person * `group` - group' cohort_name: type: string nullable: true description: Resolved cohort name for cohort-type filters. group_type_index: type: integer nullable: true description: Group type index when using group-based filters. operator: allOf: - $ref: '#/components/schemas/DateOperatorEnum' description: 'Date comparison operator. * `is_date_exact` - is_date_exact * `is_date_after` - is_date_after * `is_date_before` - is_date_before' value: type: string description: Date value in ISO format or relative date expression. required: - key - operator - value SurveyRatingQuestionSchemaTypeEnum: enum: - rating type: string description: '* `rating` - rating' GeneratedSurveyRootTranslation: type: object properties: name: type: string description: Translated survey name. thankYouMessageHeader: type: string description: Translated thank-you header. thankYouMessageDescription: type: string description: Translated thank-you description. thankYouMessageCloseButtonText: type: string description: Translated thank-you close button text. BucketingIdentifierEnum: enum: - distinct_id - device_id type: string description: '* `distinct_id` - User ID (default) * `device_id` - Device ID' GenerateSurveyTranslationsRequest: type: object properties: target_language: type: string description: Language code to generate translations for, for example pt-BR. source_language: type: string default: en description: Source language code for the existing survey copy. overwrite: type: boolean default: false description: Whether to overwrite existing translations for this language. survey: type: object additionalProperties: nullable: true description: Draft survey field value. description: Optional translation-only draft survey payload to translate instead of the last saved survey. required: - target_language FeatureFlagMultivariateVariantSchema: type: object properties: key: type: string description: Unique key for this variant. name: type: string description: Human-readable name for this variant. rollout_percentage: type: number format: double description: Variant rollout percentage. required: - key - rollout_percentage ScheduleEnum: enum: - once - recurring - always type: string description: '* `once` - once * `recurring` - recurring * `always` - always' SurveyConditionsSchema: type: object properties: url: type: string selector: type: string seenSurveyWaitPeriodInDays: type: integer minimum: 0 description: Don't show this survey to users who saw any survey in the last x days. urlMatchType: allOf: - $ref: '#/components/schemas/StringMatchOperatorEnum' description: 'URL/device matching types: ''regex'' (matches regex pattern), ''not_regex'' (does not match regex pattern), ''exact'' (exact string match), ''is_not'' (not exact match), ''icontains'' (case-insensitive contains), ''not_icontains'' (case-insensitive does not contain). * `regex` - regex * `not_regex` - not_regex * `exact` - exact * `is_not` - is_not * `icontains` - icontains * `not_icontains` - not_icontains' events: $ref: '#/components/schemas/SurveyEventsConditionSchema' deviceTypes: type: array items: $ref: '#/components/schemas/DeviceTypesEnum' description: Device types that should match for this survey to be shown. deviceTypesMatchType: allOf: - $ref: '#/components/schemas/StringMatchOperatorEnum' description: 'URL/device matching types: ''regex'' (matches regex pattern), ''not_regex'' (does not match regex pattern), ''exact'' (exact string match), ''is_not'' (not exact match), ''icontains'' (case-insensitive contains), ''not_icontains'' (case-insensitive does not contain). * `regex` - regex * `not_regex` - not_regex * `exact` - exact * `is_not` - is_not * `icontains` - icontains * `not_icontains` - not_icontains' linkedFlagVariant: type: string description: The variant of the feature flag linked to this survey. PatchedSurveySerializerCreateUpdateOnlySchema: type: object properties: id: type: string format: uuid readOnly: true name: type: string description: Survey name. maxLength: 400 minLength: 1 description: type: string description: Survey description. type: allOf: - $ref: '#/components/schemas/SurveyType' description: 'Survey type. * `popover` - popover * `widget` - widget * `external_survey` - external survey * `api` - api' schedule: nullable: true description: 'Survey scheduling behavior: ''once'' = show once per user (default), ''recurring'' = repeat based on iteration_count and iteration_frequency_days settings, ''always'' = show every time conditions are met (mainly for widget surveys) * `once` - once * `recurring` - recurring * `always` - always' oneOf: - $ref: '#/components/schemas/ScheduleEnum' - $ref: '#/components/schemas/NullEnum' linked_flag: allOf: - $ref: '#/components/schemas/MinimalFeatureFlag' readOnly: true linked_flag_id: type: integer writeOnly: true nullable: true description: The feature flag linked to this survey. linked_insight_id: type: integer writeOnly: true nullable: true targeting_flag_id: type: integer writeOnly: true description: An existing targeting flag to use for this survey. targeting_flag: allOf: - $ref: '#/components/schemas/MinimalFeatureFlag' readOnly: true internal_targeting_flag: allOf: - $ref: '#/components/schemas/MinimalFeatureFlag' readOnly: true targeting_flag_filters: allOf: - $ref: '#/components/schemas/FeatureFlagFiltersSchema' writeOnly: true nullable: true description: 'Target specific users based on their properties. Example: {groups: [{properties: [{key: ''email'', value: [''@company.com''], operator: ''icontains''}], rollout_percentage: 100}]}' remove_targeting_flag: type: boolean writeOnly: true nullable: true description: Set to true to completely remove all targeting filters from the survey, making it visible to all users (subject to other display conditions like URL matching). questions: type: array items: $ref: '#/components/schemas/SurveyQuestionInputSchema' nullable: true description: "\n The `array` of questions included in the survey. Each question must conform to one of the defined question types: Basic, Link, Rating, or Multiple Choice.\n\n Basic (open-ended question)\n - `id`: The question ID\n - `type`: `open`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Link (a question with a link)\n - `id`: The question ID\n - `type`: `link`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `link`: The URL associated with the question.\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Rating (a question with a rating scale)\n - `id`: The question ID\n - `type`: `rating`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `display`: Display style of the rating (`number` or `emoji`).\n - `scale`: The scale of the rating (`number`).\n - `lowerBoundLabel`: Label for the lower bound of the scale.\n - `upperBoundLabel`: Label for the upper bound of the scale.\n - `isNpsQuestion`: Whether the question is an NPS rating.\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Multiple choice\n - `id`: The question ID\n - `type`: `single_choice` or `multiple_choice`\n - `question`: The text of the question.\n - `description`: Optional description of the question.\n - `descriptionContentType`: Content type of the description (`html` or `text`).\n - `optional`: Whether the question is optional (`boolean`).\n - `buttonText`: Text displayed on the submit button.\n - `choices`: An array of choices for the question.\n - `shuffleOptions`: Whether to shuffle the order of the choices (`boolean`).\n - `hasOpenChoice`: Whether the question allows an open-ended response (`boolean`).\n - `branching`: Branching logic for the question. See branching types below for details.\n\n Branching logic can be one of the following types:\n\n Next question: Proceeds to the next question\n ```json\n {\n \"type\": \"next_question\"\n }\n ```\n\n End: Ends the survey, optionally displaying a confirmation message.\n ```json\n {\n \"type\": \"end\"\n }\n ```\n\n Response-based: Branches based on the response values. Available for the `rating` and `single_choice` question types.\n ```json\n {\n \"type\": \"response_based\",\n \"responseValues\": {\n \"responseKey\": \"value\"\n }\n }\n ```\n\n Specific question: Proceeds to a specific question by index.\n ```json\n {\n \"type\": \"specific_question\",\n \"index\": 2\n }\n ```\n\n Translations: Each question can include inline translations.\n - `translations`: Object mapping language codes to translated fields.\n - Language codes: Any string - allows customers to use their own language keys (e.g., \"es\", \"es-MX\", \"english\", \"french\")\n - Translatable fields: `question`, `description`, `buttonText`, `choices`, `lowerBoundLabel`, `upperBoundLabel`, `link`\n\n Example with translations:\n ```json\n {\n \"id\": \"uuid\",\n \"type\": \"rating\",\n \"question\": \"How satisfied are you?\",\n \"lowerBoundLabel\": \"Not satisfied\",\n \"upperBoundLabel\": \"Very satisfied\",\n \"translations\": {\n \"es\": {\n \"question\": \"¿Qué tan satisfecho estás?\",\n \"lowerBoundLabel\": \"No satisfecho\",\n \"upperBoundLabel\": \"Muy satisfecho\"\n },\n \"fr\": {\n \"question\": \"Dans quelle mesure êtes-vous satisfait?\"\n }\n }\n }\n ```\n " conditions: allOf: - $ref: '#/components/schemas/SurveyConditionsSchema' nullable: true description: Display and targeting conditions for the survey. appearance: allOf: - $ref: '#/components/schemas/SurveyAppearanceSchema' nullable: true description: Survey appearance customization. created_at: type: string format: date-time readOnly: true created_by: allOf: - $ref: '#/components/schemas/UserBasic' readOnly: true start_date: type: string format: date-time nullable: true description: Setting this will launch the survey immediately. Don't add a start_date unless explicitly requested to do so. end_date: type: string format: date-time nullable: true description: When the survey stopped being shown to users. Setting this will complete the survey. archived: type: boolean description: Archive state for the survey. responses_limit: type: integer nullable: true description: The maximum number of responses before automatically stopping the survey. iteration_count: type: integer maximum: 500 minimum: 1 nullable: true description: For a recurring schedule, this field specifies the number of times the survey should be shown to the user. Use 1 for 'once every X days', higher numbers for multiple repetitions. Works together with iteration_frequency_days to determine the overall survey schedule. iteration_frequency_days: type: integer maximum: 365 minimum: 1 nullable: true description: For a recurring schedule, this field specifies the interval in days between each survey instance shown to the user, used alongside iteration_count for precise scheduling. iteration_start_dates: type: array items: type: string format: date-time nullable: true nullable: true current_iteration: type: integer maximum: 2147483647 minimum: 0 nullable: true current_iteration_start_date: type: string format: date-time nullable: true response_sampling_start_date: type: string format: date-time nullable: true response_sampling_interval_type: nullable: true oneOf: - $ref: '#/components/schemas/ResponseSamplingIntervalTypeEnum' - $ref: '#/components/schemas/BlankEnum' - $ref: '#/components/schemas/NullEnum' response_sampling_interval: type: integer maximum: 2147483647 minimum: 0 nullable: true response_sampling_limit: type: integer maximum: 2147483647 minimum: 0 nullable: true response_sampling_daily_limits: nullable: true enable_partial_responses: type: boolean nullable: true description: When at least one question is answered, the response is stored (true). The response is stored when all questions are answered (false). enable_iframe_embedding: type: boolean nullable: true translations: nullable: true _create_in_folder: type: string writeOnly: true title: ' create in folder' form_content: nullable: true DeviceTypesEnum: enum: - Desktop - Mobile - Tablet type: string description: '* `Desktop` - Desktop * `Mobile` - Mobile * `Tablet` - Tablet' StringMatchOperatorEnum: enum: - exact - is_not - icontains - not_icontains - regex - not_regex type: string description: '* `exact` - exact * `is_not` - is_not * `icontains` - icontains * `not_icontains` - not_icontains * `regex` - regex * `not_regex` - not_regex' GenerateSurveyTranslationsResponse: type: object properties: translations: type: object additionalProperties: $ref: '#/components/schemas/GeneratedSurveyRootTranslation' description: Survey-level translation patch keyed by language. questions: type: array items: $ref: '#/components/schemas/GeneratedSurveyQuestionTranslationPatch' description: Question-level translation patches keyed by question id and language. generated_field_paths: type: array items: type: string description: Editor field paths generated by AI and safe to highlight as draft content. trace_id: type: string description: LLM trace id for debugging and feedback. required: - generated_field_paths - questions - trace_id - translations SurveyEndBranchingTypeEnum: enum: - end type: string description: '* `end` - end' WidgetTypeEnum: enum: - button - tab - selector type: string description: '* `button` - button * `tab` - tab * `selector` - selector' SurveyNextQuestionBranchingTypeEnum: enum: - next_question type: string description: '* `next_question` - next_question' DateOperatorEnum: enum: - is_date_exact - is_date_before - is_date_after type: string description: '* `is_date_exact` - is_date_exact * `is_date_before` - is_date_before * `is_date_after` - is_date_after' parameters: ProjectIdPath: in: path name: project_id required: true schema: type: string description: Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/. securitySchemes: PersonalAPIKeyAuth: type: http scheme: bearer x-tagGroups: - name: All endpoints tags: - LLM Analytics - actions - activity_log - activity_logs - advanced_activity_logs - alerts - annotations - approval_policies - batch_exports - cdp - change_requests - code - code-invites - cohorts - comments - conversations - core - customer_analytics - customer_journeys - customer_profile_configs - dashboard_templates - dashboards - data_color_themes - data_modeling_jobs - data_warehouse - dataset_items - datasets - desktop_recordings - domains - early_access_feature - early_access_features - elements - endpoints - environments - error_tracking - evaluation_runs - evaluations - event_definitions - event_filter - event_schemas - events - experiment_holdouts - experiment_saved_metrics - experiments - exports - external_data_schemas - external_data_sources - feature_flags - file_system - file_system_shortcut - flag_value - groups - groups_types - health_issues - heatmap_screenshots - heatmaps - hog_flows - hog_function_templates - hog_functions - insight_variables - insights - integrations - invites - js-snippet - legal_documents - lineage - live_debugger_breakpoints - llm_analytics - llm_prompts - llm_skills - logs - managed_viewsets - max - max_tools - mcp_server_installations - mcp_servers - mcp_store - mcp_tools - members - notebooks - oauth_applications - object_media_previews - organizations - persisted_folder - persons - platform_features - plugin_configs - product_analytics - product_tours - project_secret_api_keys - projects - property_definitions - proxy_records - public_hog_function_templates - query - replay - reverse_proxy - role_external_references - roles - sandbox-environments - sandbox_environments - saved - schema_property_groups - sdk_doctor - session_group_summaries - session_recording_playlists - session_recordings - session_summaries - sessions - signals - subscriptions - surveys - taggers - task-automations - task-runs - task_automations - tasks - uploaded_media - user_home_settings - user_interviews - users - visual_review - warehouse_dag - warehouse_model_paths - warehouse_saved_queries - warehouse_saved_query_folders - warehouse_tables - warehouse_view_link - warehouse_view_links - web_analytics - web_experiments - web_vitals - welcome - workflows