Skip to main content
POST
Create Thread

Body

application/json

Request model for creating threads

metadata
Metadata · object | null

Thread metadata

initial_state
Initial State · object | null

LangGraph initial state

threadId
string | null

Optional client-provided thread ID for idempotent creation. Omit or null to let the server generate a UUID. When set, 1–255 characters and not blank (must fit PostgreSQL btree keys uncompressed).

Required string length: 1 - 255
Pattern: \S
ifExists
string | null
default:raise

Behavior when thread exists: 'raise' (default) or 'do_nothing'

ttl
ThreadTTLSpec · object | null

Per-thread TTL override; requires TTL to be configured server-side or default_ttl set

Response

Successful Response

Thread entity model

Status values: idle, busy, interrupted, error

thread_id
string
required

Unique identifier for the thread.

user_id
string
required

Identifier of the user who owns this thread.

created_at
string<date-time>
required

Timestamp when the thread was created.

updated_at
string<date-time>
required

Timestamp when the thread was last updated.

status
string
default:idle

Current thread status: idle, busy, interrupted, or error.

metadata
Metadata · object

Arbitrary metadata attached to the thread.