> ## 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. # Update a response > Changes the status, type, urgency or assignees (replaced as a whole) through the inbox's own commands, recorded in the audit log as made through the credential. Every field is checked before any is applied. Answers with the response, so it needs responses:read too. Scopes: responses:write, responses:read. ## OpenAPI ````yaml api-reference/openapi.json PATCH /responses/{responseId} 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}: patch: tags: - Responses summary: Update a response description: >- Changes the status, type, urgency or assignees (replaced as a whole) through the inbox's own commands, recorded in the audit log as made through the credential. Every field is checked before any is applied. Answers with the response, so it needs responses:read too. Scopes: responses:write, responses:read. operationId: updateResponse parameters: - $ref: '#/components/parameters/ResponseId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ResponseUpdate' responses: '200': description: The response after the change. 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/Response' '400': description: >- The request isn't valid. Codes: APK-006-007, RSP-002-001, RSP-002-013, RSP-002-014, PUB-003-003, PUB-003-005, PUB-001-006. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: APK-006-007: $ref: '#/components/examples/APK-006-007' RSP-002-001: $ref: '#/components/examples/RSP-002-001' RSP-002-013: $ref: '#/components/examples/RSP-002-013' RSP-002-014: $ref: '#/components/examples/RSP-002-014' PUB-003-003: $ref: '#/components/examples/PUB-003-003' PUB-003-005: $ref: '#/components/examples/PUB-003-005' PUB-001-006: $ref: '#/components/examples/PUB-001-006' '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' '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 schemas: ResponseUpdate: type: object properties: status: type: string enum: - open - planned - in_progress - resolved - archived type: type: string enum: - bug - idea - complaint - question - praise - none - auto urgency: type: string enum: - high - medium - low - auto assignees: type: array items: type: string format: uuid description: >- Member ids that replace the current assignees; [] unassigns everyone. At most 500. maxItems: 500 required: [] description: >- Send at least one field. auto drops a correction and follows the analysis again. additionalProperties: false examples: - status: in_progress assignees: - 66666666-6666-4666-8666-666666666666 Response: type: object properties: id: type: string description: The response's id (a UUID). format: uuid url: type: string description: The response in the Usertick inbox. format: uri survey: $ref: '#/components/schemas/SurveyRef' site: oneOf: - $ref: '#/components/schemas/SiteRef' - type: 'null' createdAt: type: string format: date-time examples: - '2026-09-30T10:00:00.000Z' description: When the response was received. updatedAt: type: string format: date-time examples: - '2026-09-30T10:00:00.000Z' description: >- The latest of: received, analyzed, and the last change a person or an integration made (status, type, urgency, assignees, notes, corrections). source: type: - string - 'null' description: widget, link, email or api. language: type: - string - 'null' country: type: - string - 'null' description: ISO 3166-1 alpha-2. pageUrl: type: - string - 'null' description: The page the response was sent from. device: oneOf: - $ref: '#/components/schemas/Device' - type: 'null' variant: type: - string - 'null' description: >- The ID of the survey variant the respondent saw (v_ followed by letters and digits); null when the respondent saw the survey without a variant. variantName: type: - string - 'null' description: >- The name of that variant, also for a variant the survey no longer has; null when variant is null or the variant has no name. contact: oneOf: - $ref: '#/components/schemas/ContactRef' - type: 'null' respondent: $ref: '#/components/schemas/Respondent' answers: type: array items: $ref: '#/components/schemas/Answer' description: >- Answered questions in survey order; answers to questions the survey no longer has come last. answerText: type: object description: Question id to the answer's display text. additionalProperties: type: string attachments: type: array items: $ref: '#/components/schemas/Attachment' status: type: string enum: - open - planned - in_progress - resolved - archived assignees: type: array items: $ref: '#/components/schemas/Assignee' ai: oneOf: - $ref: '#/components/schemas/Ai' - type: 'null' commentsCount: type: integer description: Notes on the timeline, deleted ones not counted. required: - id - url - survey - site - createdAt - updatedAt - source - language - country - pageUrl - device - variant - variantName - contact - respondent - answers - answerText - attachments - status - assignees - ai - commentsCount description: >- One response: what every response read returns and what every webhook delivery carries in data. additionalProperties: false examples: - id: 9b1c2d3e-4f50-4a61-8b72-93a4b5c6d7e8 url: https://app.usertick.com/inbox/9b1c2d3e-4f50-4a61-8b72-93a4b5c6d7e8 survey: id: 11111111-1111-4111-8111-111111111111 name: Checkout feedback site: id: 22222222-2222-4222-8222-222222222222 domain: shop.example.com createdAt: '2026-09-30T10:00:00.123Z' updatedAt: '2026-09-30T12:31:05.120Z' source: widget language: en country: US pageUrl: https://shop.example.com/checkout device: type: desktop browser: Chrome os: macOS variant: null variantName: null contact: id: 77777777-7777-4777-8777-777777777777 email: maya@example.com respondent: userId: user_8271 anonymousId: 5f0c7a2b-8d4e-4c1a-9e3f-2b6d8a0c4e1f verified: true email: maya@example.com emailSource: identify name: Maya Chen company: Example Inc. traits: company: Example Inc. plan: pro traitsVerified: false contactQuestion: null contact: id: 77777777-7777-4777-8777-777777777777 answers: - questionId: q_nps question: How likely are you to recommend us? type: nps value: 4 text: '4' - questionId: q_comment question: What went wrong? type: text value: Checkout rejects my card every time text: Checkout rejects my card every time answerText: q_nps: '4' q_comment: Checkout rejects my card every time attachments: [] status: in_progress assignees: - id: 66666666-6666-4666-8666-666666666666 name: Ana Ruiz email: ana@example.com ai: type: bug urgency: high theme: id: 44444444-4444-4444-8444-444444444444 name: Checkout errors category: id: 55555555-5555-4555-8555-555555555555 name: Payments sentiment: negative analyzedAt: '2026-09-30T10:00:07.250Z' corrected: false commentsCount: 2 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. SurveyRef: type: object properties: id: type: string format: uuid name: type: - string - 'null' description: >- The survey's name. Responses of a deleted survey are left out of every read and delivery, so it is null only when the survey is deleted while the response is being read. required: - id - name additionalProperties: false SiteRef: type: object properties: id: type: string format: uuid domain: type: string required: - id - domain additionalProperties: false Device: type: object properties: type: type: - string - 'null' enum: - desktop - tablet - mobile - null browser: type: - string - 'null' os: type: - string - 'null' required: - type - browser - os additionalProperties: false ContactRef: type: object properties: id: type: - string - 'null' format: uuid description: >- The Usertick contact the response is linked to; null when it is linked to none. email: type: - string - 'null' description: >- The linked contact's email, else the respondent's (respondent.email). format: email required: - id - email description: Who answered, when known; null when nothing names them. additionalProperties: false Respondent: type: object properties: userId: type: - string - 'null' description: >- The customer's own user id, as the site's widget sent it (Usertick.identify). anonymousId: type: - string - 'null' description: >- The browser's random visitor id; a new one after logout. Null when none came. verified: type: boolean description: >- A valid user hash, computed by the customer's server, came with the response. email: type: - string - 'null' description: >- The respondent's email, by precedence: the email campaign's contact, a verified identify email, the contact question (or an answer that is exactly an address), an unverified identify email. format: email emailSource: type: - string - 'null' description: Where email came from. enum: - identify - contact_question - campaign - null name: type: - string - 'null' description: The name identify sent. company: type: - string - 'null' description: The company identify sent. traits: type: object description: >- The other traits identify sent, a flat object of strings, numbers and booleans; empty without any. additionalProperties: type: - string - number - boolean traitsVerified: type: boolean description: The traits came with a verified user id. contactQuestion: type: - object - 'null' description: >- What the respondent typed into a contact question: the fields it asked for that have a value (name, email, phone, company, message). Null without one. additionalProperties: type: string contact: oneOf: - type: object properties: id: type: string format: uuid required: - id additionalProperties: false - type: 'null' description: The Usertick contact the response is linked to. required: - userId - anonymousId - verified - email - emailSource - name - company - traits - traitsVerified - contactQuestion - contact description: >- Who answered. Always present; a field is null when unknown. Never sent to the AI. additionalProperties: false Answer: type: object properties: questionId: type: string question: type: - string - 'null' description: Null for a question the survey no longer has. type: type: - string - 'null' value: description: >- The answer as sent: a number, a string, a boolean, an array or an object. text: type: string description: The answer as a person reads it. required: - questionId - question - type - value - text additionalProperties: false Attachment: type: object properties: id: type: string questionId: type: string name: type: string url: type: string description: >- GET it with a credential that has responses:read: the API answers 302 to a download link valid for 5 minutes. format: uri required: - id - questionId - name - url additionalProperties: false Assignee: type: object properties: id: type: string format: uuid description: The member id (GET /members). name: type: - string - 'null' email: type: - string - 'null' format: email required: - id - name - email additionalProperties: false Ai: type: object properties: type: type: - string - 'null' enum: - bug - idea - complaint - question - praise - null urgency: type: - string - 'null' enum: - high - medium - low - null theme: oneOf: - $ref: '#/components/schemas/TaxonomyRef' - type: 'null' category: oneOf: - $ref: '#/components/schemas/TaxonomyRef' - type: 'null' sentiment: type: - string - 'null' enum: - negative - neutral - positive - null analyzedAt: type: - string - 'null' format: date-time examples: - '2026-09-30T10:00:00.000Z' description: When the analysis ran; null when it is not known. corrected: type: boolean description: A person changed one of these values; it wins over the analysis. required: - type - urgency - theme - category - sentiment - analyzedAt - corrected description: >- The analysis. Null until analyzed, when the analysis was skipped or failed and nobody corrected it, and on every response.created delivery. 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 TaxonomyRef: type: object properties: id: type: string format: uuid name: type: string required: - id - name 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: APK-006-007: summary: 'Include at least one change: a status, a type, an urgency or assignees.' value: statusCode: 400 success: false code: APK-006-007 message: >- Include at least one change: a status, a type, an urgency or assignees. data: null RSP-002-001: summary: The response status isn't valid. value: statusCode: 400 success: false code: RSP-002-001 message: The response status isn't valid. data: null RSP-002-013: summary: The feedback type isn't valid. value: statusCode: 400 success: false code: RSP-002-013 message: The feedback type isn't valid. data: null RSP-002-014: summary: The urgency isn't valid. value: statusCode: 400 success: false code: RSP-002-014 message: The urgency isn't valid. data: null PUB-003-003: summary: Assign at most 500 people. value: statusCode: 400 success: false code: PUB-003-003 message: Assign at most 500 people. data: null PUB-003-005: summary: Every assignee must be a member of this organization. value: statusCode: 400 success: false code: PUB-003-005 message: Every assignee must be a member of this organization. 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 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 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.