# V3 API — Surveys (hand-maintained; not generated by generate-api-specs).
# Implementation: apps/web/app/api/v3/surveys/route.ts and apps/web/app/api/v3/surveys/[surveyId]/route.ts

openapi: 3.1.0
info:
  title: Formbricks API v3
  description: |
    **GET /api/v3/surveys**, **POST /api/v3/surveys**, **POST /api/v3/surveys/validate**, **GET /api/v3/surveys/{surveyId}**, and **DELETE /api/v3/surveys/{surveyId}** — authenticate with **session cookie** or **`x-api-key`** (management key with access to the workspace).

    **Spec location:** `docs/api-v3-reference/openapi.yml` (alongside v2 at `docs/api-v2-reference/openapi.yml`).

    **workspaceId**
    Query param `workspaceId` is the canonical container identifier for this API.

    **Auth**
    Authenticate with either a session cookie or **`x-api-key`**. In dual-auth mode, V3 checks the API key first when the header is present, otherwise it uses the session path. Unauthenticated callers get **401** before query validation.

    **Pagination**
    Cursor-based pagination with **limit** + opaque **cursor** token. Responses return `meta.nextCursor`; pass that value back as `cursor` to fetch the next page. Responses also include `meta.totalCount`, the total number of surveys matching the current filters across all pages. There is no `offset` in this contract.

    **Filtering**
    Filters use explicit operator-style query parameters under the **`filter[...]` family**. This endpoint supports `filter[name][contains]`, `filter[status][in]`, and `filter[type][in]`. Multi-value filters use repeated keys or comma-separated values (e.g. `filter[status][in]=draft&filter[status][in]=inProgress` or `filter[status][in]=draft,inProgress`). Sorting remains a flat `sortBy` query parameter.

    **Security**
    Missing/forbidden workspace returns **403** with a generic message (not **404**) so resource existence is not leaked. List responses use `private, no-store`.

    **OpenAPI**
    This YAML is **not** produced by `pnpm generate-api-specs` (that script only builds v2 → `docs/api-v2-reference/openapi.yml`). Update this file when the route contract changes.

    **Overview migration note**
    The v3-backed survey overview page intentionally removes actions that are not yet exposed by this contract: `Created by` filtering, `Duplicate`, `Copy...`, `Preview`, and `Copy link`.

    **Next steps (out of scope for this spec)**
    Additional v3 survey update endpoints, optional ETag/304, field selection, translation-specific writes, and survey version history.
  version: 0.1.0
  x-implementation-notes:
    route: apps/web/app/api/v3/surveys/route.ts
    query-parser: apps/web/app/api/v3/surveys/parse-v3-surveys-list-query.ts
    auth: apps/web/app/api/v3/lib/auth.ts
    workspace-resolution: apps/web/app/api/v3/lib/workspace-context.ts
    openapi-generated: false
    pagination-model: cursor
    cursor-pagination: supported
