Skip to main content
Create a session with POST /v2/sessions. Keep the same Idempotency-Key and unchanged JSON payload when retrying an uncertain result. The optional key supports up to 256 characters. Read status using GET /v2/sessions/{id}. The read payload includes createdAt, terminalAt, and result; it does not contain the create-only reusedExisting field. JSON success responses wrap this payload in data. Use If-None-Match with the response’s ETag. A matching response is HTTP 304 with an empty body. Reuse your cached payload instead of parsing JSON. You can use wait=25 to long poll; respect polling limits and retry headers. The stream endpoint is GET /v2/sessions/{id}/stream. Listen for events named session. Parse each event’s data as the session object directly; it has no JSON response envelope. Terminal states close the stream. If a session disappears, the stream can end with a minimal id and status: "expired" object. Keep v1 integration parsing separate. V1 uses sid, status_reason, and status / complete / expired stream event names. Do not redirect v1 endpoints to v2 or reuse the v2 parser for v1.