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

Update Thread

PATCH/api/threads/{threadId}

Updates thread properties including tags and agent assignment.

threadIdstringrequired

The unique thread identifier (UUID)

tagsarray

Array of string tags (replaces existing tags)

agent_idstring

New agent to assign to the thread. The agent must have a human-backed side.

envobject | null

Replaces thread environment values. Values must be strings. null clears the environment.

env_typesobject

Display types for a replacement env. A matching key with text permits display. Other values use secret.

env_patchobject

Adds or replaces individual environment values. Keys must be non-empty after trimming. Values must be non-null. Values are converted to strings.

env_type_patchobject

Changes display types for existing environment keys. Use text or secret. A key without a matching environment value returns 400.

env_deletestring[]

Removes the named environment keys and their display types.

Use either replacement fields or patch fields in one request. Patch fields operate on the stored environment. The response includes env_types but omits environment values.

Errors

The route returns 400 for invalid JSON, invalid field types, invalid environment patches, or an empty update. An agent_id that is not a string returns 400. An unknown agent returns 404. An agent without a human-backed side returns 400.

Response

Returns the updated thread object.

idstringrequired

Thread identifier

agent_idstringrequired

The agent name associated with this thread

user_idstring | null

User identifier if set

tagsarrayrequired

Array of string tags

created_atnumberrequired

Unix timestamp in seconds

cURL

curl -X PATCH https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $STANDARD_AGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["support", "escalated", "priority"]
  }'

JavaScript

const response = await fetch(
  'https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'PATCH',
    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      tags: ['support', 'escalated', 'priority']
    })
  }
);
const result = await response.json();

200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "support_agent",
  "user_id": "user_abc123",
  "tags": ["support", "escalated", "priority"],
  "created_at": 1699900000
}

400

{
  "error": {
    "code": "bad_request",
    "message": "No valid fields to update"
  },
  "requestId": "0b3c1f0e-7f0a-4a55-9c58-2f6f5a0f6f0e"
}

404

{
  "error": {
    "code": "not_found",
    "message": "Thread not found: 550e8400-e29b-41d4-a716-446655440000"
  },
  "requestId": "0b3c1f0e-7f0a-4a55-9c58-2f6f5a0f6f0e"
}