> ## 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 POST /api/threads > Widget identity is verified when signing is configured; tokenless compatibility does not establish tenant ownership… 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. ### Request body `ThreadCreateRequest` **subject** `string` Default: `'New conversation'`. **message** `string` Optional first visitor message. **channel** `string` Default: `'chat'`. **meta** `ChatMeta` Free-form request metadata forwarded to the agent (department, custom fields, page context, `sessionId`, and `agent`/`agentConfig`/`kb` identity hints). Stored on the thread. Shape is merchant-defined. **ChatMeta** **sessionId** `string` **threadMessages** `RecoveryMessage[]` **RecoveryMessage** **id** `string` **sender** `string` *required* Allowed values: `'user'`, `'ai'`. **text** `string` *required* **timestamp** `string` **provider** `Provider` Allowed values: `'openai'`, `'anthropic'`, `'gemini'`. **attachments** `Attachment[]` Maximum items: `5`. **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). ### Response `object` **threadId** `string` *required* **threadToken** `string` *required* 32-character base64url capability; echo it as `x-widget-thread-token`. **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'`. ### Status codes | Code | Meaning | | - | - | | `201` | Thread created; `threadToken` is disclosed only here. | | `401` | Widget token missing, malformed, expired, from the future, or badly signed | | `403` | Request org/agent disagrees with the widget token claims | | `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 POST \ --url 'https://api.example.com/api/response/threads' \ --header 'x-widget-token: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "subject": "New conversation", "message": "Two-person tent, green — replacement for damaged pole set.", "channel": "chat", "meta": { "sessionId": "string", "threadMessages": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sender": "user", "text": "Two-person tent, green — replacement for damaged pole set.", "timestamp": "2026-08-31T14:22:05Z" } ] }, "provider": "openai", "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" } ] }' ``` ```json 201 theme={null} { "threadId": "string", "threadToken": "YOUR_API_KEY", "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" } ] } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.