Create Session

POST/v1/sessions

Create a stateful execution of an Agent in an Environment.

Request body

stringagentrequired

Agent ID used by this Session.

Optional<string>environment_id

Optional authorized Session override. Omit to use the Agent-owned Environment.

Optional<string>title

Human-readable Session title.

Optional<object>metadata

Application metadata returned with the Session.

curl -X POST https://api.sandbase.ai/v1/sessions \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_01...",
    "environment_id": "env_01...",
    "title": "Customer research"
  }'

Response200 OK

{
  "id": "sess_01...",
  "type": "session",
  "agent_id": "agent_01...",
  "agent_version": 1,
  "environment_id": "env_01...",
  "title": "Customer research",
  "status": "idle",
  "metadata": {},
  "archived_at": null,
  "created_at": "2026-08-03T10:00:00Z",
  "updated_at": "2026-08-03T10:00:00Z"
}