Session endpoints

A session is the top-level container for a traced agent research conversation. Every tool call, reasoning step, and run belongs to a session. The web UI renders sessions as replayable timelines.

List sessions

GET /api/sessions
Authorization: Bearer <token>

Returns sessions for the caller’s tenant, newest first.

Response

{
  "sessions": [
    {
      "id": "sess_abc",
      "title": "NVDA momentum research",
      "tenant_id": "tnt_abc",
      "created_at": "2025-01-15T12:00:00Z",
      "closed_at": null,
      "event_count": 42
    }
  ]
}

Create a session

POST /api/sessions
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "NVDA momentum research",
  "prompt": "Research NVDA — pull price history, screen peers, propose a momentum strategy, and backtest it."
}

Field	Type	Required	Description
`title`	string	yes	Human-readable session title.
`prompt`	string	no	The initial prompt that kicked off the session.

Response

{
  "id": "sess_abc",
  "title": "NVDA momentum research",
  "prompt": "Research NVDA ...",
  "tenant_id": "tnt_abc",
  "created_at": "2025-01-15T12:00:00Z"
}

Creating a session emits a session_open trace event. The session is then ready to receive tool calls and runs.

Seed a demo session

POST /api/sessions/seed-demo
Authorization: Bearer <clerk-jwt>

Seeds a deterministic demo session for first-time users. This is what the web UI’s Welcome page auto-plays so a new user sees a complete research session before they’ve connected an agent.

The demo seeder generates a deterministic NVDA research session. The same events are produced every time, so the replay is identical for every new user. See Session replay.

The demo session includes this event sequence:

session_open
reasoning — agent plans the research
tool_call — fetch_history for NVDA
tool_call — screen_momentum on semis
strategy_proposed — a momentum StrategySpec
tool_call — request_backtest
run_progress — backtest completes
session_close

Response

{
  "id": "sess_demo_001",
  "title": "Demo: NVDA momentum research",
  "demo": true,
  "created_at": "2025-01-15T12:00:00Z"
}

Run endpoints — runs belong to sessions
Events & SSE — streaming session events live
Session replay — how the web UI replays sessions
Trace events — the event contract

​List sessions

​Response

​Create a session

​Response

​Seed a demo session

​Response

​Related

List sessions

Response

Create a session

Response

Seed a demo session

Response

Related