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 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. |
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.
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.
All successful responses are JSON with a 200 or 201 status. List endpoints return an object with a plural key:
Single-resource endpoints return the resource directly:
{ "id": "sess_123", "...": "..." }
{
"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. |
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. |
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). |
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). |
Strategies
| Method | Path | Description |
|---|
GET | /api/strategies | List strategies. |
POST | /api/strategies | Propose a strategy (strategy:author). |
Approvals
| Method | Path | Description |
|---|
GET | /api/approvals | List approvals (optional ?run_id=, ?state=). |
POST | /api/approvals/{id}/decide | Approve or deny (human-only). |
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. |
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. |
