> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doomberg.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Session endpoints

> List, create, and seed demo research sessions — the top-level container for traced agent activity.

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

```http theme={null}
GET /api/sessions
Authorization: Bearer <token>
```

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

### Response

```json theme={null}
{
  "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

```http theme={null}
POST /api/sessions
Authorization: Bearer <token>
Content-Type: application/json
```

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```http theme={null}
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.

<Callout type="info">
  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](/api/sessions).
</Callout>

The demo session includes this event sequence:

1. `session_open`
2. `reasoning` — agent plans the research
3. `tool_call` — `fetch_history` for NVDA
4. `tool_call` — `screen_momentum` on semis
5. `strategy_proposed` — a momentum StrategySpec
6. `tool_call` — `request_backtest`
7. `run_progress` — backtest completes
8. `session_close`

### Response

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

## Related

* [Run endpoints](/api/runs) — runs belong to sessions
* [Events & SSE](/api/runs) — streaming session events live
* [Session replay](/api/sessions) — how the web UI replays sessions
* [Trace events](/api/runs) — the event contract