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

# Create Thread

Creates a new conversation thread with the specified agent.

**agent\_id** `string` *required*

The name of the agent to use for this thread. Must match an agent defined in `agents/agents/`.

**user\_id** `string`

Optional user identifier for tracking and authorization.

**tags** `array`

Optional array of string tags for categorizing and filtering threads.

**env** `object`

Optional thread environment values. Every value must be a string.

### Errors

A request is rejected with `400`, and no thread is created, when:

* the body is not a JSON object
* `agent_id` is absent or is not a string
* `tags` is present and is not an array of strings
* `env` is present and is not an object whose values are all strings

`null` counts as present for `tags` and `env`. An empty `tags` array and an empty `env` object are valid.

A string `agent_id` returns `404` unless it is the `id` of an agent that `GET /api/agents` lists for the caller without a filter.
Those are the project's agents and the entry agents of installed packages, including agents with `primary: false`.
An agent of a package that is not one of its entry agents returns the same `404` as a name that matches no agent, and no thread is created.

**threadId** `string` *required*

Unique thread identifier (UUID)

**agent\_id** `string` *required*

The agent name associated with this thread

**message** `string` *required*

Confirmation message

```bash cURL theme={null}
curl -X POST https://your-worker.workers.dev/api/threads \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "support_agent",
    "user_id": "user_abc123",
    "tags": ["support", "web"]
  }'
```

```typescript JavaScript theme={null}
const response = await fetch('https://your-worker.workers.dev/api/threads', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    agent_id: 'support_agent',
    user_id: 'user_abc123',
    tags: ['support', 'web']
  })
});
const thread = await response.json();
```

```json 200 theme={null}
{
  "threadId": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "support_agent",
  "message": "Thread created successfully"
}
```

```json 400 theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "env must be an object whose values are all strings"
  },
  "requestId": "0b3c1f0e-7f0a-4a55-9c58-2f6f5a0f6f0e"
}
```

```json 404 theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Agent not found: missing_agent"
  },
  "requestId": "0b3c1f0e-7f0a-4a55-9c58-2f6f5a0f6f0e"
}
```


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