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

# Alias of GET /api/threads/{id}

> For an existing protected thread, send its x-widget-thread-token capability in addition to widget identity…

For an existing protected thread, send its `x-widget-thread-token` capability in addition to widget identity. Widget identity is verified when signing is configured; tokenless compatibility does not establish tenant ownership. See the authentication and recovery guide for credential and retry rules.

### Path parameters

**id** `string` *required*

Thread id (`thr_<uuid>`).

### Headers

**x-widget-thread-token** `string`

Capability required for an existing thread that has an issued token. Legacy capability-less threads are denied when STATESET\_THREAD\_TOKEN\_REQUIRED=true.

### Response

`object`

**thread** `Thread` *required*

Thread as serialized for clients: server-only fields (`state`, `accessToken`, `owner`, `restoredFromClientHistory`) are stripped.

**Thread**

**id** `string` *required*

`thr_<uuid>`.

**subject** `string` *required*

**title** `string`

**channel** `string` *required*

Defaults to `chat` on the API routes.

**meta** `object` *required*

**provider** `Provider` *required*

Allowed values: `'openai'`, `'anthropic'`, `'gemini'`.

**createdAt** `string (date-time)` *required*

**updatedAt** `string (date-time)` *required*

**messages** `Message[]` *required*

**Message**

**id** `string` *required*

`msg_<base36 timestamp>`.

**sender** `string` *required*

Allowed values: `'user'`, `'ai'`, `'agent'`.

**text** `string` *required*

**timestamp** `string (date-time)` *required*

**type** `MessageType`

Allowed values: `'text'`, `'tool_call'`, `'tool_result'`, `'card'`, `'buttons'`, `'form'`, `'product_cards'`, `'order_cards'`, `'citation'`, `'thinking'`.

**richContent** `RichContent`

Payload of a rich message (`card`, `buttons`, `form`, `product_cards`, `order_cards`); which keys are present depends on the message type. Mirrors `RichContent` in src/types/messages.ts minus client-only callbacks.

**attachments** `Attachment[]`

**toolCalls** `ToolCall[]`

**sources** `SourceCitation[]`

**suggestions** `string[]`

**thinking** `string`

**reaction** `MessageReaction`

Allowed values: `'up'`, `'down'`, `null`.

**feedbackComment** `string`

Maximum length: `500`.

**feedbackAt** `string (date-time)`

**authorName** `string`

Operator display name for native human replies.

**operatorEvent** `string`

Allowed values: `'joined'`, `'released'`, `'resolved'`.

**messages** `Message[]` *required*

**Message**

**id** `string` *required*

`msg_<base36 timestamp>`.

**sender** `string` *required*

Allowed values: `'user'`, `'ai'`, `'agent'`.

**text** `string` *required*

**timestamp** `string (date-time)` *required*

**type** `MessageType`

Allowed values: `'text'`, `'tool_call'`, `'tool_result'`, `'card'`, `'buttons'`, `'form'`, `'product_cards'`, `'order_cards'`, `'citation'`, `'thinking'`.

**richContent** `RichContent`

Payload of a rich message (`card`, `buttons`, `form`, `product_cards`, `order_cards`); which keys are present depends on the message type. Mirrors `RichContent` in src/types/messages.ts minus client-only callbacks.

**RichContent**

**image** `string`

**title** `string`

**description** `string`

**formId** `string`

**buttonStyle** `string`

Allowed values: `'default'`, `'pill'`.

**layout** `string`

Allowed values: `'scroll'`, `'stack'`.

**actions** `object[]`

**buttons** `object[]`

**fields** `object[]`

**submitLabel** `string`

**headline** `string`

**subhead** `string`

**products** `ProductCard[]`

**autoAction** `object`

**orders** `OrderCard[]`

**attachments** `Attachment[]`

**Attachment**

**id** `string`

**name** `string` *required*

**size** `integer` *required*

Maximum: `10485760`.

**type** `string` *required*

**dataUrl** `string`

`data:<mime>;base64,<payload>`.

**previewUrl** `string,null`

**url** `string`

Public URL of an already uploaded image (read for vision providers).

