Create Session

POST/v1/sessions

Create a stateful execution of an Agent. SandBase resolves runtime binding internally.

Request body

stringagentrequired

Agent ID used by this Session.

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...",
    "title": "Customer research"
  }'

Response200 OK

{
  "id": "sess_01...",
  "type": "session",
  "agent_id": "agent_01...",
  "agent_version": 1,
  "agent_version_id": "av_01...",
  "agent": {
    "id": "agent_01...",
    "type": "agent",
    "version": 1
  },
  "source": "direct",
  "title": "Customer research",
  "status": "idle",
  "metadata": {},
  "archived_at": null,
  "created_at": "2026-08-03T10:00:00Z",
  "updated_at": "2026-08-03T10:00:00Z"
}