> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usertick.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Usertick runs surveys on websites, by link, by QR code and by email, and collects every response in one inbox with reports, dashboards and workflows. The REST API lives at https://app.usertick.com/api/public/v1 and uses Bearer API keys or OAuth access tokens; the JavaScript SDK is the @usertick/snippet package on npm.

# Edit a survey draft

> Edits a survey that was never published: 1 to 50 operations (add_question with after, update_question that changes only the fields sent, remove_question, move_question, set_survey, set_targeting), applied in order and saved together or not at all. Nothing goes live: a person publishes the draft in Usertick (editorUrl). The questions are checked the way a dashboard save checks them, each error naming its field, and the plan's limits apply as in the dashboard; no Usertick AI credits are used. Send expectedDraftVersion from the last read: a draft that changed since is 409 PUB-008-004 (read it again and redo the edit). While the survey is open in the Usertick editor the edit is 409 PUB-008-003 (ask the person to close it). A live, paused or archived survey is 409 PUB-008-005: its changes are made in the dashboard. Removing a question leaves a rule that jumped to it without a destination, as the editor does. Answers with the draft.

Scopes: surveys:draft, surveys:read.



## OpenAPI

````yaml api-reference/openapi.json PATCH /surveys/{surveyId}/draft
openapi: 3.1.0
info:
  title: Usertick Public API
  version: 1.0.0
  description: >-
    The Usertick REST API v1: responses, surveys, metrics, contacts, email sends
    and webhook subscriptions of one organization.


    **Authentication.** Send an API key (Settings, Developers, API keys;
    utk_...) or an app's OAuth access token (uto_...) as Authorization: Bearer.
    X-Api-Key works for clients that cannot set Authorization. Each endpoint
    lists the scopes it needs. API keys work on Pro plans and up, and apps such
    as Zapier on every plan. AI assistants reach the API only through the
    Usertick MCP server (Starter and up), never with their token directly.


    **Format.** Plain JSON resources; times are RFC 3339 in UTC with
    milliseconds (2026-09-30T10:00:00.000Z). Lists are { data, nextCursor }:
    limit is 1 to 100 (default 25, out of range is 400), and nextCursor goes
    back as cursor until it is null. A page starts strictly after the last row
    of the page before, so a row deleted or renamed in between never ends a list
    early.


    **Errors.** Every error is { statusCode, success: false, code, message, data
    }, plus errors: [{ field, code, message }] for invalid fields. Switch on
    code (x-error-codes lists them all); messages may change. A path with no
    route answers 404 GEN-000-404, a method the route doesn't take 405
    GEN-000-405 and a body that is not JSON 415 GEN-000-415, in the same
    envelope.


    **Rate limits.** The plan sets the requests a minute, as token buckets: 300
    per credential and 1,500 per organization on Business, 120 and 600 on the
    other plans, and an Enterprise plan may set its own. GET /me returns the
    ones that apply. An answer to an authenticated request has
    X-RateLimit-Limit, -Remaining and -Reset (seconds until the budget is full)
    for the credential, and X-RateLimit-Org-* for the organization, except a 429
    over the credential's budget, which has the credential's only, and
    X-RateLimit-Window: 60s. Over a budget is 429 with Retry-After, the seconds
    the bucket takes to refill one request. A 401 carries no X-RateLimit
    headers, and neither does a 429 GEN-429-001 from the per-address limit
    (3,000 requests a minute per client address, checked before the credential).
    Calls from the Usertick MCP server skip the per-address limit, since every
    assistant arrives from its addresses; the per-credential and
    per-organization budgets still apply to them.


    **Idempotency.** Every POST, and the PATCH of a survey, dashboard or
    workflow draft, takes an Idempotency-Key header: the same key and request
    within 24 hours get the first answer again. A refusal that depends on state
    (a 403, a 409 or a 429) and a server error are not kept, so the same request
    with the key runs again.


    **Survey drafts.** With surveys:draft an assistant or a script creates
    surveys as drafts, copies any survey into a draft and edits the ones never
    published; a person publishes them in Usertick. With surveys:archive it
    archives surveys and restores archived ones as drafts.


    **Contacts and email.** With contacts:read and contacts:write a script
    manages contacts, lists and their members, and erases a contact with every
    response of the person (POST /contacts/{contactId}/erase, with
    responses:delete). With email:read it reads the survey email sends; sending
    stays in Usertick.


    **Dashboards and workflows.** With dashboards:draft an assistant or a script
    creates dashboards as drafts and edits their drafts; with workflows:draft it
    creates workflows switched off and edits their drafts. A person publishes
    either one in Usertick. dashboards:read and workflows:read list and read
    them.


    **Exports.** With exports:create (and responses:read) a script starts CSV or
    Excel exports of a survey's Results or of a dashboard, the files the Export
    menu makes, and downloads them for 24 hours. Each file counts as one of the
    plan's exports a month.


    **Support tickets.** With support:read and support:write an app or an AI
    assistant opens support tickets for the member it signed in as, lists that
    member's tickets and replies on them. A ticket belongs to a person, so an
    API key can't carry these scopes. Support tickets come with the paid plans.


    **Versioning.** Within /v1 changes are additive only: new endpoints, new
    optional parameters, new fields (ignore fields you do not know). Anything
    that will go away is announced at least six months ahead with Deprecation
    and Sunset headers on its answers.


    **Webhooks.** Every delivery is { id, type, createdAt, data }, signed per
    Standard Webhooks (see webhooks). data is the Response resource, with change
    on response.status_changed and response.classification_corrected; on
    theme.spiking it is the spike.


    Every answer carries X-Request-Id.
  contact:
    name: Usertick support
    url: https://usertick.com/support
servers:
  - url: https://app.usertick.com/api/public/v1
    description: Production
security:
  - bearerAuth: []
  - apiKeyHeader: []
tags:
  - name: Account
  - name: Responses
  - name: Surveys
  - name: Metrics
  - name: Exports
  - name: Contacts
  - name: Email
  - name: Dashboards
  - name: Workflows
  - name: Support
  - name: Webhooks
