> ## 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.

# REST API overview

> Base URL, authentication, tenant isolation, response format, and the full endpoint catalog for the Ithaca REST API.

The Ithaca REST API is the HTTP surface for the web UI, integrations, and direct scripting. The MCP server calls the same underlying services — the REST API is not a separate codebase.

## Base URL

All endpoints are rooted at `/api`. In production the API is served from `https://app.doomberg.me/api`. In local development it is served from `http://localhost:8000/api`.

```
https://app.doomberg.me/api
```

## Authentication

Two authentication modes are supported. See [Auth overview](/api/overview) for the full model.

| Mode        | Header                                              | Used by                                |
| ----------- | --------------------------------------------------- | -------------------------------------- |
| API key     | `Authorization: Bearer dmbg_<env>_<keyid>_<secret>` | Agents, MCP server, scripts.           |
| Session JWT | `Authorization: Bearer <clerk-jwt>`                 | Web UI (Clerk OAuth).                  |
| Dev header  | `X-Tenant-Id: <tenant_id>`                          | Local development only. Bypasses auth. |

<Callout type="warn">
  The `X-Tenant-Id` dev header is only accepted when the server is running in development mode. In production it is ignored. Never rely on it for real traffic.
</Callout>

## Tenant isolation

Every authenticated request resolves to a `tenant_id`. Every query is scoped by it. There is **no unscoped read path**. See [Tenant isolation](/api/overview).

## Response format

All successful responses are JSON with a `200` or `201` status. List endpoints return an object with a plural key:

```json theme={null}
{ "sessions": [ ... ] }
```

Single-resource endpoints return the resource directly:

```json theme={null}
{ "id": "sess_123", "...": "..." }
```

## Error format

Errors are JSON with a consistent shape:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "run run_abc not found",
    "details": { "run_id": "run_abc" }
  }
}
```

| HTTP status | `code`             | Meaning                                                 |
| ----------- | ------------------ | ------------------------------------------------------- |
| `400`       | `bad_request`      | Malformed body or query.                                |
| `401`       | `unauthorized`     | Missing or invalid credentials.                         |
| `403`       | `forbidden`        | Authenticated but lacks scope.                          |
| `404`       | `not_found`        | Resource does not exist (or belongs to another tenant). |
| `409`       | `conflict`         | State transition not allowed.                           |
| `422`       | `validation_error` | Schema validation failed. Field-level details included. |
| `429`       | `rate_limited`     | Too many requests.                                      |
| `500`       | `internal_error`   | Unexpected server error.                                |

## Endpoint catalog

### Auth

| Method   | Path                          | Description                         |
| -------- | ----------------------------- | ----------------------------------- |
| `GET`    | `/api/overview/me`            | Current principal.                  |
| `POST`   | `/api/overview/keys`          | Mint an API key (session JWT only). |
| `GET`    | `/api/overview/keys`          | List API keys.                      |
| `DELETE` | `/api/overview/keys/{key_id}` | Revoke an API key.                  |

→ [Auth endpoints](/api/overview)

### Sessions

| Method | Path                      | Description                            |
| ------ | ------------------------- | -------------------------------------- |
| `GET`  | `/api/sessions`           | List sessions.                         |
| `POST` | `/api/sessions`           | Create a session.                      |
| `POST` | `/api/sessions/seed-demo` | Seed a demo session for first-time UX. |

→ [Session endpoints](/api/sessions)

### Runs

| Method | Path                     | Description                    |
| ------ | ------------------------ | ------------------------------ |
| `GET`  | `/api/runs`              | List runs (optional `?kind=`). |
| `GET`  | `/api/runs/{id}`         | Full run + shaped trace.       |
| `GET`  | `/api/runs/{id}/book`    | Paper positions.               |
| `POST` | `/api/runs`              | Create a backtest run.         |
| `POST` | `/api/runs/{id}/cancel`  | Cancel a run.                  |
| `POST` | `/api/runs/{id}/promote` | Promote to paper (human-only). |

→ [Run endpoints](/api/runs)

### Events & SSE

| Method | Path                           | Description                      |
| ------ | ------------------------------ | -------------------------------- |
| `POST` | `/api/runs/{id}/events-ticket` | Mint a one-time SSE ticket.      |
| `GET`  | `/api/runs/{id}/events`        | SSE stream (replay + live tail). |

→ [Events & SSE](/api/runs)

### Strategies

| Method | Path              | Description                             |
| ------ | ----------------- | --------------------------------------- |
| `GET`  | `/api/strategies` | List strategies.                        |
| `POST` | `/api/strategies` | Propose a strategy (`strategy:author`). |

→ [Strategy endpoints](/api/strategies)

### Approvals

| Method | Path                         | Description                                      |
| ------ | ---------------------------- | ------------------------------------------------ |
| `GET`  | `/api/approvals`             | List approvals (optional `?run_id=`, `?state=`). |
| `POST` | `/api/approvals/{id}/decide` | Approve or deny (human-only).                    |

→ [Approval endpoints](/api/approvals)

### Providers

| Method | Path                     | Description                    |
| ------ | ------------------------ | ------------------------------ |
| `GET`  | `/api/providers`         | List connections + snapshots.  |
| `POST` | `/api/providers`         | Create or upsert a connection. |
| `GET`  | `/api/dataset-snapshots` | List dataset snapshots.        |

→ [Provider endpoints](/api/providers)

### Triggers

| Method | Path                       | Description           |
| ------ | -------------------------- | --------------------- |
| `GET`  | `/api/triggers`            | List triggers.        |
| `GET`  | `/api/trigger-firings`     | List trigger firings. |
| `POST` | `/api/triggers`            | Create a trigger.     |
| `POST` | `/api/triggers/{id}/state` | Change trigger state. |
| `POST` | `/api/triggers/dry-run`    | Dry-run a trigger.    |

→ [Trigger endpoints](/api/triggers)

## Related

* [Auth overview](/api/overview) — the two auth modes
* [Scopes](/api/overview) — the capability model
* [Tenant isolation](/api/overview) — the hard invariant