POST
Create an agent session
This endpoint requires an Idempotency-Key request header — omitting it is a 400. See Idempotent requests.
See Agent sessions for the conversational session model and how a turn’s async job is polled to completion.

Authorizations

x-api-key
string
header
required

API key for authentication

Headers

Idempotency-Key
string
required

Required opaque key (max 255 chars, UUIDv4 recommended) making this request idempotent for 24h: a retry with the same key and body replays the original response with Idempotent-Replayed: true. Omitting it is a 400; reusing a key with a different body is a 422; retrying while the first request is still in flight is a 409.

Body

application/json
title
string

Human-readable name for the session.

Omit it — or send a blank string — and the session is titled "New Chat" until the agent generates a name from its first turn.

Maximum string length: 200
Example:

"Q3 supplier invoices"

Response

Session created.

session_id
string
required

Opaque session identifier used by the other agent routes.

Example:

"665f1c2e8a1b4c0012ab34cd"

title
string
required

The submitted title, or the placeholder the agent replaces when it names the session on its first turn.

Example:

"New Chat"

created_at
string<date-time>
required
updated_at
string<date-time>
required
last_active_at
string<date-time> | null

When a turn was last enqueued on this session.