Skip to content

Sessions API

Sessions provide bounded operational contexts with limits.

Create Session

POST /sessions

Headers

Header Required Description
X-API-Key Yes Your API key

Request

{
  "agent_id": "2ffacd56-86ff-483c-8c59-5686df52aff8",
  "max_actions": 100,
  "max_value_usd": 1000.00,
  "expires_in_seconds": 3600
}

Response

{
  "id": "f2cc7759-b324-4a4c-943a-cf5a3e090061",
  "agent_id": "2ffacd56-86ff-483c-8c59-5686df52aff8",
  "status": "active",
  "max_actions": 100,
  "action_count": 0,
  "max_value_usd": 1000.00,
  "value_used_usd": 0.00,
  "expires_at": "2025-01-16T15:30:00Z",
  "created_at": "2025-01-16T14:30:00Z"
}

List Sessions

GET /sessions

Query Parameters

Parameter Type Description
status string Filter by status
agent_id UUID Filter by agent

Response

[
  {
    "id": "f2cc7759-b324-4a4c-943a-cf5a3e090061",
    "agent_id": "2ffacd56-86ff-483c-8c59-5686df52aff8",
    "status": "active",
    "action_count": 45,
    "max_actions": 100,
    "expires_at": "2025-01-16T15:30:00Z"
  }
]

Get Session

GET /sessions/{id}

Response

Full session details including all limits and usage.

End Session

POST /sessions/{id}/end

Response

{
  "id": "f2cc7759-b324-4a4c-943a-cf5a3e090061",
  "status": "completed",
  "ended_at": "2025-01-16T15:00:00Z"
}