Create Thread

Create a new conversation thread.

Threads hold conversation state and checkpoint history. Provide a thread_id for idempotent creation, or let the server generate one. Set if_exists to "do_nothing" to return the existing thread when the ID already exists instead of raising a 409 conflict.

POST /threads

Create Thread

cURL

curl --request POST \
  --url https://api.example.com/threads \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {},
  "initial_state": {},
  "threadId": "<string>",
  "ifExists": "raise"
}
'

200

{
  "thread_id": "<string>",
  "user_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "status": "idle",
  "metadata": {}
}

Body

application/json

Request model for creating threads

metadata · Metadata · object

Thread metadata

initial_state · Initial State · object

LangGraph initial state

threadId · string | null

Optional client-provided thread ID for idempotent creation

ifExists · string | null · default: raise

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

Response

200

application/json

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.