> ## 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.

# Add a note

> Adds a note as the credential: an app's note is its member's, an API key's note carries the key's name.

Scopes: responses:write.



## OpenAPI

````yaml api-reference/openapi.json POST /responses/{responseId}/comments
openapi: 3.1.0
info:
  title: Usertick Public API
  version: 1.0.0
  description: >-
    The Usertick REST API v1: responses, surveys, metrics 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 Starter plans and up.


    **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.


    **Rate limits.** 120 requests a minute per credential and 600 per
    organization, as token buckets. 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. Over a budget
    is 429 with Retry-After. 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).


    **Idempotency.** Every POST takes an Idempotency-Key header: the same key
    and request within 24 hours get the first answer again.


    **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: Webhooks
paths:
  /responses/{responseId}/comments:
    post:
      tags:
        - Responses
      summary: Add a note
      description: >-
        Adds a note as the credential: an app's note is its member's, an API
        key's note carries the key's name.


        Scopes: responses:write.
      operationId: addComment
      parameters:
        - $ref: '#/components/parameters/ResponseId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentBody'
      responses:
        '201':
          description: The note.
          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'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '400':
          description: >-
            The request isn't valid. Codes: RSP-002-002, RSP-002-003,
            PUB-001-006, PUB-002-001.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                RSP-002-002:
                  $ref: '#/components/examples/RSP-002-002'
                RSP-002-003:
                  $ref: '#/components/examples/RSP-002-003'
                PUB-001-006:
                  $ref: '#/components/examples/PUB-001-006'
                PUB-002-001:
                  $ref: '#/components/examples/PUB-002-001'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'The resource couldn''t be found. Codes: RSP-002-007.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                RSP-002-007:
                  $ref: '#/components/examples/RSP-002-007'
        '409':
          description: >-
            The request conflicts with the current state. Codes: 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-002-002:
                  $ref: '#/components/examples/PUB-002-002'
                PUB-002-003:
                  $ref: '#/components/examples/PUB-002-003'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    ResponseId:
      name: responseId
      in: path
      description: A response id.
      required: true
      schema:
        type: string
        format: uuid
    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:
    CommentBody:
      type: object
      properties:
        body:
          type: string
          minLength: 1
          maxLength: 10000
      required:
        - body
      additionalProperties: false
      examples:
        - body: Fixed in 2.4.1.
    Comment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        responseId:
          type: string
        kind:
          type: string
          enum:
            - note
            - external
        body:
          type: string
          description: Markdown.
        author:
          $ref: '#/components/schemas/CommentAuthor'
        createdAt:
          type: string
          format: date-time
          examples:
            - '2026-09-30T10:00:00.000Z'
        editedAt:
          type:
            - string
            - 'null'
          format: date-time
          examples:
            - '2026-09-30T10:00:00.000Z'
      required:
        - id
        - responseId
        - kind
        - body
        - author
        - createdAt
        - editedAt
      additionalProperties: false
    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.
    CommentAuthor:
      type: object
      properties:
        type:
          type: string
          enum:
            - member
            - api_key
            - external
        id:
          type:
            - string
            - 'null'
          format: uuid
        name:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
      required:
        - type
        - id
        - name
        - email
      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
  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
    RetryAfter:
      description: Seconds to wait before trying again.
      schema:
        type: integer
  examples:
    RSP-002-002:
      summary: The note can't be empty.
      value:
        statusCode: 400
        success: false
        code: RSP-002-002
        message: The note can't be empty.
        data: null
    RSP-002-003:
      summary: The note is too long.
      value:
        statusCode: 400
        success: false
        code: RSP-002-003
        message: The note is too long.
        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-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
    RSP-002-007:
      summary: The response couldn't be found.
      value:
        statusCode: 404
        success: false
        code: RSP-002-007
        message: The response couldn't be found.
        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-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 or the MCP server. 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 or the MCP server. To use them,
          upgrade to Pro or higher.
        data: null
    APK-004-008:
      summary: >-
        Your plan doesn't include apps that use the API, such as Zapier. To use
        them, upgrade to Starter or higher.
      value:
        statusCode: 403
        success: false
        code: APK-004-008
        message: >-
          Your plan doesn't include apps that use the API, such as Zapier. To
          use them, 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
    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
    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, or one that is invalid, expired or revoked. Codes:
        APK-004-001, APK-004-002.
      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'
    Forbidden:
      description: >-
        The credential lacks a scope this endpoint needs, the plan does not
        include the API (API keys on Pro and up, apps such as Zapier on Starter
        and up), or an app's member lacks the permission. Codes: APK-004-004,
        APK-004-005, APK-004-008, AUTHZ-001-002.
      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'
            AUTHZ-001-002:
              $ref: '#/components/examples/AUTHZ-001-002'
    PayloadTooLarge:
      description: 'The body is over 64 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'
    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.