Create Thread

POST

api

threads

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"]
  }'

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

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

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

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

Creates a new conversation thread with the specified agent.

string

required

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

string

Optional user identifier for tracking and authorization.

array

Optional array of string tags for categorizing and filtering threads.

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.

string

required

Unique thread identifier (UUID)

string

required

The agent name associated with this thread

string

required

Confirmation message

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"]
  }'

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

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

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

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

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"]
  }'

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

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

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

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

Threads

Messages

File System

Define Utilities

WebSocket

Errors

​Errors

Errors