paths:
  /surveys/{surveyId}/draft:
    patch:
      tags:
        - Surveys
      summary: Edit a survey draft
      description: >-
        Edits a survey that was never published: 1 to 50 operations
        (add_question with after, update_question that changes only the fields
        sent, remove_question, move_question, set_survey, set_targeting),
        applied in order and saved together or not at all. Nothing goes live: a
        person publishes the draft in Usertick (editorUrl). The questions are
        checked the way a dashboard save checks them, each error naming its
        field, and the plan's limits apply as in the dashboard; no Usertick AI
        credits are used. Send expectedDraftVersion from the last read: a draft
        that changed since is 409 PUB-008-004 (read it again and redo the edit).
        While the survey is open in the Usertick editor the edit is 409
        PUB-008-003 (ask the person to close it). A live, paused or archived
        survey is 409 PUB-008-005: its changes are made in the dashboard.
        Removing a question leaves a rule that jumped to it without a
        destination, as the editor does. Answers with the draft.


        Scopes: surveys:draft, surveys:read.
      operationId: editSurveyDraft
      parameters:
        - name: surveyId
          in: path
          description: A survey id.
          required: true
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SurveyDraftEditBody'
      responses:
        '200':
          description: The draft after the edit.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
            X-RateLimit-Org-Limit:
              $ref: '#/components/headers/XRateLimitOrgLimit'
            X-RateLimit-Org-Remaining:
              $ref: '#/components/headers/XRateLimitOrgRemaining'
            X-RateLimit-Org-Reset:
              $ref: '#/components/headers/XRateLimitOrgReset'
            X-RateLimit-Window:
              $ref: '#/components/headers/XRateLimitWindow'
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyDraft'
        '400':
          description: >-
            The request isn't valid. Codes: GEN-000-003, PUB-001-004,
            PUB-001-006, PUB-008-001, PUB-008-002, PUB-008-006, PUB-008-009,
            PUB-008-010, SRV-006-002, SRV-006-003, SRV-006-004, SRV-006-009,
            SRV-006-010, SRV-006-011, SRV-006-012, SRV-006-015, QST-001-010,
            QST-001-011, QST-001-012, QST-001-013, PUB-008-007, SRV-001-020,
            SRV-002-001, SRV-002-002, SRV-002-003, SRV-002-010, SRV-002-012,
            SRV-002-013, SRV-002-014, SRV-002-015, SRV-002-022, SRV-002-023,
            SRV-002-024, SRV-002-025, SRV-002-029, SRV-002-030, SRV-002-033,
            SRV-002-034, PUB-002-001.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GEN-000-003:
                  $ref: '#/components/examples/GEN-000-003'
                PUB-001-004:
                  $ref: '#/components/examples/PUB-001-004'
                PUB-001-006:
                  $ref: '#/components/examples/PUB-001-006'
                PUB-008-001:
                  $ref: '#/components/examples/PUB-008-001'
                PUB-008-002:
                  $ref: '#/components/examples/PUB-008-002'
                PUB-008-006:
                  $ref: '#/components/examples/PUB-008-006'
                PUB-008-009:
                  $ref: '#/components/examples/PUB-008-009'
                PUB-008-010:
                  $ref: '#/components/examples/PUB-008-010'
                SRV-006-002:
                  $ref: '#/components/examples/SRV-006-002'
                SRV-006-003:
                  $ref: '#/components/examples/SRV-006-003'
                SRV-006-004:
                  $ref: '#/components/examples/SRV-006-004'
                SRV-006-009:
                  $ref: '#/components/examples/SRV-006-009'
                SRV-006-010:
                  $ref: '#/components/examples/SRV-006-010'
                SRV-006-011:
                  $ref: '#/components/examples/SRV-006-011'
                SRV-006-012:
                  $ref: '#/components/examples/SRV-006-012'
                SRV-006-015:
                  $ref: '#/components/examples/SRV-006-015'
                QST-001-010:
                  $ref: '#/components/examples/QST-001-010'
                QST-001-011:
                  $ref: '#/components/examples/QST-001-011'
                QST-001-012:
                  $ref: '#/components/examples/QST-001-012'
                QST-001-013:
                  $ref: '#/components/examples/QST-001-013'
                PUB-008-007:
                  $ref: '#/components/examples/PUB-008-007'
                SRV-001-020:
                  $ref: '#/components/examples/SRV-001-020'
                SRV-002-001:
                  $ref: '#/components/examples/SRV-002-001'
                SRV-002-002:
                  $ref: '#/components/examples/SRV-002-002'
                SRV-002-003:
                  $ref: '#/components/examples/SRV-002-003'
                SRV-002-010:
                  $ref: '#/components/examples/SRV-002-010'
                SRV-002-012:
                  $ref: '#/components/examples/SRV-002-012'
                SRV-002-013:
                  $ref: '#/components/examples/SRV-002-013'
                SRV-002-014:
                  $ref: '#/components/examples/SRV-002-014'
                SRV-002-015:
                  $ref: '#/components/examples/SRV-002-015'
                SRV-002-022:
                  $ref: '#/components/examples/SRV-002-022'
                SRV-002-023:
                  $ref: '#/components/examples/SRV-002-023'
                SRV-002-024:
                  $ref: '#/components/examples/SRV-002-024'
                SRV-002-025:
                  $ref: '#/components/examples/SRV-002-025'
                SRV-002-029:
                  $ref: '#/components/examples/SRV-002-029'
                SRV-002-030:
                  $ref: '#/components/examples/SRV-002-030'
                SRV-002-033:
                  $ref: '#/components/examples/SRV-002-033'
                SRV-002-034:
                  $ref: '#/components/examples/SRV-002-034'
                PUB-002-001:
                  $ref: '#/components/examples/PUB-002-001'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            The request was refused. Codes: APK-004-004, APK-004-005,
            APK-004-008, APK-004-009, AUTHZ-001-002, PLN-001-003, PLN-001-015,
            SRV-002-027.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                APK-004-004:
                  $ref: '#/components/examples/APK-004-004'
                APK-004-005:
                  $ref: '#/components/examples/APK-004-005'
                APK-004-008:
                  $ref: '#/components/examples/APK-004-008'
                APK-004-009:
                  $ref: '#/components/examples/APK-004-009'
                AUTHZ-001-002:
                  $ref: '#/components/examples/AUTHZ-001-002'
                PLN-001-003:
                  $ref: '#/components/examples/PLN-001-003'
                PLN-001-015:
                  $ref: '#/components/examples/PLN-001-015'
                SRV-002-027:
                  $ref: '#/components/examples/SRV-002-027'
        '404':
          description: 'The resource couldn''t be found. Codes: APK-006-005.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                APK-006-005:
                  $ref: '#/components/examples/APK-006-005'
        '409':
          description: >-
            The request conflicts with the current state. Codes: PUB-008-003,
            PUB-008-004, PUB-008-005, PUB-002-002, PUB-002-003.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                PUB-008-003:
                  $ref: '#/components/examples/PUB-008-003'
                PUB-008-004:
                  $ref: '#/components/examples/PUB-008-004'
                PUB-008-005:
                  $ref: '#/components/examples/PUB-008-005'
                PUB-002-002:
                  $ref: '#/components/examples/PUB-002-002'
                PUB-002-003:
                  $ref: '#/components/examples/PUB-002-003'
        '413':
          $ref: '#/components/responses/PayloadTooLargeDraft'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      description: >-
        Any 1 to 255 printable ASCII characters, without a space at either end.
        The answer to the first request with a key is kept for 24 hours per
        credential: the same request again gets it back (Idempotent-Replayed:
        true), another request with the key is 409 PUB-002-002, and while the
        first still runs 409 PUB-002-003. A server error is not kept, and a
        request that never answered frees its key after 2 minutes: a retry with
        the key then runs again.
      required: false
      schema:
        type: string
        maxLength: 255
  schemas:
    SurveyDraftEditBody:
      type: object
      properties:
        expectedDraftVersion:
          type: integer
          description: 'The draftVersion the edit was made on: another is 409 PUB-008-004.'
        operations:
          type: array
          items:
            $ref: '#/components/schemas/DraftOperation'
          description: 1 to 50, applied in order, saved together or not at all.
          minItems: 1
          maxItems: 50
      required:
        - expectedDraftVersion
        - operations
      additionalProperties: false
      examples:
        - expectedDraftVersion: 7
          operations:
            - op: add_question
              question:
                ref: q3
                type: multiple_choice
                text: Which plan are you on?
                options:
                  - Free
                  - Pro
              after: null
            - op: update_question
              questionId: a0000000-0000-4000-8000-000000000005
              set:
                text: How likely are you to recommend Usertick to a friend?
            - op: set_targeting
              set:
                trigger:
                  type: scroll
                  percent: 50
    SurveyDraft:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        status:
          type: string
          enum:
            - draft
            - active
            - paused
            - archived
        channel:
          type: string
          enum:
            - website
            - link
            - email
        site:
          oneOf:
            - $ref: '#/components/schemas/SiteRef'
            - type: 'null'
        draftVersion:
          type: integer
          description: Send it back as expectedDraftVersion.
        editable:
          type: boolean
          description: 'True only for a survey in draft status: the API edits nothing else.'
        editorUrl:
          type: string
          description: >-
            The survey in the Usertick editor, where a person publishes it. Give
            it to the person.
          format: uri
        defaultLanguage:
          type: string
        languages:
          type: array
          items:
            type: string
        displayMode:
          type: string
          enum:
            - steps
            - all
            - chat
        position:
          type: string
        texts:
          type: object
          additionalProperties:
            description: >-
              A string in the survey's default language, or a map of language to
              text (languages the survey has). On an edit a string replaces the
              field and its translations; a map sets those languages and keeps
              the others, null removing one.
            oneOf:
              - type: string
              - type: object
                additionalProperties:
                  type:
                    - string
                    - 'null'
        targeting:
          $ref: '#/components/schemas/DraftTargeting'
        questions:
          type: array
          items:
            $ref: '#/components/schemas/DraftQuestion'
        publishChecks:
          type: array
          items:
            $ref: '#/components/schemas/PublishCheck'
          description: >-
            What publishing would refuse now: a report for the person who
            publishes. Nothing here blocks saving a draft.
        createdAt:
          type: string
          format: date-time
          examples:
            - '2026-09-30T10:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          examples:
            - '2026-09-30T10:00:00.000Z'
        aiGenerated:
          type: boolean
          description: >-
            True when Usertick AI wrote text in the survey's own fields; each
            question has its own. Read only.
        aiGeneratedAt:
          type:
            - string
            - 'null'
          description: >-
            When text Usertick AI wrote was first stored here; null when people
            wrote all of it.
          format: date-time
          examples:
            - '2026-09-30T10:00:00.000Z'
      required:
        - id
        - name
        - status
        - channel
        - site
        - draftVersion
        - editable
        - editorUrl
        - defaultLanguage
        - languages
        - displayMode
        - position
        - texts
        - targeting
        - questions
        - publishChecks
        - createdAt
        - updatedAt
        - aiGenerated
        - aiGeneratedAt
      additionalProperties: false
      examples:
        - id: 11111111-1111-4111-8111-111111111111
          name: Checkout NPS
          status: draft
          channel: website
          site:
            id: 22222222-2222-4222-8222-222222222222
            domain: shop.example.com
          draftVersion: 1
          editable: true
          editorUrl: >-
            https://app.usertick.com/surveys?edit=11111111-1111-4111-8111-111111111111&org=3c9e4e1a-5b7d-4f20-9a61-0c2d8e4f6a10
          defaultLanguage: en
          languages:
            - en
          displayMode: steps
          position: bottom-right
          texts: {}
          targeting:
            pages: null
            trigger:
              type: delay
              seconds: 5
            devices:
              - desktop
              - tablet
              - mobile
            frequency:
              type: until_response
              cooldownDays: 30
              maxDisplays: 0
              afterDismissDays: 0
            extraSettings: false
          questions:
            - id: a0000000-0000-4000-8000-000000000005
              ref: q1
              type: nps
              text: How likely are you to recommend Usertick?
              required: true
              lowLabel: Not likely
              highLabel: Very likely
              logic: []
              aiGenerated: false
              aiGeneratedAt: null
          publishChecks: []
          createdAt: '2026-11-03T10:00:00.000Z'
          updatedAt: '2026-11-03T10:00:00.000Z'
          aiGenerated: false
          aiGeneratedAt: null
    Error:
      type: object
      properties:
        statusCode:
          type: integer
          description: The HTTP status, again.
        success:
          type: boolean
          description: Always false.
        code:
          type: string
          description: >-
            What went wrong, stable across versions (see x-error-codes). For
            invalid fields, the first field's code.
          examples:
            - PUB-001-001
        message:
          type:
            - string
            - 'null'
          description: The code's message in English (US); null for a code without one.
        data:
          description: Extra context for some errors; null otherwise.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
          description: >-
            Every invalid field, in the order of the request's parameters. Only
            on a 400 about fields.
      required:
        - statusCode
        - success
        - code
        - message
        - data
      description: >-
        Every error answer. Success answers are the plain resource or list
        instead.
      additionalProperties: false
      examples:
        - statusCode: 400
          success: false
          code: PUB-001-001
          message: The limit must be between 1 and 100.
          data: null
          errors:
            - field: limit
              code: PUB-001-001
              message: The limit must be between 1 and 100.
            - field: sort
              code: PUB-001-005
              message: The sort order must be asc or desc.
    DraftOperation:
      description: One edit. Any other field is 400 PUB-008-001.
      oneOf:
        - type: object
          properties:
            op:
              type: string
              enum:
                - add_question
            question:
              $ref: '#/components/schemas/DraftQuestionInput'
            after:
              description: >-
                A question id or a ref of the same request: right after it; null
                for the first place; left out for the last.
              type:
                - string
                - 'null'
          required:
            - op
            - question
          additionalProperties: false
        - type: object
          properties:
            op:
              type: string
              enum:
                - update_question
            questionId:
              type: string
              description: >-
                A question id (GET /surveys/{surveyId}/draft) or a ref an
                earlier operation of the same request added.
            set:
              description: >-
                Only the fields sent change (no ref; type only as it is). A list
                sent replaces the whole list.
              type: object
          required:
            - op
            - questionId
            - set
          additionalProperties: false
        - type: object
          properties:
            op:
              type: string
              enum:
                - remove_question
            questionId:
              type: string
              description: >-
                A question id (GET /surveys/{surveyId}/draft) or a ref an
                earlier operation of the same request added.
          required:
            - op
            - questionId
          additionalProperties: false
        - type: object
          properties:
            op:
              type: string
              enum:
                - move_question
            questionId:
              type: string
              description: >-
                A question id (GET /surveys/{surveyId}/draft) or a ref an
                earlier operation of the same request added.
            after:
              description: >-
                A question id or a ref of the same request: right after it; null
                for the first place; left out for the last.
              type:
                - string
                - 'null'
          required:
            - op
            - questionId
          additionalProperties: false
        - type: object
          properties:
            op:
              type: string
              enum:
                - set_survey
            set:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                channel:
                  type: string
                  description: website (default) or link; email is 400 PUB-008-009.
                  enum:
                    - website
                    - link
                defaultLanguage:
                  type: string
                  description: A language the organization offers (default en).
                  examples:
                    - en
                languages:
                  type: array
                  items:
                    type: string
                  description: >-
                    Every language the survey is written in, within the plan;
                    the default language is always one.
                displayMode:
                  type: string
                  description: steps (default), all or chat.
                  enum:
                    - steps
                    - all
                    - chat
                position:
                  type: string
                  enum:
                    - bottom-right
                    - bottom-left
                    - top-right
                    - top-left
                    - center-modal
                texts:
                  type: object
                  description: >-
                    The widget's words by key (title, subtitle, submitButton,
                    prevButton, nextButton, startButton, closeButton,
                    successTitle, successMessage, errorMessage, requiredField,
                    redirectNote, minimizedText, launcherLabel); null removes
                    one.
                  additionalProperties:
                    description: >-
                      A string in the survey's default language, or a map of
                      language to text (languages the survey has). On an edit a
                      string replaces the field and its translations; a map sets
                      those languages and keeps the others, null removing one.
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties:
                          type:
                            - string
                            - 'null'
                      - type: 'null'
              required: []
              additionalProperties: false
          required:
            - op
            - set
          additionalProperties: false
        - type: object
          properties:
            op:
              type: string
              enum:
                - set_targeting
            set:
              $ref: '#/components/schemas/DraftTargetingInput'
          required:
            - op
            - set
          additionalProperties: false
    SiteRef:
      type: object
      properties:
        id:
          type: string
          format: uuid
        domain:
          type: string
      required:
        - id
        - domain
      additionalProperties: false
    DraftTargeting:
      type: object
      properties:
        pages:
          oneOf:
            - type: object
              properties:
                target:
                  type: string
                  enum:
                    - path
                    - url
                include:
                  type: array
                  items:
                    $ref: '#/components/schemas/DraftPageRule'
                exclude:
                  type: array
                  items:
                    $ref: '#/components/schemas/DraftPageRule'
              required:
                - target
                - include
                - exclude
              additionalProperties: false
            - type: 'null'
          description: Null for every page.
        trigger:
          oneOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - load
                    - delay
                    - scroll
                    - exit_intent
                    - time_on_site
                seconds:
                  type: integer
                  description: delay and time_on_site only; left out for the other types.
                percent:
                  type: integer
                  description: scroll only; left out for the other types.
              required:
                - type
              additionalProperties: false
            - type: 'null'
          description: Null for none, or for a trigger outside this subset (extraSettings).
        devices:
          type: array
          items:
            type: string
            enum:
              - desktop
              - tablet
              - mobile
        frequency:
          type: object
          properties:
            type:
              type: string
              enum:
                - once
                - until_response
                - cooldown
                - always
            cooldownDays:
              type: integer
            maxDisplays:
              type: integer
            afterDismissDays:
              type: integer
          required:
            - type
            - cooldownDays
            - maxDisplays
            - afterDismissDays
          additionalProperties: false
        extraSettings:
          type: boolean
          description: >-
            The survey holds targeting this subset doesn't show (an advanced
            trigger, audience rules); an edit keeps it unless it sets that part.
      required:
        - pages
        - trigger
        - devices
        - frequency
        - extraSettings
      additionalProperties: false
    DraftQuestion:
      type: object
      properties:
        id:
          type: string
          description: The question id.
        ref:
          type: string
          description: 'On a question this request added: your ref.'
        type:
          type: string
          description: >-
            File upload, screenshot and signature questions are added in the
            dashboard (400 PUB-008-006). A type never changes.
          enum:
            - welcome
            - nps
            - rating
            - ces
            - emoji
            - boolean
            - multiple_choice
            - dropdown
            - ranking
            - slider
            - text
            - contact
            - date
            - matrix
            - number
            - big_scale
            - ruler
            - dial
            - this_or_that
            - allocation
            - consent
            - cta
        text:
          description: >-
            The question (a message screen's heading). Required on a create. A
            string in the survey's default language, or a map of language to
            text (languages the survey has). On an edit a string replaces the
            field and its translations; a map sets those languages and keeps the
            others, null removing one.
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
        description:
          description: Words under the question.
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        required:
          type: boolean
          description: >-
            The editor's default for the type when left out (requiredByDefault).
            A message screen and a call to action can't be required.
        title:
          description: 'welcome: the heading.'
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        body:
          description: 'welcome, cta: one paragraph.'
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        buttonText:
          description: welcome, cta.
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        buttonUrl:
          type:
            - string
            - 'null'
          description: 'cta: the link (https); publishing needs one.'
          maxLength: 2048
        options:
          type: array
          items:
            description: >-
              A string in the survey's default language, or a map of language to
              text (languages the survey has). On an edit a string replaces the
              field and its translations; a map sets those languages and keeps
              the others, null removing one.
            oneOf:
              - type: string
              - type: object
                additionalProperties:
                  type:
                    - string
                    - 'null'
          description: >-
            multiple_choice, dropdown, ranking, allocation. Replaces the list;
            an option whose words stay keeps its value.
          maxItems: 250
        multiple:
          type: boolean
          description: 'multiple_choice, dropdown, matrix: more than one answer.'
        allowOther:
          type: boolean
          description: 'multiple_choice, dropdown: an Other answer.'
        faces:
          oneOf:
            - type: array
              items:
                type: object
                properties:
                  emoji:
                    type: string
                    maxLength: 16
                  label:
                    description: >-
                      A string in the survey's default language, or a map of
                      language to text (languages the survey has). On an edit a
                      string replaces the field and its translations; a map sets
                      those languages and keeps the others, null removing one.
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties:
                          type:
                            - string
                            - 'null'
                      - type: 'null'
                required:
                  - emoji
                additionalProperties: false
              maxItems: 7
            - type: 'null'
          description: >-
            emoji, dial: worst to best. On a dial without lowLabel and highLabel
            the first and last faces' words are the ends; an emoji scale shows
            no ends.
        rows:
          type: array
          items:
            description: >-
              A string in the survey's default language, or a map of language to
              text (languages the survey has). On an edit a string replaces the
              field and its translations; a map sets those languages and keeps
              the others, null removing one.
            oneOf:
              - type: string
              - type: object
                additionalProperties:
                  type:
                    - string
                    - 'null'
          description: 'matrix: the statements.'
          maxItems: 50
        columns:
          type: array
          items:
            description: >-
              A string in the survey's default language, or a map of language to
              text (languages the survey has). On an edit a string replaces the
              field and its translations; a map sets those languages and keeps
              the others, null removing one.
            oneOf:
              - type: string
              - type: object
                additionalProperties:
                  type:
                    - string
                    - 'null'
          description: 'matrix: the answers.'
          maxItems: 20
        pairs:
          type: array
          items:
            type: object
            properties:
              a:
                description: >-
                  A string in the survey's default language, or a map of
                  language to text (languages the survey has). On an edit a
                  string replaces the field and its translations; a map sets
                  those languages and keeps the others, null removing one.
                oneOf:
                  - type: string
                  - type: object
                    additionalProperties:
                      type:
                        - string
                        - 'null'
              b:
                description: >-
                  A string in the survey's default language, or a map of
                  language to text (languages the survey has). On an edit a
                  string replaces the field and its translations; a map sets
                  those languages and keeps the others, null removing one.
                oneOf:
                  - type: string
                  - type: object
                    additionalProperties:
                      type:
                        - string
                        - 'null'
            required:
              - a
              - b
            additionalProperties: false
          description: this_or_that.
          maxItems: 50
        points:
          type:
            - integer
            - 'null'
          description: 'rating: how many points (2 to 10, default 5).'
          minimum: 2
          maximum: 10
        min:
          type:
            - number
            - 'null'
          description: slider, big_scale, ruler, number.
        max:
          type:
            - number
            - 'null'
          description: slider, big_scale, ruler, number.
        step:
          type:
            - number
            - 'null'
          description: slider, ruler, number; allocation 1 to 100.
        lowLabel:
          description: 'The low end: nps, rating, ces, dial, slider, big_scale, ruler.'
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        highLabel:
          description: The high end.
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        placeholder:
          description: text, number, dropdown.
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        dateMode:
          type: string
          description: date.
          enum:
            - date
            - datetime-local
            - time
        contactFields:
          type: array
          items:
            type: string
            enum:
              - name
              - email
              - phone
              - company
              - message
          description: >-
            contact (default name and email). Required through the email field,
            else the first.
          maxItems: 5
        yesLabel:
          description: boolean.
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        noLabel:
          description: boolean.
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        checkboxLabel:
          description: 'consent: the words beside the box.'
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        logic:
          type: array
          items:
            type: object
            properties:
              op:
                type: string
                enum:
                  - equals
                  - not_equals
                  - contains
                  - not_contains
                  - gt
                  - gte
                  - lt
                  - lte
                  - answered
                  - not_answered
              answer:
                type:
                  - string
                  - number
                  - boolean
              then:
                oneOf:
                  - type: string
                    enum:
                      - end
                  - type: object
                    properties:
                      goto:
                        type: string
                        description: A question id.
                    required:
                      - goto
                    additionalProperties: false
                  - type: 'null'
                description: >-
                  Null for a rule with no destination yet (publishing asks for
                  one).
            required:
              - op
              - then
            additionalProperties: false
          description: Not on a message screen.
        extraSettings:
          type: boolean
          description: >-
            Only when true: the question holds settings this shape doesn't show
            (a picture, a timer, a page); an edit keeps them.
        aiGenerated:
          type: boolean
          description: >-
            True when Usertick AI wrote text in this question, in any of its
            languages: a draft from Create with AI, a generated or suggested
            question, suggested options or labels, a rewrite or a translation.
            The mark records where the text came from, so it stays true after a
            person edits the text. Read only: an edit never sends it.
        aiGeneratedAt:
          type:
            - string
            - 'null'
          description: >-
            When text Usertick AI wrote was first stored here; null when people
            wrote all of it.
          format: date-time
          examples:
            - '2026-09-30T10:00:00.000Z'
      required:
        - id
        - type
        - text
        - required
        - aiGenerated
        - aiGeneratedAt
      description: >-
        A question in the typed shape: the common fields and the type's own that
        it holds.
      additionalProperties: false
    PublishCheck:
      type: object
      properties:
        code:
          type: string
          description: The code publishing answers with.
        message:
          type:
            - string
            - 'null'
      required:
        - code
        - message
      additionalProperties: false
    FieldError:
      type: object
      properties:
        field:
          type: string
          description: >-
            The query parameter, or the body property (camelCase, dotted when
            nested).
        code:
          type: string
        message:
          type:
            - string
            - 'null'
      required:
        - field
        - code
        - message
      additionalProperties: false
    DraftQuestionInput:
      type: object
      properties:
        ref:
          type: string
          description: >-
            Your name for the question within the request (1 to 64 characters,
            not a UUID): logic jumps and after name it. Create only.
          maxLength: 64
        type:
          type: string
          description: >-
            File upload, screenshot and signature questions are added in the
            dashboard (400 PUB-008-006). A type never changes.
          enum:
            - welcome
            - nps
            - rating
            - ces
            - emoji
            - boolean
            - multiple_choice
            - dropdown
            - ranking
            - slider
            - text
            - contact
            - date
            - matrix
            - number
            - big_scale
            - ruler
            - dial
            - this_or_that
            - allocation
            - consent
            - cta
        text:
          description: >-
            The question (a message screen's heading). Required on a create. A
            string in the survey's default language, or a map of language to
            text (languages the survey has). On an edit a string replaces the
            field and its translations; a map sets those languages and keeps the
            others, null removing one.
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
        description:
          description: Words under the question.
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        required:
          type: boolean
          description: >-
            The editor's default for the type when left out (requiredByDefault).
            A message screen and a call to action can't be required.
        logic:
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/LogicRuleInput'
              maxItems: 50
            - type: 'null'
          description: >-
            Replaces the question's rules; null or [] removes them. Not on a
            message screen.
        title:
          description: 'welcome: the heading.'
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        body:
          description: 'welcome, cta: one paragraph.'
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        buttonText:
          description: welcome, cta.
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        buttonUrl:
          type:
            - string
            - 'null'
          description: 'cta: the link (https); publishing needs one.'
          maxLength: 2048
        options:
          type: array
          items:
            description: >-
              A string in the survey's default language, or a map of language to
              text (languages the survey has). On an edit a string replaces the
              field and its translations; a map sets those languages and keeps
              the others, null removing one.
            oneOf:
              - type: string
              - type: object
                additionalProperties:
                  type:
                    - string
                    - 'null'
          description: >-
            multiple_choice, dropdown, ranking, allocation. Replaces the list;
            an option whose words stay keeps its value.
          maxItems: 250
        multiple:
          type: boolean
          description: 'multiple_choice, dropdown, matrix: more than one answer.'
        allowOther:
          type: boolean
          description: 'multiple_choice, dropdown: an Other answer.'
        faces:
          oneOf:
            - type: array
              items:
                type: object
                properties:
                  emoji:
                    type: string
                    maxLength: 16
                  label:
                    description: >-
                      A string in the survey's default language, or a map of
                      language to text (languages the survey has). On an edit a
                      string replaces the field and its translations; a map sets
                      those languages and keeps the others, null removing one.
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties:
                          type:
                            - string
                            - 'null'
                      - type: 'null'
                required:
                  - emoji
                additionalProperties: false
              maxItems: 7
            - type: 'null'
          description: >-
            emoji, dial: worst to best. On a dial without lowLabel and highLabel
            the first and last faces' words are the ends; an emoji scale shows
            no ends.
        rows:
          type: array
          items:
            description: >-
              A string in the survey's default language, or a map of language to
              text (languages the survey has). On an edit a string replaces the
              field and its translations; a map sets those languages and keeps
              the others, null removing one.
            oneOf:
              - type: string
              - type: object
                additionalProperties:
                  type:
                    - string
                    - 'null'
          description: 'matrix: the statements.'
          maxItems: 50
        columns:
          type: array
          items:
            description: >-
              A string in the survey's default language, or a map of language to
              text (languages the survey has). On an edit a string replaces the
              field and its translations; a map sets those languages and keeps
              the others, null removing one.
            oneOf:
              - type: string
              - type: object
                additionalProperties:
                  type:
                    - string
                    - 'null'
          description: 'matrix: the answers.'
          maxItems: 20
        pairs:
          type: array
          items:
            type: object
            properties:
              a:
                description: >-
                  A string in the survey's default language, or a map of
                  language to text (languages the survey has). On an edit a
                  string replaces the field and its translations; a map sets
                  those languages and keeps the others, null removing one.
                oneOf:
                  - type: string
                  - type: object
                    additionalProperties:
                      type:
                        - string
                        - 'null'
              b:
                description: >-
                  A string in the survey's default language, or a map of
                  language to text (languages the survey has). On an edit a
                  string replaces the field and its translations; a map sets
                  those languages and keeps the others, null removing one.
                oneOf:
                  - type: string
                  - type: object
                    additionalProperties:
                      type:
                        - string
                        - 'null'
            required:
              - a
              - b
            additionalProperties: false
          description: this_or_that.
          maxItems: 50
        points:
          type:
            - integer
            - 'null'
          description: 'rating: how many points (2 to 10, default 5).'
          minimum: 2
          maximum: 10
        min:
          type:
            - number
            - 'null'
          description: slider, big_scale, ruler, number.
        max:
          type:
            - number
            - 'null'
          description: slider, big_scale, ruler, number.
        step:
          type:
            - number
            - 'null'
          description: slider, ruler, number; allocation 1 to 100.
        lowLabel:
          description: 'The low end: nps, rating, ces, dial, slider, big_scale, ruler.'
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        highLabel:
          description: The high end.
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        placeholder:
          description: text, number, dropdown.
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        dateMode:
          type: string
          description: date.
          enum:
            - date
            - datetime-local
            - time
        contactFields:
          type: array
          items:
            type: string
            enum:
              - name
              - email
              - phone
              - company
              - message
          description: >-
            contact (default name and email). Required through the email field,
            else the first.
          maxItems: 5
        yesLabel:
          description: boolean.
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        noLabel:
          description: boolean.
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
        checkboxLabel:
          description: 'consent: the words beside the box.'
          oneOf:
            - type: string
            - type: object
              additionalProperties:
                type:
                  - string
                  - 'null'
            - type: 'null'
      required:
        - type
        - text
      description: >-
        A question in the typed shape. Each type takes the common fields and its
        own (GET /surveys/capabilities); any other field is 400 PUB-008-001.
      additionalProperties: false
      examples:
        - ref: q1
          type: nps
          text: How likely are you to recommend Usertick?
          lowLabel: Not likely
          highLabel: Very likely
          logic:
            - op: lte
              answer: '6'
              then:
                goto: q2
        - ref: q2
          type: text
          text: What went wrong?
          placeholder: Tell us more
    DraftTargetingInput:
      type: object
      properties:
        pages:
          oneOf:
            - type: object
              properties:
                target:
                  type: string
                  description: >-
                    What every rule tests: the path, or the url with its query
                    and hash.
                  enum:
                    - path
                    - url
                include:
                  type: array
                  items:
                    type: object
                    properties:
                      op:
                        type: string
                        enum:
                          - contains
                          - equals
                          - starts_with
                          - ends_with
                          - regex
                      value:
                        type: string
                        minLength: 1
                        maxLength: 500
                      target:
                        type: string
                        description: >-
                          The same as pages.target; rules that name two are
                          refused.
                        enum:
                          - path
                          - url
                    required:
                      - op
                      - value
                    additionalProperties: false
                  maxItems: 50
                exclude:
                  type: array
                  items:
                    $ref: '#/components/schemas/DraftPageRule'
                  maxItems: 50
              required: []
              additionalProperties: false
            - type: 'null'
          description: >-
            website: the pages to show on and to leave out; null shows it on
            every page. Replaces the page rules.
        trigger:
          oneOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - load
                    - delay
                    - scroll
                    - exit_intent
                    - time_on_site
                seconds:
                  type: integer
                  description: >-
                    delay 0 to 60 (default 10), time_on_site 10 to 1800 (default
                    60).
                percent:
                  type: integer
                  description: scroll 10 to 100 (default 50).
              required:
                - type
              additionalProperties: false
            - type: 'null'
          description: >-
            website: the one trigger; null leaves none (publishing asks for
            one).
        devices:
          type: array
          items:
            type: string
            enum:
              - desktop
              - tablet
              - mobile
          description: The devices it shows on.
          minItems: 1
        frequency:
          type: object
          properties:
            type:
              type: string
              enum:
                - once
                - until_response
                - cooldown
                - always
            cooldownDays:
              type: integer
              minimum: 0
              maximum: 3650
            maxDisplays:
              type: integer
              minimum: 0
              maximum: 1000
            afterDismissDays:
              type: integer
              minimum: 0
              maximum: 3650
          required: []
          description: >-
            website: how often a visitor sees it, merged into what the survey
            has.
          additionalProperties: false
      required: []
      description: >-
        The targeting every plan runs. Only the parts sent change; any other
        field is 400 PUB-008-001.
      additionalProperties: false
    DraftPageRule:
      type: object
      properties:
        op:
          type: string
          enum:
            - contains
            - equals
            - starts_with
            - ends_with
            - regex
        value:
          type: string
        target:
          type: string
          enum:
            - path
            - url
      required:
        - op
        - value
      additionalProperties: false
    LogicRuleInput:
      type: object
      properties:
        op:
          type: string
          description: >-
            One the question type offers (GET /surveys/capabilities,
            logicOperators).
          enum:
            - equals
            - not_equals
            - contains
            - not_contains
            - gt
            - gte
            - lt
            - lte
            - answered
            - not_answered
        answer:
          description: >-
            What the answer is compared with, as text or JSON: an option's or a
            face's position counting from 1, or its words, a number, true or
            false, clicked or dismissed, a this-or-that side's words, or text.
            Not taken by answered and not_answered.
          type:
            - string
            - number
            - boolean
        then:
          description: 'end, or { "goto": a ref of the same request or a question id }.'
          oneOf:
            - type: string
              enum:
                - end
            - type: object
              properties:
                goto:
                  type: string
              required:
                - goto
              additionalProperties: false
      required:
        - op
        - then
      description: A logic rule. Logic runs in the steps and chat display modes.
      additionalProperties: false
  headers:
    XRequestId:
      description: >-
        This answer's id (req_ and 32 hex characters), also in the logs. Quote
        it to support.
      schema:
        type: string
    XRateLimitLimit:
      description: The credential's requests per minute.
      schema:
        type: integer
    XRateLimitRemaining:
      description: What is left of it now.
      schema:
        type: integer
    XRateLimitReset:
      description: >-
        Seconds until the credential's budget is full again (the bucket refills
        continuously).
      schema:
        type: integer
    XRateLimitOrgLimit:
      description: Every credential of the organization together, per minute.
      schema:
        type: integer
    XRateLimitOrgRemaining:
      description: What is left of the organization's budget.
      schema:
        type: integer
    XRateLimitOrgReset:
      description: Seconds until the organization's budget is full again.
      schema:
        type: integer
    XRateLimitWindow:
      description: >-
        The window both budgets count over: 60s, since they are requests per
        minute.
      schema:
        type: string
    IdempotentReplayed:
      description: >-
        true when this is the kept answer of an earlier request with the same
        Idempotency-Key.
      schema:
        type: string
    RetryAfter:
      description: >-
        Seconds to wait before trying again. On a 429 over a budget, the time
        the bucket takes to refill one request (1 second at 120 or 300 a
        minute); X-RateLimit-Reset says when the whole budget is back.
      schema:
        type: integer
  examples:
    GEN-000-003:
      summary: Some fields aren't valid. Check them and try again.
      value:
        statusCode: 400
        success: false
        code: GEN-000-003
        message: Some fields aren't valid. Check them and try again.
        data: null
    PUB-001-004:
      summary: This value isn't valid.
      value:
        statusCode: 400
        success: false
        code: PUB-001-004
        message: This value isn't valid.
        data: null
    PUB-001-006:
      summary: Send a JSON body that this endpoint accepts.
      value:
        statusCode: 400
        success: false
        code: PUB-001-006
        message: Send a JSON body that this endpoint accepts.
        data: null
    PUB-008-001:
      summary: >-
        This field isn't taken here. GET /surveys/capabilities lists the fields
        each question type takes, and the operations list theirs.
      value:
        statusCode: 400
        success: false
        code: PUB-008-001
        message: >-
          This field isn't taken here. GET /surveys/capabilities lists the
          fields each question type takes, and the operations list theirs.
        data: null
    PUB-008-002:
      summary: >-
        No question of this survey has this ref or ID. Use a ref from the same
        request or a question ID from GET /surveys/{surveyId}/draft.
      value:
        statusCode: 400
        success: false
        code: PUB-008-002
        message: >-
          No question of this survey has this ref or ID. Use a ref from the same
          request or a question ID from GET /surveys/{surveyId}/draft.
        data: null
    PUB-008-006:
      summary: >-
        This question type can't be created through the API, or the question's
        type can't change. File upload, screenshot and signature questions are
        added in the dashboard. To change a type, remove the question and add a
        new one.
      value:
        statusCode: 400
        success: false
        code: PUB-008-006
        message: >-
          This question type can't be created through the API, or the question's
          type can't change. File upload, screenshot and signature questions are
          added in the dashboard. To change a type, remove the question and add
          a new one.
        data: null
    PUB-008-009:
      summary: >-
        This channel isn't offered through the API. Use website or link. Email
        surveys are created in the Usertick dashboard.
      value:
        statusCode: 400
        success: false
        code: PUB-008-009
        message: >-
          This channel isn't offered through the API. Use website or link. Email
          surveys are created in the Usertick dashboard.
        data: null
    PUB-008-010:
      summary: >-
        This language isn't one the survey offers. Add it to languages first,
        using a language GET /surveys/capabilities lists.
      value:
        statusCode: 400
        success: false
        code: PUB-008-010
        message: >-
          This language isn't one the survey offers. Add it to languages first,
          using a language GET /surveys/capabilities lists.
        data: null
    SRV-006-002:
      summary: A logic rule uses an operator that isn't valid.
      value:
        statusCode: 400
        success: false
        code: SRV-006-002
        message: A logic rule uses an operator that isn't valid.
        data: null
    SRV-006-003:
      summary: A logic rule uses an action that isn't valid.
      value:
        statusCode: 400
        success: false
        code: SRV-006-003
        message: A logic rule uses an action that isn't valid.
        data: null
    SRV-006-004:
      summary: A logic rule isn't structured correctly.
      value:
        statusCode: 400
        success: false
        code: SRV-006-004
        message: A logic rule isn't structured correctly.
        data: null
    SRV-006-009:
      summary: A question has too many items or a setting outside its allowed range.
      value:
        statusCode: 400
        success: false
        code: SRV-006-009
        message: A question has too many items or a setting outside its allowed range.
        data: null
    SRV-006-010:
      summary: >-
        A question text isn't valid. Each text must be a string or a map of
        language tag to string.
      value:
        statusCode: 400
        success: false
        code: SRV-006-010
        message: >-
          A question text isn't valid. Each text must be a string or a map of
          language tag to string.
        data: null
    SRV-006-011:
      summary: >-
        A question setting has a key that starts with a capital letter or is
        spelled two ways. Use one spelling for each key.
      value:
        statusCode: 400
        success: false
        code: SRV-006-011
        message: >-
          A question setting has a key that starts with a capital letter or is
          spelled two ways. Use one spelling for each key.
        data: null
    SRV-006-012:
      summary: >-
        A question holds a number too large to store or text with invalid
        characters. Correct the value and save again.
      value:
        statusCode: 400
        success: false
        code: SRV-006-012
        message: >-
          A question holds a number too large to store or text with invalid
          characters. Correct the value and save again.
        data: null
    SRV-006-015:
      summary: >-
        A logic rule's text to match is longer than 500 characters. Shorten the
        text, then save again.
      value:
        statusCode: 400
        success: false
        code: SRV-006-015
        message: >-
          A logic rule's text to match is longer than 500 characters. Shorten
          the text, then save again.
        data: null
    QST-001-010:
      summary: Question label is too long.
      value:
        statusCode: 400
        success: false
        code: QST-001-010
        message: Question label is too long.
        data: null
    QST-001-011:
      summary: A question option or setting is too long.
      value:
        statusCode: 400
        success: false
        code: QST-001-011
        message: A question option or setting is too long.
        data: null
    QST-001-012:
      summary: Question settings are too large.
      value:
        statusCode: 400
        success: false
        code: QST-001-012
        message: Question settings are too large.
        data: null
    QST-001-013:
      summary: >-
        A question couldn't be saved because its ID is too long. Reload the page
        and try again.
      value:
        statusCode: 400
        success: false
        code: QST-001-013
        message: >-
          A question couldn't be saved because its ID is too long. Reload the
          page and try again.
        data: null
    PUB-008-007:
      summary: Send 1 to 50 operations in one edit.
      value:
        statusCode: 400
        success: false
        code: PUB-008-007
        message: Send 1 to 50 operations in one edit.
        data: null
    SRV-001-020:
      summary: A survey can have at most 200 questions.
      value:
        statusCode: 400
        success: false
        code: SRV-001-020
        message: A survey can have at most 200 questions.
        data: null
    SRV-002-001:
      summary: Survey name is required.
      value:
        statusCode: 400
        success: false
        code: SRV-002-001
        message: Survey name is required.
        data: null
    SRV-002-002:
      summary: Survey name can't be empty.
      value:
        statusCode: 400
        success: false
        code: SRV-002-002
        message: Survey name can't be empty.
        data: null
    SRV-002-003:
      summary: Survey name must be between 1 and 255 characters.
      value:
        statusCode: 400
        success: false
        code: SRV-002-003
        message: Survey name must be between 1 and 255 characters.
        data: null
    SRV-002-010:
      summary: A survey text is too long.
      value:
        statusCode: 400
        success: false
        code: SRV-002-010
        message: A survey text is too long.
        data: null
    SRV-002-012:
      summary: Survey settings are too large.
      value:
        statusCode: 400
        success: false
        code: SRV-002-012
        message: Survey settings are too large.
        data: null
    SRV-002-013:
      summary: The trigger settings aren't valid.
      value:
        statusCode: 400
        success: false
        code: SRV-002-013
        message: The trigger settings aren't valid.
        data: null
    SRV-002-014:
      summary: The page rules aren't valid.
      value:
        statusCode: 400
        success: false
        code: SRV-002-014
        message: The page rules aren't valid.
        data: null
    SRV-002-015:
      summary: The frequency settings aren't valid.
      value:
        statusCode: 400
        success: false
        code: SRV-002-015
        message: The frequency settings aren't valid.
        data: null
    SRV-002-022:
      summary: >-
        This survey has more languages than Usertick offers. To save it, remove
        languages.
      value:
        statusCode: 400
        success: false
        code: SRV-002-022
        message: >-
          This survey has more languages than Usertick offers. To save it,
          remove languages.
        data: null
    SRV-002-023:
      summary: >-
        A page, referrer or trigger pattern can't run safely in the browser.
        Simplify it and check its flags.
      value:
        statusCode: 400
        success: false
        code: SRV-002-023
        message: >-
          A page, referrer or trigger pattern can't run safely in the browser.
          Simplify it and check its flags.
        data: null
    SRV-002-024:
      summary: >-
        The widget position isn't recognized. Use bottom-right, bottom-left,
        top-right, top-left or center-modal.
      value:
        statusCode: 400
        success: false
        code: SRV-002-024
        message: >-
          The widget position isn't recognized. Use bottom-right, bottom-left,
          top-right, top-left or center-modal.
        data: null
    SRV-002-025:
      summary: The display mode isn't recognized. Use all, steps or chat.
      value:
        statusCode: 400
        success: false
        code: SRV-002-025
        message: The display mode isn't recognized. Use all, steps or chat.
        data: null
    SRV-002-029:
      summary: >-
        A survey setting has a key that starts with a capital letter or is
        spelled two ways. Use one spelling for each key.
      value:
        statusCode: 400
        success: false
        code: SRV-002-029
        message: >-
          A survey setting has a key that starts with a capital letter or is
          spelled two ways. Use one spelling for each key.
        data: null
    SRV-002-030:
      summary: >-
        A survey setting holds a number too large to store or text with invalid
        characters. Correct the value and try again.
      value:
        statusCode: 400
        success: false
        code: SRV-002-030
        message: >-
          A survey setting holds a number too large to store or text with
          invalid characters. Correct the value and try again.
        data: null
    SRV-002-033:
      summary: >-
        A survey text or language list isn't valid. Each text must be a string
        or a map of language tag to string, and each language must be a language
        tag.
      value:
        statusCode: 400
        success: false
        code: SRV-002-033
        message: >-
          A survey text or language list isn't valid. Each text must be a string
          or a map of language tag to string, and each language must be a
          language tag.
        data: null
    SRV-002-034:
      summary: >-
        The display settings aren't valid. Check the devices, the side button
        icon, the embed selector and the redirect address, then try again.
      value:
        statusCode: 400
        success: false
        code: SRV-002-034
        message: >-
          The display settings aren't valid. Check the devices, the side button
          icon, the embed selector and the redirect address, then try again.
        data: null
    PUB-002-001:
      summary: >-
        Send an Idempotency-Key of 1 to 255 printable ASCII characters, without
        a space at either end.
      value:
        statusCode: 400
        success: false
        code: PUB-002-001
        message: >-
          Send an Idempotency-Key of 1 to 255 printable ASCII characters,
          without a space at either end.
        data: null
    APK-004-004:
      summary: >-
        This API key or app doesn't have permission for this request. Grant it
        the required scope.
      value:
        statusCode: 403
        success: false
        code: APK-004-004
        message: >-
          This API key or app doesn't have permission for this request. Grant it
          the required scope.
        data: null
    APK-004-005:
      summary: >-
        Your plan doesn't include API keys. To use them, upgrade to Pro or
        higher.
      value:
        statusCode: 403
        success: false
        code: APK-004-005
        message: >-
          Your plan doesn't include API keys. To use them, upgrade to Pro or
          higher.
        data: null
    APK-004-008:
      summary: >-
        This organization's plan doesn't include apps that use the API, such as
        Zapier. To use them, contact Usertick sales to change the plan.
      value:
        statusCode: 403
        success: false
        code: APK-004-008
        message: >-
          This organization's plan doesn't include apps that use the API, such
          as Zapier. To use them, contact Usertick sales to change the plan.
        data: null
    APK-004-009:
      summary: >-
        This organization's plan doesn't include the MCP server. To use an AI
        assistant with Usertick, upgrade to Starter or higher.
      value:
        statusCode: 403
        success: false
        code: APK-004-009
        message: >-
          This organization's plan doesn't include the MCP server. To use an AI
          assistant with Usertick, upgrade to Starter or higher.
        data: null
    AUTHZ-001-002:
      summary: Your role doesn't have the required permission.
      value:
        statusCode: 403
        success: false
        code: AUTHZ-001-002
        message: Your role doesn't have the required permission.
        data: null
    PLN-001-003:
      summary: >-
        This survey has more questions than your plan allows. To save or publish
        it, remove questions or upgrade your plan.
      value:
        statusCode: 403
        success: false
        code: PLN-001-003
        message: >-
          This survey has more questions than your plan allows. To save or
          publish it, remove questions or upgrade your plan.
        data: null
    PLN-001-015:
      summary: >-
        This survey has more questions that collect a file, a screenshot or a
        signature than your plan allows. To save or publish it, remove one or
        upgrade to Starter, which has no such limit.
      value:
        statusCode: 403
        success: false
        code: PLN-001-015
        message: >-
          This survey has more questions that collect a file, a screenshot or a
          signature than your plan allows. To save or publish it, remove one or
          upgrade to Starter, which has no such limit.
        data: null
    SRV-002-027:
      summary: >-
        Your plan doesn't include this many languages in one survey. To add a
        language, remove another or upgrade your plan.
      value:
        statusCode: 403
        success: false
        code: SRV-002-027
        message: >-
          Your plan doesn't include this many languages in one survey. To add a
          language, remove another or upgrade your plan.
        data: null
    APK-006-005:
      summary: The survey couldn't be found.
      value:
        statusCode: 404
        success: false
        code: APK-006-005
        message: The survey couldn't be found.
        data: null
    PUB-008-003:
      summary: >-
        The survey is open in the Usertick editor, so the changes weren't saved.
        Ask the person to close the editor, then send the changes again.
      value:
        statusCode: 409
        success: false
        code: PUB-008-003
        message: >-
          The survey is open in the Usertick editor, so the changes weren't
          saved. Ask the person to close the editor, then send the changes
          again.
        data: null
    PUB-008-004:
      summary: >-
        The draft changed after it was read. Read it again with GET
        /surveys/{surveyId}/draft, then send the changes with the new
        draftVersion.
      value:
        statusCode: 409
        success: false
        code: PUB-008-004
        message: >-
          The draft changed after it was read. Read it again with GET
          /surveys/{surveyId}/draft, then send the changes with the new
          draftVersion.
        data: null
    PUB-008-005:
      summary: >-
        Only a survey that was never published can be edited through the API.
        Edit this survey in the Usertick dashboard.
      value:
        statusCode: 409
        success: false
        code: PUB-008-005
        message: >-
          Only a survey that was never published can be edited through the API.
          Edit this survey in the Usertick dashboard.
        data: null
    PUB-002-002:
      summary: >-
        This Idempotency-Key was used with a different request. Use a new key
        for a new request.
      value:
        statusCode: 409
        success: false
        code: PUB-002-002
        message: >-
          This Idempotency-Key was used with a different request. Use a new key
          for a new request.
        data: null
    PUB-002-003:
      summary: >-
        A request with this Idempotency-Key is still running. Try again in a
        moment.
      value:
        statusCode: 409
        success: false
        code: PUB-002-003
        message: >-
          A request with this Idempotency-Key is still running. Try again in a
          moment.
        data: null
    APK-004-001:
      summary: Send an API key or an access token in the Authorization header.
      value:
        statusCode: 401
        success: false
        code: APK-004-001
        message: Send an API key or an access token in the Authorization header.
        data: null
    APK-004-002:
      summary: >-
        The API key or access token is invalid, expired or revoked. Connect
        again with a valid one.
      value:
        statusCode: 401
        success: false
        code: APK-004-002
        message: >-
          The API key or access token is invalid, expired or revoked. Connect
          again with a valid one.
        data: null
    APK-004-007:
      summary: >-
        This credential is for another server. The MCP server takes only the
        access tokens an assistant gets when it signs in, and the REST API takes
        API keys and app tokens.
      value:
        statusCode: 401
        success: false
        code: APK-004-007
        message: >-
          This credential is for another server. The MCP server takes only the
          access tokens an assistant gets when it signs in, and the REST API
          takes API keys and app tokens.
        data: null
    GEN-000-413:
      summary: The request is too large. Send less data or a smaller file.
      value:
        statusCode: 413
        success: false
        code: GEN-000-413
        message: The request is too large. Send less data or a smaller file.
        data: null
    GEN-000-415:
      summary: >-
        The request body isn't JSON. Send it with Content-Type:
        application/json.
      value:
        statusCode: 415
        success: false
        code: GEN-000-415
        message: >-
          The request body isn't JSON. Send it with Content-Type:
          application/json.
        data: null
    APK-004-003:
      summary: This API key or app sent too many requests. Wait a minute and try again.
      value:
        statusCode: 429
        success: false
        code: APK-004-003
        message: >-
          This API key or app sent too many requests. Wait a minute and try
          again.
        data: null
    APK-004-006:
      summary: >-
        Your organization sent too many API requests. Wait a minute and try
        again.
      value:
        statusCode: 429
        success: false
        code: APK-004-006
        message: >-
          Your organization sent too many API requests. Wait a minute and try
          again.
        data: null
    GEN-429-001:
      summary: Too many requests were sent. Wait a minute and try again.
      value:
        statusCode: 429
        success: false
        code: GEN-429-001
        message: Too many requests were sent. Wait a minute and try again.
        data: null
  responses:
    Unauthorized:
      description: >-
        No credential, one that is invalid, expired or revoked, or a token an AI
        assistant got for the MCP server. Codes: APK-004-001, APK-004-002,
        APK-004-007.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            APK-004-001:
              $ref: '#/components/examples/APK-004-001'
            APK-004-002:
              $ref: '#/components/examples/APK-004-002'
            APK-004-007:
              $ref: '#/components/examples/APK-004-007'
    PayloadTooLargeDraft:
      description: 'The body is over 512 KB. Codes: GEN-000-413.'
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            GEN-000-413:
              $ref: '#/components/examples/GEN-000-413'
    UnsupportedMediaType:
      description: >-
        The body is not JSON: send it with Content-Type: application/json.
        Codes: GEN-000-415.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            GEN-000-415:
              $ref: '#/components/examples/GEN-000-415'
    TooManyRequests:
      description: >-
        Over the credential's or the organization's budget, or over the
        per-address limit that is checked before the credential (GEN-429-001,
        without X-RateLimit headers). Codes: APK-004-003, APK-004-006,
        GEN-429-001.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            APK-004-003:
              $ref: '#/components/examples/APK-004-003'
            APK-004-006:
              $ref: '#/components/examples/APK-004-006'
            GEN-429-001:
              $ref: '#/components/examples/GEN-429-001'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (utk_live_...) or an app's OAuth access token (uto_...).
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: The API key, for clients that cannot send Authorization.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.