View as MarkdownPlain text for this page Open in ChatGPTQuestions about this page Open in ClaudeQuestions about this page

Create Thread

POST/api/threads

Creates a new conversation thread with the specified agent.

agent_idstringrequired

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.

dataobject

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_typesobject

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.

propertiesobject

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.

tagsarray

Optional array of string tags for categorizing and filtering threads.

envobject

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.

threadIdstringrequired

Unique thread identifier (UUID)

agent_idstringrequired

The agent name associated with this thread

messagestring

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.

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

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

200

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

400

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

404

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