Sessions

Create session

Create a Session for a saved Agent, or for an inline Agent defined in the request. The Agent configuration, Skills, and MCP connections are frozen for the lifetime of the Session. With stream=true and an initial input, the 201 response is a Server-Sent Events stream of the first turn instead of a JSON Session. Execution admission (balance and organization status) is checked here.

post/v1/agents/sessions

Request

  • Base URL: https://api.sandbase.ai
  • URL: https://api.sandbase.ai/v1/agents/sessions
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Headers

Idempotency-Keystring

Optional. Send a stable key so retries do not create duplicates.

OpenAI-Beta'agents=v1'

Optional OpenAI SDK header. When present it must be agents=v1.

Request body

OR

Response

Session created. With stream=true, a text/event-stream of the first turn whose first event, agent.session.created, carries the Session.

idstring required

Session ID (ses_ prefix).

object'agent.session' required
agentobject required

OpenAI-shaped snapshot of the effective Agent configuration (id, name, model, instructions, multi_agent, reasoning, service_tier, text, tools).

agent_idstring required
agent_versioninteger required
titlestring required
modelstring required
metadataobject required
status'idle' | 'in_progress' | 'requires_action' | 'failed' required

Execution status. requires_action is not supported yet and surfaces as a 502 executor_contract_error.

lifecycle_status'active' | 'archived' required
sync_statusstring required
execution_statusstring required
row_versioninteger required
vault_idsstring[] required
usageobject nullable

Token usage; null until a turn reports usage.

created_atinteger required
last_active_atinteger required
updated_atinteger required
archived_atinteger nullable required
source'direct' | 'service' | 'schedule' | 'null' nullable
source_idstring nullable

Service or Schedule ID when source is service or schedule.

source_failure_codestring

Changes

No recorded changes to this operation across all 1 revision of this API.