Sessions

A session is one conversation with an agent; see sessions and turns for how to use one. Paths are relative to /v1. To create a session, send environment plus either agent_id (a saved agent) or agent (an inline configuration). input is optional; if present, it starts the first turn. Other optional fields are vault_ids and metadata. Use {"type":"none"} when no sandbox is needed.

Method	Path	Purpose / response
`GET`	`/agents/sessions`	List · `SyncCursorPage[AgentSession]`
`POST`	`/agents/sessions`	Create · `AgentSession`
`DELETE`	`/agents/sessions/{session_id}`	Delete · `AgentSessionDeleted`
`GET`	`/agents/sessions/{session_id}`	Get · `AgentSession`
`POST`	`/agents/sessions/{session_id}`	Update · `AgentSession`

Session items and turns

Method	Path	Purpose / response
`GET`	`/agents/sessions/{session_id}/items`	List · `SyncCursorPage[AgentSessionItem]`
`GET`	`/agents/sessions/{session_id}/turns`	List · `SyncCursorPage[Turn]`
`GET`	`/agents/sessions/{session_id}/turns/{turn_id}`	Get · `Turn`

Subagents and their history

Method	Path	Purpose / response
`GET`	`/agents/sessions/{session_id}/subagents`	List · `SyncCursorPage[Subagent]`
`GET`	`/agents/sessions/{session_id}/subagents/{subagent_id}`	Get · `Subagent`
`GET`	`/agents/sessions/{session_id}/subagents/{subagent_id}/items`	List · `SyncCursorPage[AgentSessionItem]`
`GET`	`/agents/sessions/{session_id}/subagents/{subagent_id}/turns`	List · `SyncCursorPage[Turn]`
`GET`	`/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}`	Get · `Turn`
`GET`	`/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items`	List · `SyncCursorPage[AgentSessionItem]`

Artifacts

Method	Path	Purpose / response
`GET`	`/agents/sessions/{session_id}/artifacts`	List · `SyncCursorPage[SessionArtifact]`
`DELETE`	`/agents/sessions/{session_id}/artifacts/{artifact_id}`	Delete · `SessionArtifactDeleted`
`GET`	`/agents/sessions/{session_id}/artifacts/{artifact_id}`	Get · `SessionArtifact`
`GET`	`/agents/sessions/{session_id}/artifacts/{artifact_id}/content`	Download · Binary content

Create and read a conversation:

curl -X POST "$BASE_URL/agents/sessions" \
  -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' \
  -d '{"agent_id":"'"$AGENT_ID"'","environment":{"type":"none"},"input":"Summarize this topic."}'
curl -H "Authorization: Bearer $API_KEY" "$BASE_URL/agents/sessions/$SESSION_ID/turns?limit=10"
curl -H "Authorization: Bearer $API_KEY" "$BASE_URL/agents/sessions/$SESSION_ID/items?limit=10"
curl -X POST "$BASE_URL/agents/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' \
  -d '{"metadata":{"project":"demo"}}'

Statuses

Object	`status` values
Session	`idle`, `in_progress`, `requires_action`, `failed`
Turn	`queued`, `in_progress`, `waiting`, `completed`, `failed`, `cancelled`
Subagent	`active`, `closed`

See turns and statuses for what each means.

Notes

GET .../turns lists subagent turns alongside the session’s own; they carry a non-null subagent_id, while session items list only the session’s own conversation. POST /agents/sessions/{session_id} updates metadata only. List sessions accepts agent_id, after, limit, order; history and artifact lists accept after, limit, order (artifacts also accept environment_id). A turn may still be in progress after session creation: inspect its status or subscribe to events. Artifact content is binary, not a JSON resource. Deleting a session does not delete its saved agent.

​Sessions

​Session items and turns

​Subagents and their history

​Artifacts

​Statuses

​Notes