paths:
  /api/v3/surveys:
    get:
      operationId: getSurveysV3
      summary: List surveys
      description: |
        Returns surveys for the workspace. Session cookie or x-api-key.
      tags:
        - V3 Surveys
      parameters:
        - in: query
          name: workspaceId
          required: true
          schema:
            type: string
            format: cuid2
          description: |
            Workspace identifier. This is the canonical container ID for v3 APIs.
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Page size (max 100)
        - in: query
          name: cursor
          schema:
            type: string
          description: |
            Opaque cursor returned as `meta.nextCursor` from the previous page. Omit on the first request.
        - in: query
          name: includeTotalCount
          schema:
            type: boolean
            default: true
          description: |
            Whether to calculate `meta.totalCount` for this request. Set to `false` on cursor-pagination follow-up requests to skip the extra count query; in that case `meta.totalCount` is `null`.
        - in: query
          name: filter[name][contains]
          schema:
            type: string
            maxLength: 512
          description: Case-insensitive substring match on survey name (same as in-app list filters).
        - in: query
          name: filter[status][in]
          schema:
            type: array
            items:
              type: string
              enum: [draft, inProgress, paused, completed]
          style: form
          explode: true
          description: |
            Survey status filter. Repeat the parameter (`filter[status][in]=draft&filter[status][in]=inProgress`) or use comma-separated values (`filter[status][in]=draft,inProgress`). Invalid values → **400**.
        - in: query
          name: filter[type][in]
          schema:
            type: array
            items:
              type: string
              enum: [link, app]
          style: form
          explode: true
          description: Survey type filter (`link` / `app`). Same repeat-or-comma rules as `filter[status][in]`.
        - in: query
          name: sortBy
          schema:
            type: string
            enum: [createdAt, updatedAt, name, relevance]
          description: Sort order. Defaults to `updatedAt`. The `cursor` token is bound to the selected sort order.
      responses:
        "200":
          description: Surveys retrieved successfully
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Request correlation ID
            Cache-Control:
              schema:
                type: string
              example: "private, no-store"
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SurveyListItem"
                  meta:
                    type: object
                    required: [limit, nextCursor, totalCount]
                    properties:
                      limit:
                        type: integer
                      nextCursor:
                        type: string
                        nullable: true
                        description: Opaque cursor for the next page. `null` when there are no more results.
                      totalCount:
                        type: integer
                        nullable: true
                        minimum: 0
                        description: Total number of surveys matching the current filters across all pages. `null` when `includeTotalCount=false`.
        "400":
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "401":
          description: Not authenticated (no valid session or API key)
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "403":
          description: Forbidden — no access, or workspace does not exist (404 not used; avoids existence leak)
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "429":
          description: Rate limit exceeded
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds until the current rate-limit window resets
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
      security:
        - sessionAuth: []
        - apiKeyAuth: []
    post:
      operationId: createSurveyV3
      summary: Create a survey
      description: |
        Creates a block-based survey template from one strict survey document. The endpoint accepts
        multilingual authoring maps keyed by real locale codes and converts them to Formbricks'
        internal default-language representation. Non-default locale keys in translated content
        must be declared in `languages`; undeclared locale keys return `unsupported_locale` in
        `invalid_params` instead of silently mutating workspace languages.

        `blocks[].id` and `variables[].id` are stable public identifiers. They may be omitted on
        create, in which case the server generates cuid2 ids. If the same create request needs to
        reference a block or variable from logic, provide explicit valid ids and use those references
        consistently.

        For normal sequential surveys, omit `logic` and `logicFallback`. `logicFallback` is only valid
        when the same block has at least one `logic` rule; otherwise the API returns
        `invalid_reference`.

        This first write surface intentionally stays structure-focused: `type` may be omitted or set
        to `link`, but `app`/in-app survey creation and distribution-channel settings are not part of
        this operation. Unsupported fields are rejected instead of ignored.
      tags:
        - V3 Surveys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSurveyRequest"
            examples:
              productFeedback:
                summary: Create a multilingual block-based survey
                value:
                  workspaceId: clxx1234567890123456789012
                  name: Product Feedback Survey
                  status: draft
                  defaultLanguage: en-US
                  metadata:
                    cx_operation: enterprise_onboarding
                    title:
                      en-US: Product Feedback
                      de-DE: Produktfeedback
                  languages:
                    - code: de-DE
                      enabled: true
                  welcomeCard:
                    enabled: true
                    headline:
                      en-US: Welcome
                      de-DE: Willkommen
                  blocks:
                    - name: Main Block
                      elements:
                        - id: satisfaction
                          type: openText
                          headline:
                            en-US: What should we improve?
                            de-DE: Was sollen wir verbessern?
                          required: true
                  endings: []
                  hiddenFields:
                    enabled: false
                  variables: []
              sequentialProductSurvey:
                summary: Create a richer sequential survey without logicFallback
                description: |
                  Multi-block survey with generated block and variable ids. Sequential surveys should
                  omit `logic` and `logicFallback`; blocks are shown in array order.
                value:
                  workspaceId: clxx1234567890123456789012
                  name: Sequential Product Survey
                  defaultLanguage: en-US
                  languages:
                    - code: de-DE
                      enabled: true
                  metadata:
                    cx_operation: product_feedback
                    title:
                      en-US: Sequential Product Survey
                      de-DE: Sequenzielle Produktumfrage
                  welcomeCard:
                    enabled: true
                    headline:
                      en-US: Help us improve the product
                      de-DE: Hilf uns, das Produkt zu verbessern
                  hiddenFields:
                    enabled: true
                    fieldIds:
                      - account_id
                      - plan
                  variables:
                    - name: feedback_score
                      type: number
                      value: 0
                  blocks:
                    - name: Satisfaction
                      elements:
                        - id: overall_rating
                          type: rating
                          headline:
                            en-US: How satisfied are you with the product?
                            de-DE: Wie zufrieden bist du mit dem Produkt?
                          required: true
                          range: 5
                          scale: smiley
                        - id: product_area
                          type: multipleChoiceSingle
                          headline:
                            en-US: Which area should we improve first?
                            de-DE: Welchen Bereich sollten wir zuerst verbessern?
                          required: true
                          choices:
                            - id: onboarding
                              label:
                                en-US: Onboarding
                                de-DE: Onboarding
                            - id: analytics
                              label:
                                en-US: Analytics
                                de-DE: Analysen
                    - name: Feedback
                      elements:
                        - id: free_text_feedback
                          type: openText
                          headline:
                            en-US: What is one thing we should change?
                            de-DE: Was sollten wir ändern?
                          required: false
                          longAnswer: true
                  endings:
                    - id: cmpsequentialend0000000000
                      type: endScreen
                      headline:
                        en-US: Thanks for your feedback!
                        de-DE: Danke für dein Feedback!
      responses:
        "201":
          description: Survey created successfully
          headers:
            Location:
              schema:
                type: string
              description: Relative URL of the created survey resource.
              example: /api/v3/surveys/clsv1234567890123456789012
            X-Request-Id:
              schema:
                type: string
              description: Request correlation ID
            Cache-Control:
              schema:
                type: string
              example: "private, no-store"
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    $ref: "#/components/schemas/SurveyResource"
        "400":
          description: |
            Bad Request — invalid JSON, unsupported fields, non-`link` type, malformed multilingual
            maps, duplicate stable ids, or dangling logic/reference ids.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "401":
          description: Not authenticated (no valid session or API key)
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "403":
          description: Forbidden — no write access, missing external URL permission, or workspace does not exist (404 not used; avoids existence leak)
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "429":
          description: Rate limit exceeded
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds until the current rate-limit window resets
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
      security:
        - sessionAuth: []
        - apiKeyAuth: []
  /api/v3/surveys/validate:
    post:
      operationId: validateSurveyV3
      summary: Validate a survey document
      description: |
        Validates a future create or patch survey payload without writing data, creating languages,
        or creating survey versions. Invalid survey documents return `200` with `data.valid=false`
        so agents and MCP clients can repair payloads from structured `invalid_params`.

        Use `400` only for malformed validation envelopes, unsupported operations, invalid `surveyId`,
        or unsupported query parameters.
      tags:
        - V3 Surveys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ValidateSurveyRequest"
            examples:
              createValidation:
                summary: Validate a create payload
                value:
                  operation: create
                  data:
                    workspaceId: clxx1234567890123456789012
                    name: Product Feedback Survey
                    defaultLanguage: en-US
                    blocks:
                      - id: clbk1234567890123456789012
                        name: Main Block
                        elements:
                          - id: satisfaction
                            type: openText
                            headline:
                              en-US: What should we improve?
                            required: true
              patchValidation:
                summary: Validate a future patch payload
                value:
                  operation: patch
                  surveyId: clsv1234567890123456789012
                  data:
                    blocks:
                      - id: clbk1234567890123456789012
                        name: Main Block
                        elements:
                          - id: satisfaction
                            type: openText
                            headline:
                              en-US: What should we improve?
                            required: true
      responses:
        "200":
          description: Validation completed. The survey document may still be invalid.
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Request correlation ID
            Cache-Control:
              schema:
                type: string
              example: "private, no-store"
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    $ref: "#/components/schemas/SurveyValidationResult"
              examples:
                invalid:
                  summary: Invalid survey document
                  value:
                    data:
                      valid: false
                      operation: create
                      invalid_params:
                        - name: blocks.0.elements.0.buttonUrl
                          reason: Unsupported field 'buttonUrl' for element type 'openText'. Allowed fields...
                valid:
                  summary: Valid survey document
                  value:
                    data:
                      valid: true
                      operation: create
                      invalid_params: []
                      languages:
                        - code: en-US
                          default: true
                          enabled: true
                          writeBehavior: connect_or_create
        "400":
          description: Malformed validation envelope, invalid route/query data, or unsupported operation
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "401":
          description: Not authenticated (no valid session or API key)
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "403":
          description: Forbidden — no write access, or survey/workspace does not exist
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "429":
          description: Rate limit exceeded
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds until the current rate-limit window resets
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
      security:
        - sessionAuth: []
        - apiKeyAuth: []
  /api/v3/surveys/{surveyId}:
    get:
      operationId: getSurveyV3
      summary: Retrieve a survey
      description: |
        Returns the public v3 survey management resource for one survey. By default, translatable
        fields are returned as stable multilingual maps keyed by the language codes emitted in
        `languages[].code`. Use `lang` to filter those maps to one or more requested language selectors.
      tags:
        - V3 Surveys
      parameters:
        - in: path
          name: surveyId
          required: true
          schema:
            type: string
            format: cuid2
          description: Survey identifier.
        - in: query
          name: lang
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
            examples:
              - [de-DE]
              - [de-DE, pt-PT]
              - [de]
              - [zh-Hans]
              - [zh-Hans-CN]
          description: |
            Comma-separated language selector filter for translatable fields, for example `?lang=de-DE,pt-PT`.
            The response shape stays stable: translatable fields are always maps, never strings, and response
            keys match the emitted `languages[].code` values for this survey.
            For compatibility with existing Formbricks surveys, GET accepts language tags such as `de`,
            `de-DE`, `zh-Hans`, and `zh-Hans-CN`, accepts `_` or `-` separators, is case-insensitive, and
            accepts configured workspace aliases such as `english`. Bare language selectors are resolved
            against the survey's configured languages and return `400` if ambiguous, for example if both
            `en-US` and `en-GB` are configured.
            Disabled-but-configured languages are readable in the management API so unfinished translations can
            be completed.
      responses:
        "200":
          description: Survey retrieved successfully
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Request correlation ID
            Cache-Control:
              schema:
                type: string
              example: "private, no-store"
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    $ref: "#/components/schemas/SurveyResource"
              examples:
                multilingual:
                  summary: Multilingual authoring resource
                  value:
                    data:
                      id: clseedsurveycsat000000
                      workspaceId: clseedworkspace000000000
                      createdAt: "2026-05-18T09:24:54.014Z"
                      updatedAt: "2026-05-18T09:24:54.014Z"
                      name: CSAT Survey
                      type: link
                      status: inProgress
                      metadata: {}
                      defaultLanguage: en-US
                      languages:
                        - code: en-US
                          default: true
                          enabled: true
                        - code: de-DE
                          alias: german
                          default: false
                          enabled: false
                      welcomeCard:
                        enabled: false
                      blocks:
                        - id: e0tfwzqk63op37y14z95qq3k
                          name: Main Block
                          elements:
                            - id: nzte4cm8836hgjw63pesziht
                              type: rating
                              range: 5
                              scale: smiley
                              headline:
                                en-US: How satisfied are you with our product?
                                de-DE: Wie zufrieden sind Sie mit unserem Produkt?
                              required: true
                      endings: []
                      hiddenFields:
                        enabled: false
                      variables: []
                filtered:
                  summary: Language-filtered projection with ?lang=de-DE
                  value:
                    data:
                      id: clseedsurveycsat000000
                      workspaceId: clseedworkspace000000000
                      createdAt: "2026-05-18T09:24:54.014Z"
                      updatedAt: "2026-05-18T09:24:54.014Z"
                      name: CSAT Survey
                      type: link
                      status: inProgress
                      metadata: {}
                      defaultLanguage: en-US
                      languages:
                        - code: en-US
                          default: true
                          enabled: true
                        - code: de-DE
                          alias: german
                          default: false
                          enabled: false
                      welcomeCard:
                        enabled: false
                      blocks:
                        - id: e0tfwzqk63op37y14z95qq3k
                          name: Main Block
                          elements:
                            - id: nzte4cm8836hgjw63pesziht
                              type: rating
                              range: 5
                              scale: smiley
                              headline:
                                de-DE: Wie zufrieden sind Sie mit unserem Produkt?
                              required: true
                      endings: []
                      hiddenFields:
                        enabled: false
                      variables: []
        "400":
          description: Invalid survey id, unsupported query parameter, unknown language, or unsupported legacy survey shape
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "401":
          description: Not authenticated (no valid session or API key)
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "403":
          description: Forbidden — no access, or survey does not exist (404 not used; avoids existence leak)
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "429":
          description: Rate limit exceeded
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds until the current rate-limit window resets
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
      security:
        - sessionAuth: []
        - apiKeyAuth: []
    delete:
      operationId: deleteSurveyV3
      summary: Delete a survey
      description: Deletes a survey by id. Session cookie or x-api-key.
      tags:
        - V3 Surveys
      parameters:
        - in: path
          name: surveyId
          required: true
          schema:
            type: string
            format: cuid2
          description: Survey identifier.
      responses:
        "204":
          description: Survey deleted successfully
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Request correlation ID
            Cache-Control:
              schema:
                type: string
              example: "private, no-store"
        "400":
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "401":
          description: Not authenticated (no valid session or API key)
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "403":
          description: Forbidden — no access, or survey does not exist (404 not used; avoids existence leak)
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "429":
          description: Rate limit exceeded
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds until the current rate-limit window resets
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
      security:
        - sessionAuth: []
        - apiKeyAuth: []