**toolCalls** `ToolCall[]`

**ToolCall**

**id** `string` *required*

**name** `string` *required*

**arguments** `object`

**result** `any`

**status** `string`

Allowed values: `'running'`, `'complete'`, `'error'`.

**sources** `SourceCitation[]`

**SourceCitation**

**id** `string` *required*

**title** `string` *required*

**url** `string` *required*

**snippet** `string`

Up to 220 characters of the document.

**suggestions** `string[]`

**thinking** `string`

**reaction** `MessageReaction`

Allowed values: `'up'`, `'down'`, `null`.

**feedbackComment** `string`

Maximum length: `500`.

**feedbackAt** `string (date-time)`

**authorName** `string`

Operator display name for native human replies.

**operatorEvent** `string`

Allowed values: `'joined'`, `'released'`, `'resolved'`.

**escalated** `boolean`

Present when a Gorgias ticket exists for the thread. Fixed value: `true`.

### Status codes

| Code | Meaning |
| - | - |
| `200` | Thread and its messages |
| `401` | Widget token missing, malformed, expired, from the future, or badly signed |
| `403` | Thread capability missing/wrong, thread owner mismatch, or token identity mismatch |
| `404` | Unknown thread (or, for feedback, a message that is not an assistant message) |
| `429` | Too many requests for this IP (scoped by verified org/agent) |
| `500` | Unhandled error |

### Using this contract

