API Reference

HTTP routes, resource relationships, request behavior, errors, OpenAPI, and operational caveats.

The API server is built with Hono and publishes OpenAPI at:

GET /openapi.json

Health check:

GET /health

Error Shape

Validation, not-found, and internal errors use:

{
  "error": "Invalid request",
  "code": "invalid_request",
  "message": "Invalid request",
  "details": {},
  "requestId": "uuid-or-x-request-id",
  "retryable": false,
  "recoverable": true
}

Status	Code	Meaning
`400`	`invalid_request`	Validation failed, IDs differ, unsafe path, or stale target hash.
`404`	`not_found`	Requested resource was not found.
`500`	`internal_error`	Unexpected server error.

The server checks path IDs against body IDs for run events, checkpoints, model/tool records, branches, interventions, and fixtures.

Pagination

List-style routes accept limit and offset where noted. Defaults are limit=100&offset=0; maximum limit is 500.

Project Routes

Method	Path	Purpose
`POST`	`/v1/projects`	Create project.
`GET`	`/v1/projects/{id}`	Fetch project.
`GET`	`/v1/projects/{id}/catalog`	Summarize project observed projections and capabilities.

Run And Capture Routes

Method	Path	Purpose
`POST`	`/v1/runs`	Create run.
`GET`	`/v1/runs?projectId=...&limit=100&offset=0`	List runs, optionally filtered by project.
`GET`	`/v1/runs/{id}`	Fetch run.
`PATCH`	`/v1/runs/{id}`	Patch run status, timing, agent/name, or metadata.
`POST`	`/v1/runs/{id}/events:batch`	Append ordered events. Returns `{ inserted }`.
`GET`	`/v1/runs/{id}/events?limit=100&offset=0`	Fetch base events ordered by sequence.
`POST`	`/v1/artifacts`	Store artifact payload.
`GET`	`/v1/artifacts/{id}`	Fetch artifact metadata plus payload when file exists.
`POST`	`/v1/runs/{id}/checkpoints`	Create checkpoint.
`GET`	`/v1/runs/{id}/checkpoints`	List checkpoints.
`POST`	`/v1/runs/{id}/model-calls`	Store or update model call projection.
`POST`	`/v1/runs/{id}/tool-proposals`	Store tool proposal projection.
`POST`	`/v1/runs/{id}/tool-executions`	Store or update tool execution projection.

Context Routes

Method	Path	Purpose
`GET`	`/v1/runs/{id}/context-inventory`	Reconstruct context inventory for a run.
`GET`	`/v1/model-calls/{id}/context-inventory`	Filter inventory to one model call.
`GET`	`/v1/checkpoints/{id}/context-inventory`	Filter inventory to one checkpoint.
`POST`	`/v1/context/search`	Search context items by project, optional run, kinds, query, `limit`, and `offset`.
`GET`	`/v1/runs/{id}/catalog`	Summarize run observed projections and next actions.

Branch And Intervention Routes

Method	Path	Purpose
`POST`	`/v1/runs/{id}/branches`	Create branch from run checkpoint.
`GET`	`/v1/branches/{id}`	Fetch branch.
`POST`	`/v1/branches/{id}/interventions`	Attach typed intervention.
`GET`	`/v1/branches/{id}/interventions`	List interventions.

Replay And Fixture Routes

Method	Path	Purpose
`POST`	`/v1/replays`	Create replay. Executes immediately unless `wait: false`.
`GET`	`/v1/replays/{id}`	Fetch replay.
`GET`	`/v1/replays/{id}/events?limit=100&offset=0`	Fetch latest-attempt replay events or fallback base events.
`GET`	`/v1/replays/{id}/attempts?limit=100&offset=0`	List append-only replay attempts.
`GET`	`/v1/replays/{id}/fixture-requirements`	List fixture requirements.
`GET`	`/v1/replays/{id}/diff`	List replay diffs.
`GET`	`/v1/replays/{id}/metrics`	List replay metrics.
`GET`	`/v1/replays/{id}/effects`	List replay-level effects.
`POST`	`/v1/replays/{id}/tool-fixtures`	Create tool fixture and satisfy matching requirements.
`POST`	`/v1/replays/{id}/resume`	Re-execute replay after fixtures are added.

POST /v1/replays returns 201 for finished replays and 202 for paused or queued replays. Queued replays include metadata.jobId.

Experiment Routes

Method	Path	Purpose
`POST`	`/v1/experiments`	Create experiment plan.
`POST`	`/v1/hypothesis-batches`	Create plan, run it, and return results.
`GET`	`/v1/experiments/{id}`	Fetch experiment.
`POST`	`/v1/experiments/{id}/run`	Run experiment. Enqueues a durable job when `wait: false`.
`GET`	`/v1/experiments/{id}/results?limit=100&offset=0`	Fetch aggregate result object with paged arrays.
`GET`	`/v1/experiments/{id}/requirements?limit=100&offset=0`	List requirements across experiment replays.
`GET`	`/v1/experiments/{id}/trial-matrix?limit=100&offset=0`	List arms and replay statuses.
`GET`	`/v1/experiments/{id}/statistics`	Fetch experiment statistics.
`GET`	`/v1/experiments/{id}/arm-comparison?limit=100&offset=0`	Currently returns trial matrix data.
`GET`	`/v1/experiments/{id}/effects`	List experiment-level effects.

Effects And Analysis Routes

Method	Path	Purpose
`POST`	`/v1/effects:rank`	Return ranked effects from replays or an experiment.
`POST`	`/v1/analysis-runs`	Create persisted analysis output from base run and optional replay/experiment.
`GET`	`/v1/analysis-runs/{id}`	Fetch analysis run record.

Job Route

Method	Path	Purpose
`GET`	`/v1/jobs/{id}/events`	Returns durable job lifecycle SSE from stored job events: `job.queued`, `job.enqueued`, `job.started`, then `job.finished` or `job.failed`.

Resource Relationships

Projects own runs, artifacts, branches, replays, fixtures, experiments, and analysis outputs.

Runs own ordered events, model calls, tool proposals, tool executions, checkpoints, and run-scoped artifacts.

Branches belong to a base run and checkpoint, then own interventions.

Replays belong to a project and base run, optionally branch and experiment arm with trialIndex, then produce replay events, requirements, diffs, metrics, fixture uses, attempts, and effects.

Experiments own hypotheses and arms. Arms reference branches and replay IDs.

Analysis runs reference a base run and optionally replay or experiment evidence.

On this page