> ## 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 dashboard draft

> Changes a dashboard's draft with 1 to 50 operations (add_card, update_card that changes only the fields sent, remove_card, set_board), applied in order and saved together or not at all. Allowed on a published board too: viewers keep the published board, and the answer says hasUnpublishedChanges. Nothing reaches the board's viewers: a person opens it in edit mode in Usertick (editorUrl) and selects Publish. The API never publishes, discards, deletes, pins or shares a board. The plan's dashboards and cards per dashboard 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-015-004 (read it again and redo the edit). While the board is open in edit mode in Usertick the edit is 409 PUB-015-003. A card id that names no card is 400 PUB-015-005. A board past the plan's cards per dashboard keeps saving while it doesn't grow. Recorded in the audit log as made through the credential.

Scopes: dashboards:draft, dashboards:read.



## OpenAPI

````yaml api-reference/openapi.json PATCH /dashboards/{dashboardId}/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:
  /dashboards/{dashboardId}/draft:
    patch:
      tags:
        - Dashboards
      summary: Edit a dashboard draft
      description: >-
        Changes a dashboard's draft with 1 to 50 operations (add_card,
        update_card that changes only the fields sent, remove_card, set_board),
        applied in order and saved together or not at all. Allowed on a
        published board too: viewers keep the published board, and the answer
        says hasUnpublishedChanges. Nothing reaches the board's viewers: a
        person opens it in edit mode in Usertick (editorUrl) and selects
        Publish. The API never publishes, discards, deletes, pins or shares a
        board. The plan's dashboards and cards per dashboard 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-015-004 (read
        it again and redo the edit). While the board is open in edit mode in
        Usertick the edit is 409 PUB-015-003. A card id that names no card is
        400 PUB-015-005. A board past the plan's cards per dashboard keeps
        saving while it doesn't grow. Recorded in the audit log as made through
        the credential.


        Scopes: dashboards:draft, dashboards:read.
      operationId: editDashboardDraft
      parameters:
        - name: dashboardId
          in: path
          description: A dashboard id.
          required: true
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DashboardDraftEdit'
      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/DashboardDraft'
        '400':
          description: >-
            The request isn't valid. Codes: GEN-000-003, PUB-001-004,
            PUB-001-006, PUB-015-002, PUB-015-006, PUB-015-008, DSH-002-004,
            DSH-002-006, DSH-002-007, DSH-002-008, DSH-002-001, DSH-002-002,
            DSH-002-003, PUB-015-005, PUB-015-007, 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-015-002:
                  $ref: '#/components/examples/PUB-015-002'
                PUB-015-006:
                  $ref: '#/components/examples/PUB-015-006'
                PUB-015-008:
                  $ref: '#/components/examples/PUB-015-008'
                DSH-002-004:
                  $ref: '#/components/examples/DSH-002-004'
                DSH-002-006:
                  $ref: '#/components/examples/DSH-002-006'
                DSH-002-007:
                  $ref: '#/components/examples/DSH-002-007'
                DSH-002-008:
                  $ref: '#/components/examples/DSH-002-008'
                DSH-002-001:
                  $ref: '#/components/examples/DSH-002-001'
                DSH-002-002:
                  $ref: '#/components/examples/DSH-002-002'
                DSH-002-003:
                  $ref: '#/components/examples/DSH-002-003'
                PUB-015-005:
                  $ref: '#/components/examples/PUB-015-005'
                PUB-015-007:
                  $ref: '#/components/examples/PUB-015-007'
                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, DSH-006-003, PLN-001-013,
            PLN-004-004.
          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'
                DSH-006-003:
                  $ref: '#/components/examples/DSH-006-003'
                PLN-001-013:
                  $ref: '#/components/examples/PLN-001-013'
                PLN-004-004:
                  $ref: '#/components/examples/PLN-004-004'
        '404':
          description: 'The resource couldn''t be found. Codes: PUB-015-001.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                PUB-015-001:
                  $ref: '#/components/examples/PUB-015-001'
        '409':
          description: >-
            The request conflicts with the current state. Codes: PUB-015-003,
            PUB-015-004, 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-015-003:
                  $ref: '#/components/examples/PUB-015-003'
                PUB-015-004:
                  $ref: '#/components/examples/PUB-015-004'
                PUB-002-002:
                  $ref: '#/components/examples/PUB-002-002'
                PUB-002-003:
                  $ref: '#/components/examples/PUB-002-003'
        '413':
          $ref: '#/components/responses/PayloadTooLargeDashboard'
        '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:
    DashboardDraftEdit:
      type: object
      properties:
        expectedDraftVersion:
          type: integer
          description: draftVersion from the last read. Missing is 400 PUB-001-004.
          minimum: 0
        operations:
          type: array
          items:
            $ref: '#/components/schemas/DashboardOperation'
          description: 1 to 50 changes, applied in order and saved together or not at all.
          minItems: 1
          maxItems: 50
      required:
        - expectedDraftVersion
        - operations
      additionalProperties: false
      examples:
        - expectedDraftVersion: 2
          operations:
            - op: add_card
              card:
                kind: themes
                title: Top themes
                surveyId: 11111111-1111-4111-8111-111111111111
            - op: update_card
              id: w_k3v9q2ab
              set:
                title: NPS this month
            - op: set_board
              name: Onboarding
    DashboardDraft:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        icon:
          type:
            - string
            - 'null'
        color:
          type:
            - string
            - 'null'
        visibility:
          type: string
          enum:
            - organization
            - private
        isDefault:
          type: boolean
        readOnlyByPlan:
          type: boolean
        hasUnpublishedChanges:
          type: boolean
          description: True while the draft holds changes viewers don't see yet.
        draftVersion:
          type: integer
          description: Send it back as expectedDraftVersion on the next edit.
        editable:
          type: boolean
        cards:
          type: array
          items:
            $ref: '#/components/schemas/DashboardCard'
          description: The draft's cards (the published ones while nothing waits).
        url:
          type: string
          format: uri
        editorUrl:
          type: string
          description: >-
            Opens the board in edit mode in Usertick, where a person reviews the
            draft and selects Publish.
          format: uri
        draftUpdatedAt:
          type:
            - string
            - 'null'
          format: date-time
          examples:
            - '2026-09-30T10:00:00.000Z'
        createdAt:
          type: string
          format: date-time
          examples:
            - '2026-09-30T10:00:00.000Z'
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
          examples:
            - '2026-09-30T10:00:00.000Z'
        aiGenerated:
          type: boolean
        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
        - description
        - icon
        - color
        - visibility
        - isDefault
        - readOnlyByPlan
        - hasUnpublishedChanges
        - draftVersion
        - editable
        - cards
        - url
        - editorUrl
        - draftUpdatedAt
        - createdAt
        - updatedAt
        - aiGenerated
        - aiGeneratedAt
      additionalProperties: false
      examples:
        - id: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa
          name: Onboarding health
          description: null
          icon: null
          color: null
          visibility: organization
          isDefault: false
          readOnlyByPlan: false
          hasUnpublishedChanges: true
          draftVersion: 2
          editable: true
          cards:
            - id: w_k3v9q2ab
              kind: big_number
              widgetType: big-number
              title: NPS
              surveyId: 11111111-1111-4111-8111-111111111111
              questionId: null
              metric: nps
              dimension: null
              granularity: null
              derived: null
              target: null
              when: null
              text: null
              position:
                x: 0
                'y': 0
              size:
                w: 3
                h: 2
              extraSettings: false
              aiGenerated: false
              surveyMissing: false
          url: >-
            https://app.usertick.com/analytics/dashboards/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa?org=3c9e4e1a-5b7d-4f20-9a61-0c2d8e4f6a10
          editorUrl: >-
            https://app.usertick.com/analytics/dashboards/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa?edit=1&org=3c9e4e1a-5b7d-4f20-9a61-0c2d8e4f6a10
          draftUpdatedAt: '2026-11-05T10:00:00.000Z'
          createdAt: '2026-11-05T10:00:00.000Z'
          updatedAt: null
          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.
    DashboardOperation:
      oneOf:
        - type: object
          properties:
            op:
              type: string
              enum:
                - add_card
            card:
              $ref: '#/components/schemas/DashboardCardInput'
          required:
            - op
            - card
          description: Adds a card.
          additionalProperties: false
        - type: object
          properties:
            op:
              type: string
              enum:
                - update_card
            id:
              type: string
            set:
              $ref: '#/components/schemas/DashboardCardChange'
          required:
            - op
            - id
            - set
          description: Changes the fields sent; every other setting stays.
          additionalProperties: false
        - type: object
          properties:
            op:
              type: string
              enum:
                - remove_card
            id:
              type: string
          required:
            - op
            - id
          description: >-
            Removes a card from the draft. Viewers keep it until a person
            publishes.
          additionalProperties: false
        - type: object
          properties:
            op:
              type: string
              enum:
                - set_board
            name:
              type: string
              minLength: 1
              maxLength: 255
            description:
              type:
                - string
                - 'null'
              description: null clears it.
              maxLength: 1000
            icon:
              type:
                - string
                - 'null'
              description: A tile icon key of the dashboard's icon set.
              maxLength: 40
            color:
              type:
                - string
                - 'null'
              description: A tile color key of the dashboard's palette.
              maxLength: 40
          required:
            - op
          description: >-
            Renames the board or changes its description or tile face; send at
            least one field.
          additionalProperties: false
      description: One change to the draft.
    DashboardCard:
      type: object
      properties:
        id:
          type: string
          description: The card id (update_card and remove_card name it).
        kind:
          type:
            - string
            - 'null'
          description: >-
            The card kind; null for a card only the dashboard makes (a
            countdown), which the API can remove but not change.
          enum:
            - question
            - big_number
            - breakdown
            - responses_over_time
            - recent_responses
            - derived_number
            - goal
            - compare
            - leaderboard
            - ai_insights
            - themes
            - comments
            - note
            - stat
            - score_distribution
            - survey_health
            - response_time
            - funnel
            - word_cloud
            - threshold
            - score_trend
            - weekday
            - variant_compare
            - null
        widgetType:
          type: string
          description: The card as the board stores it (big-number, line-chart, ...).
        title:
          type: string
        surveyId:
          type:
            - string
            - 'null'
          description: >-
            The survey the card reads (needsSurvey in GET
            /dashboards/capabilities says when).
          format: uuid
        questionId:
          type:
            - string
            - 'null'
          description: A question of that survey.
          maxLength: 64
        metric:
          type:
            - string
            - 'null'
          description: >-
            The measure: responses (the default) needs no survey; every other
            one does.
          enum:
            - responses
            - avg_score
            - nps
            - csat
            - ces
            - acceptance_rate
            - click_rate
            - null
        dimension:
          type:
            - string
            - 'null'
          description: 'breakdown: what it splits responses by (default country).'
          enum:
            - country
            - device
            - language
            - browser
            - page
            - null
        granularity:
          type:
            - string
            - 'null'
          description: 'responses_over_time and score_trend: the time bucket (default week).'
          enum:
            - day
            - week
            - month
            - null
        derived:
          type:
            - string
            - 'null'
          description: 'derived_number: the rate it shows (default completion).'
          enum:
            - nps
            - completion
            - null
        target:
          type:
            - number
            - 'null'
          description: >-
            goal: the number aimed at (default 100). threshold: the line
            (default 10).
          minimum: -1000000000
          maximum: 1000000000
        when:
          type:
            - string
            - 'null'
          description: 'threshold: the side of the line that is marked.'
          enum:
            - below
            - above
            - null
        text:
          type:
            - string
            - 'null'
          description: 'note: the text, up to 2,000 characters.'
          maxLength: 2000
        position:
          $ref: '#/components/schemas/CardPosition'
        size:
          $ref: '#/components/schemas/CardSize'
        extraSettings:
          type: boolean
          description: >-
            The card holds settings the typed shape doesn't show (several
            questions on one chart, its own filters); an edit keeps them.
        aiGenerated:
          type: boolean
          description: True when Usertick AI drafted the card.
        surveyMissing:
          type: boolean
          description: True when the survey the card reads is gone.
      required:
        - id
        - kind
        - widgetType
        - title
        - surveyId
        - questionId
        - metric
        - dimension
        - granularity
        - derived
        - target
        - when
        - text
        - position
        - size
        - extraSettings
        - aiGenerated
        - surveyMissing
      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
    DashboardCardInput:
      type: object
      properties:
        kind:
          type: string
          description: >-
            The card kind; GET /dashboards/capabilities lists the fields each
            takes. A field the kind doesn't take is 400 PUB-015-002.
          enum:
            - question
            - big_number
            - breakdown
            - responses_over_time
            - recent_responses
            - derived_number
            - goal
            - compare
            - leaderboard
            - ai_insights
            - themes
            - comments
            - note
            - stat
            - score_distribution
            - survey_health
            - response_time
            - funnel
            - word_cloud
            - threshold
            - score_trend
            - weekday
            - variant_compare
        title:
          type: string
          description: What the card is called, 1 to 120 characters.
          minLength: 1
          maxLength: 120
        surveyId:
          type:
            - string
            - 'null'
          description: >-
            The survey the card reads (needsSurvey in GET
            /dashboards/capabilities says when).
          format: uuid
        questionId:
          type:
            - string
            - 'null'
          description: A question of that survey.
          maxLength: 64
        metric:
          type:
            - string
            - 'null'
          description: >-
            The measure: responses (the default) needs no survey; every other
            one does.
          enum:
            - responses
            - avg_score
            - nps
            - csat
            - ces
            - acceptance_rate
            - click_rate
            - null
        dimension:
          type:
            - string
            - 'null'
          description: 'breakdown: what it splits responses by (default country).'
          enum:
            - country
            - device
            - language
            - browser
            - page
            - null
        granularity:
          type:
            - string
            - 'null'
          description: 'responses_over_time and score_trend: the time bucket (default week).'
          enum:
            - day
            - week
            - month
            - null
        derived:
          type:
            - string
            - 'null'
          description: 'derived_number: the rate it shows (default completion).'
          enum:
            - nps
            - completion
            - null
        target:
          type:
            - number
            - 'null'
          description: >-
            goal: the number aimed at (default 100). threshold: the line
            (default 10).
          minimum: -1000000000
          maximum: 1000000000
        when:
          type:
            - string
            - 'null'
          description: 'threshold: the side of the line that is marked.'
          enum:
            - below
            - above
            - null
        text:
          type:
            - string
            - 'null'
          description: 'note: the text, up to 2,000 characters.'
          maxLength: 2000
        position:
          oneOf:
            - $ref: '#/components/schemas/CardPosition'
            - type: 'null'
          description: >-
            Left out, the card goes below the lowest card, first fit, as the
            dashboard's templates place cards.
        size:
          oneOf:
            - $ref: '#/components/schemas/CardSize'
            - type: 'null'
          description: Left out, the kind's default size.
      required:
        - kind
        - title
      additionalProperties: false
      examples:
        - kind: big_number
          title: NPS
          surveyId: 11111111-1111-4111-8111-111111111111
          metric: nps
        - kind: breakdown
          title: Top countries
          dimension: country
        - kind: note
          title: Read me
          text: Numbers cover the last 30 days.
    DashboardCardChange:
      type: object
      properties:
        kind:
          type: string
          description: The card's own kind; another kind is 400 PUB-015-006.
          enum:
            - question
            - big_number
            - breakdown
            - responses_over_time
            - recent_responses
            - derived_number
            - goal
            - compare
            - leaderboard
            - ai_insights
            - themes
            - comments
            - note
            - stat
            - score_distribution
            - survey_health
            - response_time
            - funnel
            - word_cloud
            - threshold
            - score_trend
            - weekday
            - variant_compare
        title:
          type: string
          description: What the card is called, 1 to 120 characters.
          minLength: 1
          maxLength: 120
        surveyId:
          type:
            - string
            - 'null'
          description: >-
            The survey the card reads (needsSurvey in GET
            /dashboards/capabilities says when).
          format: uuid
        questionId:
          type:
            - string
            - 'null'
          description: A question of that survey.
          maxLength: 64
        metric:
          type:
            - string
            - 'null'
          description: >-
            The measure: responses (the default) needs no survey; every other
            one does.
          enum:
            - responses
            - avg_score
            - nps
            - csat
            - ces
            - acceptance_rate
            - click_rate
            - null
        dimension:
          type:
            - string
            - 'null'
          description: 'breakdown: what it splits responses by (default country).'
          enum:
            - country
            - device
            - language
            - browser
            - page
            - null
        granularity:
          type:
            - string
            - 'null'
          description: 'responses_over_time and score_trend: the time bucket (default week).'
          enum:
            - day
            - week
            - month
            - null
        derived:
          type:
            - string
            - 'null'
          description: 'derived_number: the rate it shows (default completion).'
          enum:
            - nps
            - completion
            - null
        target:
          type:
            - number
            - 'null'
          description: >-
            goal: the number aimed at (default 100). threshold: the line
            (default 10).
          minimum: -1000000000
          maximum: 1000000000
        when:
          type:
            - string
            - 'null'
          description: 'threshold: the side of the line that is marked.'
          enum:
            - below
            - above
            - null
        text:
          type:
            - string
            - 'null'
          description: 'note: the text, up to 2,000 characters.'
          maxLength: 2000
        position:
          $ref: '#/components/schemas/CardPosition'
        size:
          $ref: '#/components/schemas/CardSize'
      required: []
      description: >-
        The fields to change; every other setting of the card stays, its own
        filters included. null clears a field.
      additionalProperties: false
    CardPosition:
      type: object
      properties:
        x:
          type: integer
          description: The first of the 12 columns, 0 to 11.
          minimum: 0
          maximum: 11
        'y':
          type: integer
          description: The first row, 0 to 100,000.
          minimum: 0
          maximum: 100000
      required:
        - x
        - 'y'
      additionalProperties: false
    CardSize:
      type: object
      properties:
        w:
          type: integer
          description: >-
            Columns, 1 to 12, with x plus w at most 12, and at least the kind's
            minSize.
          minimum: 1
          maximum: 12
        h:
          type: integer
          description: Rows, 1 to 50, and at least the kind's minSize.
          minimum: 1
          maximum: 50
      required:
        - w
        - h
      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-015-002:
      summary: >-
        This field isn't taken here. GET /dashboards/capabilities lists the
        fields each card kind takes, and the operations list theirs.
      value:
        statusCode: 400
        success: false
        code: PUB-015-002
        message: >-
          This field isn't taken here. GET /dashboards/capabilities lists the
          fields each card kind takes, and the operations list theirs.
        data: null
    PUB-015-006:
      summary: >-
        This card kind can't be created through the API, or the card's kind
        can't change. GET /dashboards/capabilities lists the kinds. To change a
        kind, remove the card and add a new one.
      value:
        statusCode: 400
        success: false
        code: PUB-015-006
        message: >-
          This card kind can't be created through the API, or the card's kind
          can't change. GET /dashboards/capabilities lists the kinds. To change
          a kind, remove the card and add a new one.
        data: null
    PUB-015-008:
      summary: >-
        The survey or the question this card names can't be used: it isn't the
        organization's, the credential can't read it, or the question isn't in
        the survey.
      value:
        statusCode: 400
        success: false
        code: PUB-015-008
        message: >-
          The survey or the question this card names can't be used: it isn't the
          organization's, the credential can't read it, or the question isn't in
          the survey.
        data: null
    DSH-002-004:
      summary: Dashboard layout is too large.
      value:
        statusCode: 400
        success: false
        code: DSH-002-004
        message: Dashboard layout is too large.
        data: null
    DSH-002-006:
      summary: The dashboard icon or color isn't valid.
      value:
        statusCode: 400
        success: false
        code: DSH-002-006
        message: The dashboard icon or color isn't valid.
        data: null
    DSH-002-007:
      summary: >-
        A card title is longer than 120 characters. Shorten the title, then save
        again.
      value:
        statusCode: 400
        success: false
        code: DSH-002-007
        message: >-
          A card title is longer than 120 characters. Shorten the title, then
          save again.
        data: null
    DSH-002-008:
      summary: >-
        A note is longer than 2,000 characters. Shorten the note, then save
        again.
      value:
        statusCode: 400
        success: false
        code: DSH-002-008
        message: >-
          A note is longer than 2,000 characters. Shorten the note, then save
          again.
        data: null
    DSH-002-001:
      summary: Dashboard name is required.
      value:
        statusCode: 400
        success: false
        code: DSH-002-001
        message: Dashboard name is required.
        data: null
    DSH-002-002:
      summary: Dashboard name is too long.
      value:
        statusCode: 400
        success: false
        code: DSH-002-002
        message: Dashboard name is too long.
        data: null
    DSH-002-003:
      summary: Description is too long.
      value:
        statusCode: 400
        success: false
        code: DSH-002-003
        message: Description is too long.
        data: null
    PUB-015-005:
      summary: >-
        No card of this dashboard's draft has this ID. Use a card ID from GET
        /dashboards/{dashboardId}/draft.
      value:
        statusCode: 400
        success: false
        code: PUB-015-005
        message: >-
          No card of this dashboard's draft has this ID. Use a card ID from GET
          /dashboards/{dashboardId}/draft.
        data: null
    PUB-015-007:
      summary: Send 1 to 50 operations in one edit.
      value:
        statusCode: 400
        success: false
        code: PUB-015-007
        message: Send 1 to 50 operations in one edit.
        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
    DSH-006-003:
      summary: This dashboard is shared as view only. To make changes, copy it.
      value:
        statusCode: 403
        success: false
        code: DSH-006-003
        message: This dashboard is shared as view only. To make changes, copy it.
        data: null
    PLN-001-013:
      summary: >-
        This dashboard has as many cards as your plan allows. To add another,
        remove a card or upgrade to Starter, which has no card limit.
      value:
        statusCode: 403
        success: false
        code: PLN-001-013
        message: >-
          This dashboard has as many cards as your plan allows. To add another,
          remove a card or upgrade to Starter, which has no card limit.
        data: null
    PLN-004-004:
      summary: >-
        This dashboard is read-only because your organization has more
        dashboards than its plan allows. To edit it, delete a dashboard or
        upgrade.
      value:
        statusCode: 403
        success: false
        code: PLN-004-004
        message: >-
          This dashboard is read-only because your organization has more
          dashboards than its plan allows. To edit it, delete a dashboard or
          upgrade.
        data: null
    PUB-015-001:
      summary: The dashboard couldn't be found.
      value:
        statusCode: 404
        success: false
        code: PUB-015-001
        message: The dashboard couldn't be found.
        data: null
    PUB-015-003:
      summary: >-
        The dashboard is open in edit mode in Usertick, so the changes weren't
        saved. Ask the person to leave edit mode, then send the changes again.
      value:
        statusCode: 409
        success: false
        code: PUB-015-003
        message: >-
          The dashboard is open in edit mode in Usertick, so the changes weren't
          saved. Ask the person to leave edit mode, then send the changes again.
        data: null
    PUB-015-004:
      summary: >-
        The draft changed after it was read. Read it again with GET
        /dashboards/{dashboardId}/draft, then send the changes with the new
        draftVersion.
      value:
        statusCode: 409
        success: false
        code: PUB-015-004
        message: >-
          The draft changed after it was read. Read it again with GET
          /dashboards/{dashboardId}/draft, then send the changes with the new
          draftVersion.
        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'
    PayloadTooLargeDashboard:
      description: 'The body is over 256 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.