REST API overview

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.tradeithaca.com/api. In local development it is served from http://localhost:8000/api.

https://app.tradeithaca.com/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.

Response format

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

{ "sessions": [ ... ] }

Single-resource endpoints return the resource directly:

{ "id": "sess_123", "...": "..." }

Error format

Errors are JSON with a consistent shape:

{
  "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

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

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

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

Strategies

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

→ Strategy endpoints

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

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

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

Auth overview — the two auth modes
Scopes — the capability model
Tenant isolation — the hard invariant

Getting Started

Agent Guide

Tools

Skills

Strategy & Backtest

REST API

REST API overview

Base URL

Authentication

Tenant isolation

Response format

Error format

Endpoint catalog

Auth

Sessions

Runs

Events & SSE

Strategies

Approvals

Providers

Triggers

​Base URL

​Authentication

​Tenant isolation

​Response format

​Error format

​Endpoint catalog

​Auth

​Sessions

​Runs

​Events & SSE

​Strategies

​Approvals

​Providers

​Triggers

​Related

Base URL

Authentication

Tenant isolation

Response format

Error format

Endpoint catalog

Auth

Sessions

Runs

Events & SSE

Strategies

Approvals

Providers

Triggers

Related