Sessions and Turns
Use the Organization API Key from your backend and select the owning End User in the path. Retained User-Key reads and interaction commands use the owner’s /api/v1/user/sessions routes.
Create and read a conversation
Section titled “Create and read a conversation”| Method and path | Purpose |
|---|---|
POST /api/v1/org/users/{userId}/sessions |
Create a Session from an explicit AgentTemplate and freeze its current configuration. |
GET /api/v1/org/users/{userId}/sessions |
List owned Sessions with cursor pagination. |
GET /api/v1/org/users/{userId}/sessions/{id} |
Read metadata and current execution identity. |
PATCH /api/v1/org/users/{userId}/sessions/{id}/model |
Select the model for the next Turn with the Session’s If-Match token. |
POST /api/v1/org/users/{userId}/sessions/{id}/name |
Set the display name. |
DELETE /api/v1/org/users/{userId}/sessions/{id} |
Hide the Session within its execution and cleanup boundaries. |
Creation accepts { "agentTemplateId": "…", "model": "…" }; omitting model uses the active release’s default model when it is served, otherwise the Organization default. Model selection belongs to the Session, independently of Template behavior. To change it, send { "model": "…" } to the model route with the Session read’s ETag in If-Match. Missing and stale tokens return 428 and 412. Selection is limited to models the active release serves. A change during execution takes effect from the next Turn; steering and continuation retain the current Turn’s admitted model.
Later Template saves affect new Sessions. Existing Sessions keep their fixed recipe while current authority and dependency availability govern execution. Hiding a Session is distinct from erasing its history.
Keep the original Idempotency-Key for creation retries. The request may include additionalInstructions and sandbox. Supply acknowledgeSessionRecall: true when the selected Template enables cross-Session Recall. Session lists accept an agentTemplateId filter for the current Configuration Epoch. Saved Turns carry the agentTemplateId admitted for that Turn.
Switch the Session’s Template
Section titled “Switch the Session’s Template”Send the target agentTemplateId and a stable Idempotency-Key to POST /api/v1/org/users/{userId}/sessions/{id}/template-switches. The Session must be idle with no live Realtime Connection. A target that enables cross-Session Recall requires acknowledgment. Replay the same request to recover the latest state of the original receipt.
A Session with incorporated history returns a pending receipt with a handoffTurnId. Read that Turn for the assistant summary when it succeeds. A template_handoff Turn has no user Message. Success advances the Configuration Epoch. Failure or cancellation preserves the source epoch and leaves a terminal Turn in history. An empty Session can switch immediately. Equivalent effective configuration returns unchanged.
Submit commands
Section titled “Submit commands”POST /api/v1/org/users/{userId}/sessions/{id}/events accepts a message, an explicit cancellation or, when enabled by the deployment, a checkpoint retry and returns a stable JSON command receipt after reliable acceptance. Submission and following are separate: an Application Server follows the Session’s events over its Backend Connection, and other clients read the receipt, Turns and timeline.
Turn checkpoint retry is disabled by default. A new InputRetryEvent returns 400 checkpoint_runtime_unavailable when disabled or unavailable. When enabled, a new retry for a Turn admitted under an earlier Session Configuration Epoch returns 409 session_configuration_epoch_changed. Previously accepted retry commands still recover their original receipt with 200 and never execute again; disabling retry does not remove saved history or disable cancellation.
A Session has at most one active Full Agent Turn; completed Realtime Turns do not occupy that slot. A new plain-text requirement during execution steers that same Turn instead of queueing another. Acceptance alone does not prove incorporation or success. A cancellation records an intent; read its eventual result. Completed external effects retain their actual effects.
Keep the original command identity and content when recovering an uncertain request. Querying the original receipt does not submit or execute the command again. An explicit checkpoint retry is a new command whose result must remain distinct from the earlier execution result.
Read receipts and history
Section titled “Read receipts and history”| Method and path | Purpose |
|---|---|
GET /api/v1/org/users/{userId}/sessions/{id}/interactions |
List message, cancellation and checkpoint-retry receipts, or find the original retry receipt by its command key. |
GET /api/v1/org/users/{userId}/sessions/{id}/interactions/{receiptId} |
Read the original command and its original execution result. |
GET /api/v1/org/users/{userId}/sessions/{id}/turns |
List Full Agent and user-input Realtime Turns with cursor pagination. |
GET /api/v1/org/users/{userId}/sessions/{id}/turns/{turnId} |
Read the selected Full Agent or user-input Realtime Turn’s saved history. |
GET /api/v1/org/users/{userId}/sessions/{id}/timeline |
List Turns and Realtime facts in one Session timeline order with cursor pagination. |
POST /api/v1/org/users/{userId}/sessions/{id}/turns/audio |
Transcribe audio and submit a Turn under the applicable admission rules. |
Use the command receipt for its original execution outcome. A current Turn read and Session idleness answer different questions. Successful assistant Messages, partial drafts and progress updates have different meanings; a failed draft is not a final answer.
Session events and recovery explains following persisted events and reconnecting.
See reading Realtime conversation history for transcript metadata, narration and pagination behavior.