Skip to main content

Sessions

Sessions are conversation histories. They are created implicitly when a query or chat sets a session (or X-Alexandria-Session) value. The session API gives users read access to their own turn history.

Session summary object​

{
  "session_id": "my-session",
  "agent_id": "researcher",
  "turn_count": 12,
  "last_active": "2026-01-15T14:32:00Z"
}

Turn object​

{
  "role": "user",
  "content": "What is the capital of France?",
  "model_name": "gpt-4o",
  "created_at": "2026-01-15T14:32:00Z"
}

GET /v1/sessions​

List all sessions for the authenticated user.

Query params

  • agent — filter by agent name

Response 200 — array of session summary objects.

curl "http://localhost:8080/v1/sessions?agent=researcher" \
  -H "Authorization: Bearer $ACCESS" | jq .

GET /v1/sessions/{id}​

Get all turns in a session. The id parameter is the session ID string (not a UUID — it's the value passed in the query session field or X-Alexandria-Session header).

Scoped to the authenticated user.

Query params

  • agent — filter by agent name (when a session spans multiple agents)
  • limit / offset — pagination

Response 200 — array of turn objects. Returns 404 when no turns found.

curl "http://localhost:8080/v1/sessions/my-session?limit=10&offset=0" \
  -H "Authorization: Bearer $ACCESS" | jq .

DELETE /v1/sessions/{id}​

Delete a session and all its turns.

Query params

  • agent — scope deletion to a specific agent within the session

Response 200

{ "deleted": 12 }

Returns 404 if no turns matched.

curl -X DELETE "http://localhost:8080/v1/sessions/my-session" \
  -H "Authorization: Bearer $ACCESS" | jq .