Sign in

v1

latestOpenAPI 3.0.02026-07-174565114.3 KB
v1

Create empty thread

Create a new empty thread. Note: initialMessages is not supported yet; create the thread first, then add messages via runs/message endpoints.

post/v1/threads

Request body

userKeystring

Identifier for a user in your system. Required if no bearer token is provided.

metadataobject

Additional metadata to attach to the thread

Example request

{
  "initialMessages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Hello, world!"
        }
      ]
    }
  ]
}

Response

Created thread

idstring required

Unique identifier for this thread

namestring

Thread name (auto-generated or user-set)

userKeystring

Optional user key for thread organization

runStatus'idle' | 'waiting' | 'streaming' required

Current run status: idle (no run), waiting (run started, awaiting content), streaming (receiving content)

currentRunIdstring

ID of the currently active run (when not idle)

statusMessagestring

Human-readable status message (e.g., 'Fetching weather data...')

lastRunCancelledboolean

Whether the last run was cancelled

pendingToolCallIdsstring[]

Tool call IDs awaiting client-side results. If non-empty, next run must provide tool_result content with previousRunId set.

lastCompletedRunIdstring

ID of the last completed run. Required as previousRunId when continuing after tool calls.

metadataobject

Additional metadata

createdAtstring required

When the thread was created (ISO 8601)

updatedAtstring required

When the thread was last updated (ISO 8601)

Example response

{
  "id": "thr_abc123xyz",
  "runStatus": "idle",
  "lastRunError": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  },
  "createdAt": "2024-01-15T12:00:00Z",
  "updatedAt": "2024-01-15T12:05:00Z"
}