Read the [source OpenAPI document](https://docs.stateset.com/spec/chat-widget.json) for declared schemas and alternatives.
This page also includes documented corrections from the [spec overlays](https://github.com/stateset/docs/tree/main/spec/overlays).
Example IDs and values are illustrative; replace them with records from your workspace.

```bash cURL theme={null}
curl --silent --show-error --fail-with-body --request GET \
  --url 'https://api.example.com/api/response/threads/{id}' \
  --header 'x-widget-token: YOUR_API_KEY' \
  --header 'x-widget-thread-token: REPLACE_WITH_X_WIDGET_THREAD_TOKEN'
```

```json 200 theme={null}
{
  "thread": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "subject": "Replacement tent pole set",
    "title": "Replacement tent pole set",
    "channel": "string",
    "meta": {},
    "provider": "openai",
    "createdAt": "2026-08-31T14:22:05Z",
    "updatedAt": "2026-08-31T14:22:05Z",
    "messages": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "sender": "user",
        "text": "Two-person tent, green — replacement for damaged pole set.",
        "timestamp": "2026-08-31T14:22:05Z",
        "type": "text",
        "richContent": {
          "image": "https://cdn.example.com/products/tent-2p.jpg",
          "title": "Replacement tent pole set",
          "description": "Two-person tent, green — replacement for damaged pole set.",
          "formId": "string",
          "buttonStyle": "default",
          "layout": "scroll",
          "actions": [
            {
              "label": null
            }
          ],
          "buttons": [
            {
              "label": null,
              "value": null,
              "href": null,
              "target": null
            }
          ],
          "fields": [
            {
              "name": null,
              "label": null,
              "type": null,
              "placeholder": null,
              "required": null,
              "options": null
            }
          ],
          "submitLabel": "string",
          "headline": "Replacement tent pole set",
          "subhead": "string",
          "products": [
            {
              "id": null,
              "title": null,
              "price": null,
              "image": null,
              "url": null,
              "description": null,
              "whyItMatches": null,
              "rating": null,
              "reviewCount": null,
              "badges": null,
              "isUpsell": null,
              "actions": null,
              "variantOptions": null,
              "variantSelectionLabel": null,
              "variantSelectionPlaceholder": null,
              "variantSelectionRequired": null,
              "variantDisplay": null,
              "selectedVariantId": null,
              "selectedVariantLabel": null,
              "complementaryProducts": null,
              "complementaryHeadline": null,
              "complementaryText": null,
              "continueShoppingAfterAdd": null
            }
          ],
          "autoAction": {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "type": "add_to_cart",
            "productId": "string",
            "quantity": 2,
            "expiresAt": "2026-08-31T14:22:05Z"
          },
          "orders": [
            {
              "id": null,
              "name": null,
              "amount": null,
              "status": null,
              "trackingUrl": null,
              "lineItems": null,
              "actions": null
            }
          ]
        },
        "attachments": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "name": "Two-Person Tent",
            "size": 1,
            "type": "standard",
            "dataUrl": "string",
            "previewUrl": "string",
            "url": "https://example.com/webhooks/stateset"
          }
        ],
        "toolCalls": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "name": "Two-Person Tent",
            "arguments": {},
            "result": null,
            "status": "running"
          }
        ],
        "sources": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "title": "Replacement tent pole set",
            "url": "https://example.com/webhooks/stateset",
            "snippet": "string"
          }
        ],
        "suggestions": [
          "string"
        ],
        "thinking": "string",
        "reaction": "up",
        "feedbackComment": "string",
        "feedbackAt": "2026-08-31T14:22:05Z",
        "authorName": "string",
        "operatorEvent": "joined"
      }
    ]
  },
  "messages": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "sender": "user",
      "text": "Two-person tent, green — replacement for damaged pole set.",
      "timestamp": "2026-08-31T14:22:05Z",
      "type": "text",
      "richContent": {
        "image": "https://cdn.example.com/products/tent-2p.jpg",
        "title": "Replacement tent pole set",
        "description": "Two-person tent, green — replacement for damaged pole set.",
        "formId": "string",
        "buttonStyle": "default",
        "layout": "scroll",
        "actions": [
          {
            "label": "Replacement tent pole set"
          }
        ],
        "buttons": [
          {
            "label": "Replacement tent pole set",
            "value": "49.00",
            "href": "https://example.com/webhooks/stateset",
            "target": "_self"
          }
        ],
        "fields": [
          {
            "name": "Two-Person Tent",
            "label": "Replacement tent pole set",
            "type": "standard",
            "placeholder": "string",
            "required": true,
            "options": []
          }
        ],
        "submitLabel": "string",
        "headline": "Replacement tent pole set",
        "subhead": "string",
        "products": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "title": "Replacement tent pole set",
            "price": "49.00",
            "image": "https://cdn.example.com/products/tent-2p.jpg",
            "url": "https://example.com/webhooks/stateset",
            "description": "Two-person tent, green — replacement for damaged pole set.",
            "whyItMatches": "string",
            "rating": 1.5,
            "reviewCount": 1,
            "badges": [],
            "isUpsell": true,
            "actions": [],
            "variantOptions": [],
            "variantSelectionLabel": "string",
            "variantSelectionPlaceholder": "string",
            "variantSelectionRequired": true,
            "variantDisplay": "select",
            "selectedVariantId": "string",
            "selectedVariantLabel": "string",
            "complementaryProducts": [],
            "complementaryHeadline": "string",
            "complementaryText": "string",
            "continueShoppingAfterAdd": true
          }
        ],
        "autoAction": {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "type": "add_to_cart",
          "productId": "string",
          "quantity": 2,
          "expiresAt": "2026-08-31T14:22:05Z"
        },
        "orders": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "name": "Two-Person Tent",
            "amount": "49.00",
            "status": "pending",
            "trackingUrl": "string",
            "lineItems": [],
            "actions": []
          }
        ]
      },
      "attachments": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "Two-Person Tent",
          "size": 1,
          "type": "standard",
          "dataUrl": "string",
          "previewUrl": "string",
          "url": "https://example.com/webhooks/stateset"
        }
      ],
      "toolCalls": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "Two-Person Tent",
          "arguments": {},
          "result": null,
          "status": "running"
        }
      ],
      "sources": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "title": "Replacement tent pole set",
          "url": "https://example.com/webhooks/stateset",
          "snippet": "string"
        }
      ],
      "suggestions": [
        "string"
      ],
      "thinking": "string",
      "reaction": "up",
      "feedbackComment": "string",
      "feedbackAt": "2026-08-31T14:22:05Z",
      "authorName": "string",
      "operatorEvent": "joined"
    }
  ],
  "escalated": true
}
```


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