components:
  securitySchemes:
    sessionAuth:
      type: apiKey
      in: cookie
      name: next-auth.session-token
      description: |
        NextAuth session JWT cookie. **Development:** often `next-auth.session-token`.
        **Production (HTTPS):** often `__Secure-next-auth.session-token`. Send the cookie your browser receives after sign-in.
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: |
        Management API key; must include **workspaceId** as an allowed workspace with read, write, or manage permission.
  schemas:
    CreateSurveyRequest:
      type: object
      description: |
        Strict v3 survey creation document. This endpoint accepts survey structure only: name,
        metadata, languages, welcome card, blocks/elements/logic, endings, hidden fields, and variables.
        It rejects legacy `questions` and out-of-scope settings such as styling, targeting, segments,
        follow-ups, recaptcha, single-use/email verification, slug, custom scripts, analytics fields,
        timestamps, and `createdBy`.

        Translatable fields use real locale-code maps. The map must include the `defaultLanguage`
        key so the server can persist the internal default translation. Locale keys are normalized
        case-insensitively (`de_de` → `de-DE`). Non-default locale keys must be declared in
        `languages`; undeclared locale keys in metadata, welcome cards, blocks, or endings are
        rejected with `unsupported_locale`.

        `blocks[].id` and `variables[].id` may be omitted on create and will be generated by the
        server. Provide explicit cuid2 ids when other fields in the same request reference them.
        For normal sequential flow, omit `logicFallback`. It is only valid together with a non-empty
        `logic` array on the same block.
      required: [workspaceId, name, blocks]
      properties:
        workspaceId:
          type: string
          format: cuid2
          description: Workspace where the survey will be created. Requires read/write access.
        name:
          type: string
          minLength: 1
        type:
          type: string
          enum: [link]
          default: link
          description: |
            Optional compatibility field. Only `link` is accepted here; app/in-app survey distribution
            remains outside this structure-focused create endpoint.
        status:
          type: string
          enum: [draft, inProgress, paused, completed]
          default: draft
        metadata:
          allOf:
            - $ref: "#/components/schemas/SurveyMetadata"
          default: {}
        defaultLanguage:
          type: string
          default: en-US
          description: Default authoring locale. Translatable maps must include this locale key.
        languages:
          type: array
          default: []
          items:
            $ref: "#/components/schemas/CreateSurveyLanguage"
          description: |
            Optional survey language configuration. Languages also referenced by translatable maps are
            connected automatically. If omitted, languages are derived from `defaultLanguage` and map keys.
        welcomeCard:
          allOf:
            - $ref: "#/components/schemas/SurveyWelcomeCard"
          default:
            enabled: false
        blocks:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/CreateSurveyBlock"
        endings:
          type: array
          default: []
          items:
            $ref: "#/components/schemas/SurveyEnding"
        hiddenFields:
          allOf:
            - $ref: "#/components/schemas/SurveyHiddenFields"
          default:
            enabled: false
        variables:
          type: array
          default: []
          items:
            $ref: "#/components/schemas/CreateSurveyVariable"
      additionalProperties: false
    CreateSurveyLanguage:
      type: object
      description: Language to connect to the created survey. `default`, if provided, must match `defaultLanguage`.
      required: [code]
      properties:
        code:
          type: string
          description: BCP 47 locale code. `_` separators and casing are normalized.
          example: de-DE
        default:
          type: boolean
          description: Optional marker for readability; only the `defaultLanguage` entry may set this to true.
        enabled:
          type: boolean
          default: true
          description: Whether this language is enabled for respondent-facing delivery.
      additionalProperties: false
    PatchSurveyRequest:
      type: object
      description: |
        Future patch payload shape. Top-level fields are partial; any provided nested object or array
        fully replaces that subtree. Immutable/system fields such as `id`, `workspaceId`, `type`,
        timestamps, `questions`, analytics, distribution, styling, targeting, and scripts are rejected.
      properties:
        name:
          type: string
          minLength: 1
        status:
          type: string
          enum: [draft, inProgress, paused, completed]
        metadata:
          allOf:
            - $ref: "#/components/schemas/SurveyMetadata"
        defaultLanguage:
          type: string
          description: Default authoring locale.
        languages:
          type: array
          items:
            $ref: "#/components/schemas/CreateSurveyLanguage"
        welcomeCard:
          $ref: "#/components/schemas/SurveyWelcomeCard"
        blocks:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/SurveyBlock"
        endings:
          type: array
          items:
            $ref: "#/components/schemas/SurveyEnding"
        hiddenFields:
          $ref: "#/components/schemas/SurveyHiddenFields"
        variables:
          type: array
          items:
            $ref: "#/components/schemas/SurveyVariable"
      additionalProperties: false
    ValidateSurveyRequest:
      oneOf:
        - $ref: "#/components/schemas/ValidateSurveyCreateRequest"
        - $ref: "#/components/schemas/ValidateSurveyPatchRequest"
      discriminator:
        propertyName: operation
        mapping:
          create: "#/components/schemas/ValidateSurveyCreateRequest"
          patch: "#/components/schemas/ValidateSurveyPatchRequest"
    ValidateSurveyCreateRequest:
      type: object
      required: [operation, data]
      properties:
        operation:
          type: string
          enum: [create]
        data:
          description: Intended create payload. Invalid documents are allowed so the endpoint can return repairable validation errors.
          anyOf:
            - $ref: "#/components/schemas/CreateSurveyRequest"
            - type: object
              additionalProperties: true
      additionalProperties: false
    ValidateSurveyPatchRequest:
      type: object
      required: [operation, surveyId, data]
      properties:
        operation:
          type: string
          enum: [patch]
        surveyId:
          type: string
          format: cuid2
        data:
          description: Intended patch payload. Invalid documents are allowed so the endpoint can return repairable validation errors.
          anyOf:
            - $ref: "#/components/schemas/PatchSurveyRequest"
            - type: object
              additionalProperties: true
      additionalProperties: false
    SurveyValidationResult:
      type: object
      required: [valid, operation, invalid_params]
      properties:
        valid:
          type: boolean
          description: Whether the submitted survey document is valid.
        operation:
          type: string
          enum: [create, patch]
        invalid_params:
          type: array
          description: Repairable validation errors using document-relative paths.
          items:
            $ref: "#/components/schemas/InvalidParam"
        languages:
          type: array
          description: Languages that a successful write would connect or create. Present only when `valid=true`.
          items:
            $ref: "#/components/schemas/SurveyValidationLanguage"
      additionalProperties: false
    SurveyValidationLanguage:
      type: object
      required: [code, default, enabled, writeBehavior]
      properties:
        code:
          type: string
        default:
          type: boolean
        enabled:
          type: boolean
        writeBehavior:
          type: string
          enum: [connect_or_create]
          description: Validation is read-only; a real write would connect an existing language or create it if missing.
      additionalProperties: false
    SurveyListItem:
      type: object
      description: |
        Shape returned by `GET /api/v3/surveys`. Serialized dates are ISO 8601 strings.
        The v3 overview contract intentionally omits internal fields such as `_count`.
        Legacy DB rows may include survey **type** values `website` or `web` (see Prisma); filter **type** only accepts `link` | `app`.
      properties:
        id:
          type: string
        name:
          type: string
        workspaceId:
          type: string
        type:
          type: string
          enum: [link, app, website, web]
        status:
          type: string
          enum: [draft, inProgress, paused, completed]
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        responseCount:
          type: integer
        creator:
          type: object
          nullable: true
          properties:
            name:
              type: string
        singleUse:
          type: object
          nullable: true
          properties:
            enabled:
              type: boolean
            isEncrypted:
              type: boolean
    TranslatableText:
      allOf:
        - $ref: "#/components/schemas/TranslatableTextMap"
      description: |
        Survey authoring text. `GET /api/v3/surveys/{surveyId}` always returns maps keyed by the emitted
        `languages[].code` values for this survey. Use `?lang=` to filter which language keys are included.
        The internal storage key `default` is never exposed by v3.
      examples:
        - en-US: What should we improve?
          de-DE: Was sollten wir verbessern?
    TranslatableTextMap:
      type: object
      description: Multilingual text map keyed by the emitted `languages[].code` values for this survey.
      propertyNames:
        type: string
        description: Survey language code/tag, for example `en-US`, `de-DE`, `vi`, or `zh-Hans`.
      additionalProperties:
        type: string
    SurveyMetadata:
      type: object
      description: |
        Arbitrary JSON survey context for customer- or operation-specific metadata. v3 preserves
        arbitrary metadata values as-is. If present, `title` and `description` are treated as
        translatable text maps and returned with real locale-code keys.
      properties:
        title:
          $ref: "#/components/schemas/TranslatableText"
        description:
          $ref: "#/components/schemas/TranslatableText"
      additionalProperties: true
    SurveyLanguage:
      type: object
      description: |
        Language configured for this survey. GET responses expose the server-emitted code/tag used as the
        translatable map key. Existing surveys can use region-qualified, language-only, or script-only codes.
        Disabled languages can still be read by the management API so unfinished translations can be completed.
      required: [code, default, enabled]
      properties:
        code:
          type: string
          description: Server-emitted survey language code/tag used as the translatable map key.
          example: en-US
        alias:
          type: string
          nullable: true
          description: Optional configured alias accepted by `?lang` for compatibility and agent discovery.
          example: english
        default:
          type: boolean
          description: Whether this is the default authoring language.
        enabled:
          type: boolean
          description: Whether this language is enabled for respondent-facing delivery.
    SurveyWelcomeCard:
      type: object
      description: Optional card shown before the first survey block.
      required: [enabled]
      properties:
        enabled:
          type: boolean
        headline:
          $ref: "#/components/schemas/TranslatableText"
        subheader:
          $ref: "#/components/schemas/TranslatableText"
        buttonLabel:
          $ref: "#/components/schemas/TranslatableText"
        fileUrl:
          type: string
        videoUrl:
          type: string
        timeToFinish:
          type: boolean
        showResponseCount:
          type: boolean
      additionalProperties: false
    SurveyHiddenFields:
      type: object
      description: |
        Hidden fields, sometimes called embedded data in other survey products. Field ids are stable
        public identifiers and may be referenced by logic, recall, quotas, integrations, and response data.
        Use only letters, numbers, underscores, and hyphens; avoid spaces and reserved ids.
      required: [enabled]
      properties:
        enabled:
          type: boolean
        fieldIds:
          type: array
          items:
            type: string
            pattern: "^[a-zA-Z0-9_-]+$"
          uniqueItems: true
      additionalProperties: false
    SurveyVariable:
      oneOf:
        - $ref: "#/components/schemas/SurveyNumberVariable"
        - $ref: "#/components/schemas/SurveyTextVariable"
      description: |
        Survey variable. Variable ids are stable references used by logic and calculation actions.
        Variable names are human-readable labels and must be unique within the survey.
    CreateSurveyVariable:
      oneOf:
        - $ref: "#/components/schemas/CreateSurveyNumberVariable"
        - $ref: "#/components/schemas/CreateSurveyTextVariable"
      description: |
        Survey variable accepted by `POST /api/v3/surveys`. `id` may be omitted and will be
        generated by the server. Provide an explicit cuid2 id when logic in the same request needs
        to reference this variable.
    CreateSurveyNumberVariable:
      type: object
      required: [name, type, value]
      properties:
        id:
          type: string
          format: cuid2
          description: Optional stable variable id. Generated when omitted.
        name:
          type: string
          pattern: "^[a-z0-9_]+$"
          description: Unique variable name. Lowercase letters, numbers, and underscores only.
        type:
          type: string
          enum: [number]
        value:
          type: number
          description: Default numeric value.
      additionalProperties: false
    CreateSurveyTextVariable:
      type: object
      required: [name, type, value]
      properties:
        id:
          type: string
          format: cuid2
          description: Optional stable variable id. Generated when omitted.
        name:
          type: string
          pattern: "^[a-z0-9_]+$"
          description: Unique variable name. Lowercase letters, numbers, and underscores only.
        type:
          type: string
          enum: [text]
        value:
          type: string
          description: Default text value.
      additionalProperties: false
    SurveyNumberVariable:
      type: object
      description: |
        Number variable. Used by `calculate` logic actions with numeric operators such as `add`,
        `subtract`, `multiply`, `divide`, or `assign`.
      required: [id, name, type, value]
      properties:
        id:
          type: string
          format: cuid2
          description: Stable variable id referenced from logic.
        name:
          type: string
          pattern: "^[a-z0-9_]+$"
          description: Unique variable name. Lowercase letters, numbers, and underscores only.
        type:
          type: string
          enum: [number]
        value:
          type: number
          description: Default numeric value.
      additionalProperties: false
    SurveyTextVariable:
      type: object
      description: |
        Text variable. Used by `calculate` logic actions with text operators such as `assign` or `concat`.
      required: [id, name, type, value]
      properties:
        id:
          type: string
          format: cuid2
          description: Stable variable id referenced from logic.
        name:
          type: string
          pattern: "^[a-z0-9_]+$"
          description: Unique variable name. Lowercase letters, numbers, and underscores only.
        type:
          type: string
          enum: [text]
        value:
          type: string
          description: Default text value.
      additionalProperties: false
    SurveyEnding:
      oneOf:
        - $ref: "#/components/schemas/SurveyEndScreenEnding"
        - $ref: "#/components/schemas/SurveyRedirectEnding"
      discriminator:
        propertyName: type
        mapping:
          endScreen: "#/components/schemas/SurveyEndScreenEnding"
          redirectToUrl: "#/components/schemas/SurveyRedirectEnding"
      description: |
        Ending reached after the last block or a jump action. `type` selects the allowed shape;
        unsupported fields are rejected instead of ignored.
    SurveyEndScreenEnding:
      type: object
      description: Visual end screen displayed after survey completion.
      required: [id, type]
      properties:
        id:
          type: string
          format: cuid2
          description: Stable ending id. `jumpToBlock.target` may point to this id.
        type:
          type: string
          enum: [endScreen]
        headline:
          $ref: "#/components/schemas/TranslatableText"
        subheader:
          $ref: "#/components/schemas/TranslatableText"
        buttonLabel:
          $ref: "#/components/schemas/TranslatableText"
        buttonLink:
          type: string
        imageUrl:
          type: string
        videoUrl:
          type: string
      additionalProperties: false
    SurveyRedirectEnding:
      type: object
      description: |
        Redirects the respondent to a URL after survey completion. External redirects require the
        organization's external URL permission; otherwise write endpoints return `403 Forbidden`.
      required: [id, type, url]
      properties:
        id:
          type: string
          format: cuid2
          description: Stable ending id. `jumpToBlock.target` may point to this id.
        type:
          type: string
          enum: [redirectToUrl]
        url:
          type: string
          description: External redirect URL. Requires the organization's external URL permission.
        label:
          type: string
          description: Optional internal label for redirect endings.
      additionalProperties: false
    SurveyBlock:
      type: object
      description: |
        Block-based survey section. Block ids are stable public identifiers. Logic and fallbacks can
        jump to block ids or ending ids, so clients and agents should preserve ids unless intentionally
        creating/deleting a block.
      required: [id, name, elements]
      properties:
        id:
          type: string
          format: cuid2
          description: Stable block id.
        name:
          type: string
          minLength: 1
        elements:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/SurveyElement"
        logic:
          type: array
          items:
            $ref: "#/components/schemas/SurveyBlockLogic"
        logicFallback:
          type: string
          format: cuid2
          description: |
            Block or ending id used when no logic condition matches. Only valid when this same block
            has at least one `logic` rule; omit it for normal sequential flow.
        buttonLabel:
          $ref: "#/components/schemas/TranslatableText"
        backButtonLabel:
          $ref: "#/components/schemas/TranslatableText"
      additionalProperties: false
    CreateSurveyBlock:
      type: object
      description: |
        Block accepted by `POST /api/v3/surveys`. `id` may be omitted and will be generated by the
        server. Provide an explicit cuid2 id when logic in the same request needs to jump to this block.
        For normal sequential flow, omit `logic` and `logicFallback`. `logicFallback` is only valid
        when this same block has at least one `logic` rule.
      required: [name, elements]
      properties:
        id:
          type: string
          format: cuid2
          description: Optional stable block id. Generated when omitted.
        name:
          type: string
          minLength: 1
        elements:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/SurveyElement"
        logic:
          type: array
          items:
            $ref: "#/components/schemas/SurveyBlockLogic"
        logicFallback:
          type: string
          format: cuid2
          description: |
            Block or ending id used when no logic condition matches. Only valid when this same block
            has at least one `logic` rule; omit it for normal sequential flow.
        buttonLabel:
          $ref: "#/components/schemas/TranslatableText"
        backButtonLabel:
          $ref: "#/components/schemas/TranslatableText"
      additionalProperties: false
    SurveyElement:
      oneOf:
        - $ref: "#/components/schemas/SurveyOpenTextElement"
        - $ref: "#/components/schemas/SurveyConsentElement"
        - $ref: "#/components/schemas/SurveyMultipleChoiceSingleElement"
        - $ref: "#/components/schemas/SurveyMultipleChoiceMultiElement"
        - $ref: "#/components/schemas/SurveyNpsElement"
        - $ref: "#/components/schemas/SurveyCtaElement"
        - $ref: "#/components/schemas/SurveyRatingElement"
        - $ref: "#/components/schemas/SurveyPictureSelectionElement"
        - $ref: "#/components/schemas/SurveyDateElement"
        - $ref: "#/components/schemas/SurveyFileUploadElement"
        - $ref: "#/components/schemas/SurveyCalElement"
        - $ref: "#/components/schemas/SurveyMatrixElement"
        - $ref: "#/components/schemas/SurveyAddressElement"
        - $ref: "#/components/schemas/SurveyRankingElement"
        - $ref: "#/components/schemas/SurveyContactInfoElement"
        - $ref: "#/components/schemas/SurveyCsatElement"
        - $ref: "#/components/schemas/SurveyCesElement"
      discriminator:
        propertyName: type
        mapping:
          openText: "#/components/schemas/SurveyOpenTextElement"
          consent: "#/components/schemas/SurveyConsentElement"
          multipleChoiceSingle: "#/components/schemas/SurveyMultipleChoiceSingleElement"
          multipleChoiceMulti: "#/components/schemas/SurveyMultipleChoiceMultiElement"
          nps: "#/components/schemas/SurveyNpsElement"
          cta: "#/components/schemas/SurveyCtaElement"
          rating: "#/components/schemas/SurveyRatingElement"
          pictureSelection: "#/components/schemas/SurveyPictureSelectionElement"
          date: "#/components/schemas/SurveyDateElement"
          fileUpload: "#/components/schemas/SurveyFileUploadElement"
          cal: "#/components/schemas/SurveyCalElement"
          matrix: "#/components/schemas/SurveyMatrixElement"
          address: "#/components/schemas/SurveyAddressElement"
          ranking: "#/components/schemas/SurveyRankingElement"
          contactInfo: "#/components/schemas/SurveyContactInfoElement"
          csat: "#/components/schemas/SurveyCsatElement"
          ces: "#/components/schemas/SurveyCesElement"
      description: |
        Survey element/question inside a block. Element ids are stable public identifiers used by
        logic, recall strings, response data, quotas, integrations, and analysis. `type` selects the
        allowed shape; unsupported fields are rejected instead of ignored.
    SurveyElementBase:
      type: object
      required: [id, type, headline, required]
      properties:
        id:
          type: string
          pattern: "^[a-zA-Z0-9_-]+$"
          description: Stable element id. Avoid spaces and reserved ids.
        type:
          type: string
          enum:
            - openText
            - multipleChoiceSingle
            - multipleChoiceMulti
            - nps
            - rating
            - csat
            - ces
            - consent
            - pictureSelection
            - cta
            - date
            - fileUpload
            - cal
            - matrix
            - address
            - ranking
            - contactInfo
        headline:
          $ref: "#/components/schemas/TranslatableText"
        subheader:
          $ref: "#/components/schemas/TranslatableText"
        required:
          type: boolean
        imageUrl:
          type: string
        videoUrl:
          type: string
        isDraft:
          type: boolean
          description: Draft marker used by the editor and future update rules.
    SurveyOpenTextElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          properties:
            type:
              type: string
              enum: [openText]
            placeholder:
              $ref: "#/components/schemas/TranslatableText"
            longAnswer:
              type: boolean
            inputType:
              type: string
              enum: [text, email, url, number, phone]
              default: text
            insightsEnabled:
              type: boolean
              default: false
            charLimit:
              $ref: "#/components/schemas/SurveyCharLimit"
            validation:
              $ref: "#/components/schemas/SurveyValidation"
      unevaluatedProperties: false
    SurveyConsentElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          required: [label]
          properties:
            type:
              type: string
              enum: [consent]
            label:
              $ref: "#/components/schemas/TranslatableText"
            validation:
              $ref: "#/components/schemas/SurveyValidation"
      unevaluatedProperties: false
    SurveyMultipleChoiceSingleElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          required: [choices]
          properties:
            type:
              type: string
              enum: [multipleChoiceSingle]
            choices:
              type: array
              minItems: 2
              items:
                $ref: "#/components/schemas/SurveyChoice"
            shuffleOption:
              $ref: "#/components/schemas/SurveyShuffleOption"
            otherOptionPlaceholder:
              $ref: "#/components/schemas/TranslatableText"
            displayType:
              $ref: "#/components/schemas/SurveyMultipleChoiceDisplayType"
      unevaluatedProperties: false
    SurveyMultipleChoiceMultiElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          required: [choices]
          properties:
            type:
              type: string
              enum: [multipleChoiceMulti]
            choices:
              type: array
              minItems: 2
              items:
                $ref: "#/components/schemas/SurveyChoice"
            shuffleOption:
              $ref: "#/components/schemas/SurveyShuffleOption"
            otherOptionPlaceholder:
              $ref: "#/components/schemas/TranslatableText"
            validation:
              $ref: "#/components/schemas/SurveyValidation"
            displayType:
              $ref: "#/components/schemas/SurveyMultipleChoiceDisplayType"
      unevaluatedProperties: false
    SurveyNpsElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          properties:
            type:
              type: string
              enum: [nps]
            lowerLabel:
              $ref: "#/components/schemas/TranslatableText"
            upperLabel:
              $ref: "#/components/schemas/TranslatableText"
            isColorCodingEnabled:
              type: boolean
              default: false
      unevaluatedProperties: false
    SurveyCtaElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          description: If `buttonExternal` is true, `buttonUrl` and `ctaButtonLabel` are required.
          properties:
            type:
              type: string
              enum: [cta]
            buttonExternal:
              type: boolean
              default: false
            buttonUrl:
              type: string
            ctaButtonLabel:
              $ref: "#/components/schemas/TranslatableText"
      unevaluatedProperties: false
    SurveyRatingElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          required: [scale, range]
          properties:
            type:
              type: string
              enum: [rating]
            scale:
              type: string
              enum: [number, smiley, star]
            range:
              type: integer
              enum: [3, 4, 5, 6, 7, 10]
            lowerLabel:
              $ref: "#/components/schemas/TranslatableText"
            upperLabel:
              $ref: "#/components/schemas/TranslatableText"
            isColorCodingEnabled:
              type: boolean
              default: false
      unevaluatedProperties: false
    SurveyPictureSelectionElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          required: [choices]
          properties:
            type:
              type: string
              enum: [pictureSelection]
            allowMulti:
              type: boolean
              default: false
            choices:
              type: array
              minItems: 2
              items:
                $ref: "#/components/schemas/SurveyPictureChoice"
            validation:
              $ref: "#/components/schemas/SurveyValidation"
      unevaluatedProperties: false
    SurveyDateElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          required: [format]
          properties:
            type:
              type: string
              enum: [date]
            html:
              $ref: "#/components/schemas/TranslatableText"
            format:
              type: string
              enum: [M-d-y, d-M-y, y-M-d]
            validation:
              $ref: "#/components/schemas/SurveyValidation"
      unevaluatedProperties: false
    SurveyFileUploadElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          required: [allowMultipleFiles]
          properties:
            type:
              type: string
              enum: [fileUpload]
            allowMultipleFiles:
              type: boolean
            maxSizeInMB:
              type: number
            allowedFileExtensions:
              type: array
              items:
                type: string
            validation:
              $ref: "#/components/schemas/SurveyValidation"
      unevaluatedProperties: false
    SurveyCalElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          required: [calUserName]
          properties:
            type:
              type: string
              enum: [cal]
            calUserName:
              type: string
              minLength: 1
            calHost:
              type: string
      unevaluatedProperties: false
    SurveyMatrixElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          required: [rows, columns]
          properties:
            type:
              type: string
              enum: [matrix]
            rows:
              type: array
              items:
                $ref: "#/components/schemas/SurveyChoice"
            columns:
              type: array
              items:
                $ref: "#/components/schemas/SurveyChoice"
            shuffleOption:
              $ref: "#/components/schemas/SurveyShuffleOption"
            validation:
              $ref: "#/components/schemas/SurveyValidation"
      unevaluatedProperties: false
    SurveyAddressElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          required: [addressLine1, addressLine2, city, state, zip, country]
          properties:
            type:
              type: string
              enum: [address]
            addressLine1:
              $ref: "#/components/schemas/SurveyToggleInputConfig"
            addressLine2:
              $ref: "#/components/schemas/SurveyToggleInputConfig"
            city:
              $ref: "#/components/schemas/SurveyToggleInputConfig"
            state:
              $ref: "#/components/schemas/SurveyToggleInputConfig"
            zip:
              $ref: "#/components/schemas/SurveyToggleInputConfig"
            country:
              $ref: "#/components/schemas/SurveyToggleInputConfig"
            validation:
              $ref: "#/components/schemas/SurveyValidation"
      unevaluatedProperties: false
    SurveyRankingElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          required: [choices]
          properties:
            type:
              type: string
              enum: [ranking]
            choices:
              type: array
              minItems: 2
              maxItems: 25
              items:
                $ref: "#/components/schemas/SurveyChoice"
            otherOptionPlaceholder:
              $ref: "#/components/schemas/TranslatableText"
            shuffleOption:
              $ref: "#/components/schemas/SurveyShuffleOption"
            validation:
              $ref: "#/components/schemas/SurveyValidation"
      unevaluatedProperties: false
    SurveyContactInfoElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          required: [firstName, lastName, email, phone, company]
          properties:
            type:
              type: string
              enum: [contactInfo]
            firstName:
              $ref: "#/components/schemas/SurveyToggleInputConfig"
            lastName:
              $ref: "#/components/schemas/SurveyToggleInputConfig"
            email:
              $ref: "#/components/schemas/SurveyToggleInputConfig"
            phone:
              $ref: "#/components/schemas/SurveyToggleInputConfig"
            company:
              $ref: "#/components/schemas/SurveyToggleInputConfig"
            validation:
              $ref: "#/components/schemas/SurveyValidation"
      unevaluatedProperties: false
    SurveyCsatElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          required: [scale, range]
          properties:
            type:
              type: string
              enum: [csat]
            scale:
              type: string
              enum: [number, smiley, star]
            range:
              type: integer
              enum: [5]
            lowerLabel:
              $ref: "#/components/schemas/TranslatableText"
            upperLabel:
              $ref: "#/components/schemas/TranslatableText"
            isColorCodingEnabled:
              type: boolean
              default: false
      unevaluatedProperties: false
    SurveyCesElement:
      allOf:
        - $ref: "#/components/schemas/SurveyElementBase"
        - type: object
          required: [scale, range]
          properties:
            type:
              type: string
              enum: [ces]
            scale:
              type: string
              enum: [number, smiley, star]
            range:
              type: integer
              enum: [5, 7]
            lowerLabel:
              $ref: "#/components/schemas/TranslatableText"
            upperLabel:
              $ref: "#/components/schemas/TranslatableText"
            isColorCodingEnabled:
              type: boolean
              default: false
      unevaluatedProperties: false
    SurveyCharLimit:
      type: object
      description: Optional `openText` character limit configuration.
      properties:
        enabled:
          type: boolean
          default: false
        min:
          type: number
        max:
          type: number
      additionalProperties: false
    SurveyShuffleOption:
      type: string
      enum: [none, all, exceptLast, reverseOrderOccasionally, reverseOrderExceptLast]
    SurveyMultipleChoiceDisplayType:
      type: string
      enum: [list, dropdown]
    SurveyChoice:
      type: object
      required: [id, label]
      properties:
        id:
          type: string
          description: Stable choice id.
        label:
          $ref: "#/components/schemas/TranslatableText"
      additionalProperties: false
    SurveyPictureChoice:
      type: object
      required: [id, imageUrl]
      properties:
        id:
          type: string
          description: Stable picture choice id.
        imageUrl:
          type: string
      additionalProperties: false
    SurveyToggleInputConfig:
      type: object
      description: Field config for address and contact info elements.
      required: [show, required, placeholder]
      properties:
        show:
          type: boolean
        required:
          type: boolean
        placeholder:
          $ref: "#/components/schemas/TranslatableText"
      additionalProperties: false
    SurveyValidation:
      type: object
      description: Optional element-level validation rules.
      required: [rules]
      properties:
        logic:
          type: string
          enum: [and, or]
          default: and
        rules:
          type: array
          items:
            $ref: "#/components/schemas/SurveyValidationRule"
      additionalProperties: false
    SurveyValidationRule:
      type: object
      required: [id, type, params]
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - minLength
            - maxLength
            - pattern
            - email
            - url
            - phone
            - equals
            - doesNotEqual
            - contains
            - doesNotContain
            - minValue
            - maxValue
            - isGreaterThan
            - isLessThan
            - minSelections
            - maxSelections
            - minRanked
            - rankAll
            - minRowsAnswered
            - answerAllRows
            - isLaterThan
            - isEarlierThan
            - isBetween
            - isNotBetween
            - fileExtensionIs
            - fileExtensionIsNot
        params:
          type: object
          additionalProperties: true
        field:
          type: string
          enum:
            [
              addressLine1,
              addressLine2,
              city,
              state,
              zip,
              country,
              firstName,
              lastName,
              email,
              phone,
              company,
            ]
      additionalProperties: false
    SurveyBlockLogic:
      type: object
      description: Conditional logic rule evaluated at block level.
      required: [id, conditions, actions]
      properties:
        id:
          type: string
          format: cuid2
        conditions:
          $ref: "#/components/schemas/SurveyConditionGroup"
        actions:
          type: array
          items:
            $ref: "#/components/schemas/SurveyLogicAction"
      additionalProperties: false
    SurveyConditionGroup:
      type: object
      required: [id, connector, conditions]
      properties:
        id:
          type: string
          format: cuid2
        connector:
          type: string
          enum: [and, or]
        conditions:
          type: array
          items:
            oneOf:
              - $ref: "#/components/schemas/SurveyCondition"
              - $ref: "#/components/schemas/SurveyConditionGroup"
      additionalProperties: false
    SurveyCondition:
      type: object
      description: |
        Single condition. Operators such as `isSubmitted`, `isSkipped`, `isClicked`, `isAccepted`,
        `isBooked`, `isSet`, and `isEmpty` do not use `rightOperand`; comparison operators do.
      required: [id, leftOperand, operator]
      properties:
        id:
          type: string
          format: cuid2
        leftOperand:
          $ref: "#/components/schemas/SurveyDynamicReference"
        operator:
          type: string
          enum:
            - equals
            - doesNotEqual
            - contains
            - doesNotContain
            - startsWith
            - doesNotStartWith
            - endsWith
            - doesNotEndWith
            - isSubmitted
            - isSkipped
            - isGreaterThan
            - isLessThan
            - isGreaterThanOrEqual
            - isLessThanOrEqual
            - equalsOneOf
            - includesAllOf
            - includesOneOf
            - doesNotIncludeOneOf
            - doesNotIncludeAllOf
            - isClicked
            - isNotClicked
            - isAccepted
            - isBefore
            - isAfter
            - isBooked
            - isPartiallySubmitted
            - isCompletelySubmitted
            - isSet
            - isNotSet
            - isEmpty
            - isNotEmpty
            - isAnyOf
        rightOperand:
          $ref: "#/components/schemas/SurveyLogicOperand"
      additionalProperties: false
    SurveyLogicOperand:
      oneOf:
        - type: object
          required: [type, value]
          properties:
            type:
              type: string
              enum: [static]
            value:
              oneOf:
                - type: string
                - type: number
                - type: array
                  items:
                    type: string
          additionalProperties: false
        - $ref: "#/components/schemas/SurveyDynamicReference"
    SurveyDynamicReference:
      type: object
      description: Dynamic reference to another value in the survey document.
      required: [type, value]
      properties:
        type:
          type: string
          enum: [element, variable, hiddenField]
        value:
          type: string
          description: Element id, variable id, or hidden field id depending on `type`.
        meta:
          type: object
          additionalProperties:
            type: string
      additionalProperties: false
    SurveyLogicAction:
      oneOf:
        - $ref: "#/components/schemas/SurveyCalculateAction"
        - $ref: "#/components/schemas/SurveyRequireAnswerAction"
        - $ref: "#/components/schemas/SurveyJumpToBlockAction"
      description: |
        Logic action. Keep referenced ids stable: `calculate.variableId` points to a variable id,
        `requireAnswer.target` points to an element id, and `jumpToBlock.target` points to a block id
        or ending id.
    SurveyCalculateAction:
      type: object
      description: Updates a survey variable when the logic rule matches.
      required: [id, objective, variableId, operator, value]
      properties:
        id:
          type: string
          format: cuid2
        objective:
          type: string
          enum: [calculate]
        variableId:
          type: string
          format: cuid2
          description: Variable id for `calculate`.
        operator:
          type: string
          enum: [assign, concat, add, subtract, multiply, divide]
        value:
          $ref: "#/components/schemas/SurveyLogicOperand"
      additionalProperties: false
    SurveyRequireAnswerAction:
      type: object
      description: Requires an element/question to be answered before continuing.
      required: [id, objective, target]
      properties:
        id:
          type: string
          format: cuid2
        objective:
          type: string
          enum: [requireAnswer]
        target:
          type: string
          description: Target element id.
      additionalProperties: false
    SurveyJumpToBlockAction:
      type: object
      description: Jumps to another block or ending when the logic rule matches.
      required: [id, objective, target]
      properties:
        id:
          type: string
          format: cuid2
        objective:
          type: string
          enum: [jumpToBlock]
        target:
          type: string
          format: cuid2
          description: Target block id or ending id.
      additionalProperties: false
    SurveyResource:
      type: object
      required:
        - id
        - workspaceId
        - createdAt
        - updatedAt
        - name
        - type
        - status
        - metadata
        - defaultLanguage
        - languages
        - welcomeCard
        - blocks
        - endings
        - hiddenFields
        - variables
      properties:
        id:
          type: string
        workspaceId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        name:
          type: string
        type:
          type: string
          enum: [link, app, website, web]
        status:
          type: string
          enum: [draft, inProgress, paused, completed]
        metadata:
          allOf:
            - $ref: "#/components/schemas/SurveyMetadata"
          nullable: true
        defaultLanguage:
          type: string
          description: Emitted language code/tag for the survey default language. The internal `default` translation key is never exposed.
        languages:
          type: array
          items:
            $ref: "#/components/schemas/SurveyLanguage"
        welcomeCard:
          $ref: "#/components/schemas/SurveyWelcomeCard"
        blocks:
          type: array
          items:
            $ref: "#/components/schemas/SurveyBlock"
        endings:
          type: array
          items:
            $ref: "#/components/schemas/SurveyEnding"
        hiddenFields:
          $ref: "#/components/schemas/SurveyHiddenFields"
        variables:
          type: array
          items:
            $ref: "#/components/schemas/SurveyVariable"
    InvalidParam:
      type: object
      description: |
        Field-level validation error. `name` and `reason` are always intended for humans.
        Optional machine-readable fields are included when the API can identify the semantic error,
        especially for survey locale, identifier, and reference validation used by MCP and agent clients.
      required: [name, reason]
      properties:
        name:
          type: string
          description: Dot-path to the invalid request field.
        reason:
          type: string
          description: Human-readable repair guidance.
        code:
          type: string
          enum:
            - dangling_reference
            - duplicate_identifier
            - duplicate_locale
            - forbidden_identifier
            - immutable_identifier
            - invalid_locale
            - invalid_reference
            - missing_required_field
            - missing_translation
            - unsupported_field
            - unsupported_locale
          description: Machine-readable validation category, when available.
        identifier:
          type: string
          description: Identifier involved in the validation failure, when available. For language errors, this can be the normalized language code.
        referenceType:
          type: string
          enum: [block, element, ending, hiddenField, language, variable, variableName, recall]
          description: Identifier namespace involved in the validation failure.
        missingId:
          type: string
          description: Referenced id that does not exist in the submitted survey document.
        firstUsedAt:
          type: string
          description: Dot-path where a duplicate identifier was first used.
        conflictsWith:
          type: string
          description: Dot-path to the existing identifier that conflicts with this field.
      additionalProperties: false
    Problem:
      type: object
      description: RFC 9457 Problem Details for HTTP APIs (`application/problem+json`). Responses typically include a machine-readable `code` field alongside `title`, `status`, `detail`, and `requestId`.
      required: [title, status, detail, requestId]
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        code:
          type: string
          enum: [bad_request, not_authenticated, forbidden, internal_server_error, too_many_requests]
        requestId:
          type: string
        details:
          type: object
        invalid_params:
          type: array
          items:
            $ref: "#/components/schemas/InvalidParam"