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

The runtime determines the thread owner from the authenticated caller.
Creation does not start an execution.
Send a message to start a run.

- data (object)

  Persistent invocation arguments for `ThreadState.arguments` and prompt variables.
  Non-empty arguments are validated against the agent side A prompt's `requiredSchema`.
  Invalid arguments return `400`.
  Omitted, `null`, or empty arguments skip schema validation.

* env_types (object)

  Environment display types by key.
  Use `text` for values that can appear in prompts and output.
  Other values use `secret`.
  Keys without a matching `env` value are ignored.

- properties (object)

  Initial thread properties.
  The runtime reserves its invocation-argument property.

`initial_messages` is accepted for compatibility but is not stored.
Use the send-message endpoint to add messages.

- 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)

  Confirmation text. The Standard Agent Specification defines `threadId` and `agent_id` for this response. `message` is a runtime addition that the specification permits, and a client can ignore it.

A successful request returns `200`.

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

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

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

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

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