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

# Create a thread

> Mirrors the widget's createThread helper.

Mirrors the widget's `createThread` helper.

### Request body

`ThreadCreate`

<ParamField body="subject" type="string" required />

<ParamField body="message" type="string" />

<ParamField body="channel" type="string" />

<ParamField body="meta" type="object" />

<ParamField body="provider" type="string" />

### Response

`ThreadWithMessages`

<ResponseField name="thread" type="object" required />

<ResponseField name="messages" type="Message[]" required>
  <Expandable title="Message">
    <ResponseField name="id" type="string" />

    <ResponseField name="sender" type="string" />

    <ResponseField name="text" type="string" />

    <ResponseField name="timestamp" type="string (date-time)" />
  </Expandable>
</ResponseField>

### Status codes

| Code  | Meaning |
| ----- | ------- |
| `200` | OK      |
| `400` | Error   |
| `401` | Error   |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.example.com/api/threads' \
    --header 'x-widget-token: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
    "subject": "Replacement tent pole set",
    "message": "Two-person tent, green — replacement for damaged pole set.",
    "channel": "string",
    "meta": {},
    "provider": "string"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "thread": {},
    "messages": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "sender": "string",
        "text": "Two-person tent, green — replacement for damaged pole set.",
        "timestamp": "2026-08-31T14:22:05Z"
      }
    ]
  }
  ```
</ResponseExample>