HTTP API

The viewer is a single Next.js deployment that is both the website and the data plane. Every machine-boundary consumer — the ct CLI, browser client-components (lazy loads and downloads), and LLM agents — talks to the same /api routes documented here. The website's own server-rendered pages and server actions call the underlying data-layer functions in-process and do not go over HTTP, so they are not listed as routes.

This is the contract the CLI speaks and the surface a self-hosted viewer exposes. It is unversioned and lockstep: there is no /v1 prefix, breaking changes land atomically with their client, and a stale client fails loudly (a 400/404) rather than silently misbehaving. The remedy for a loud failure is to update your checkout (git pull).

Authentication

A deployment runs in exactly one mode, chosen by the VIEWER_MODE env var (private or public; any other value, including unset, is fail-closed and 500s every request).

• Private mode: every route requires a per-user token. Send it as an Authorization: Bearer <token> header, or as the control_tower_admin_session cookie that the web login sets. Tokens live in the deployment's own <MONGO_DB>_auth.users collection; any valid token grants the full read/write surface (there are no scopes or roles yet). There is no HTTP Basic auth.
• Public mode: reads need no credential; the data layer narrows what is visible. Writes are refused with 403 by construction, and a few read routes that would expose full .eval archives also 403 (see the download routes below).

Get a token with the CLI (ct login caches one locally; CONTROL_TOWER_API_TOKEN overrides the cache for CI), or directly:

curl -sX POST "$BASE_URL/api/auth/login" \
  -H 'content-type: application/json' \
  -d '{"username": "you", "password": "..."}'
# => {"token": "..."}

A missing or invalid token on a private deployment returns 401 {"error": "Unauthorized"}. The CLI branches on status alone — 401 prints a "run ct login" hint.

Wire conventions

• snake_case everywhere on the wire. Query params, request-body fields, and response fields are all snake_case (total_count, page_size, ids_only, task_set, run_id). camelCase is a TypeScript-internal convention that never appears in HTTP.
• Unknown query params fail loudly. Each route declares its allowed param names; any param outside that set is a 400 that names the offender and, when the fix is an obvious camelCase→snake_case slip, suggests the right spelling (e.g. {"error": "Unknown query param: 'pageSize' (did you mean 'page_size'?)"}). The suggestion is message text only, never an accepted alias. Routes that take no params reject any query param.
• Uniform list shape. Every list response is {"items": [...], "total_count": N, "page": P, "page_size": S, "total_pages": T}.
• Every list response is bounded. No request returns a whole collection. limit=N is "the newest N" (page one at N); page+page_size paginate (both or neither); a request that supplies neither is page one at the maximum page size (500). All three clamp to that maximum. total_count is always the true match count and page_size/total_pages describe the window you got, so a caller that wants everything can see how much it did not get and page for the rest — it never has to know the server's ceiling.
• Single documents are returned bare — the document itself, with no {data, meta} envelope.
• Errors are {"error": "<human message>"} plus the correct HTTP status. There are no machine-readable error codes; clients branch on status (400, 401, 403, 404, 409, 413, 502).

Route surface

Trajectories

Runs

Comments

Comments are their own append-only sub-resource, never a merge-patch field. The same Comment entity hangs off three parents — a run, a whole trajectory, and a single step (keyed by tool_call_id) — and all three expose the identical three methods.

Shared semantics across all nine:

• The client sends only text. POST and PATCH take {"text": "..."} and nothing else; a body without a string text is a 400. PATCH accepts an empty string. DELETE takes no body.
• Identity and clock are server-owned. The comment's id, created_by/created_at, edited_by/edited_at, and deleted_by/deleted_at are all stamped from the authenticated actor and the server clock; a client cannot set or spoof them.
• Delete is soft. The comment and its text are retained with deleted_at/deleted_by set, so the audit trail survives.
• Responses: POST returns 201 with the new comment; PATCH returns 200 with the updated comment; DELETE returns 200 {"ok": true}. An unknown parent, an unknown comment id, or a comment that is already soft-deleted is a 404; a tool_call_id outside [A-Za-z0-9_-]+ is a 400.

Datasets

Datasets are named, versioned collections of run ids or trajectory ids. The version number is assigned by the server on publish (the client never picks it), which removes the read-then-insert race the old client-side path had.

Sabotage evals

Eval logs (S3 brokering)

Auth

AI (Markdown for agents)

GET /api/ai/runs, GET /api/ai/trajectories, and GET /api/ai/trajectories/{id} return the same data as Markdown for LLM agents, over the same filters and auth as the JSON routes. /llms.txt is the agent-facing entry point: it self-describes the data model, endpoints, and wire contract, and agents re-discover it each session. It is the source of truth for the AI surface.

Raw sample byte stream

GET /api/trajectories/{id}/sample streams the raw, still-compressed .eval sample bytes verbatim over a chunked 200 — a format-agnostic byte proxy. The server does no decompression, parsing, or derivation: it forwards the compressed sample member straight from S3, so the ~1 MB compressed payload crosses the wire instead of the hundreds of MB it inflates to, and the function never holds the decompressed sample in memory. The client inflates and derives the transcript itself (a Web Worker, in the browser).

Response headers:

• Content-Type: application/octet-stream.
• X-Sample-Compression: <codec> — names the codec so the client knows how to inflate (derived from the .eval ZIP member's compression method).
• Content-Encoding: identity — the payload is already compressed; this stops the platform from re-encoding it.
• Cache-Control: no-store.

Failures split on when they happen relative to the committed 200:

• Before the stream starts (bad id, missing document, S3 open failure, or an unsupported ZIP compression method): a plain {"error": ...} JSON body with a 400/404/502 status — no stream.
• After the 200 is committed: the status is already sent, so a failure can only truncate the byte stream. The client's derivation surfaces the truncation as an error — a transcript that decodes without a terminating summary is treated as truncated, not complete.

PATCH (merge-patch) semantics

PATCH /api/runs/{id} and PATCH /api/trajectories/{id} apply JSON merge-patch over a strict field whitelist, shared with the website's edit actions so the two can't drift:

• Runs: name, tags, description, policy.
• Trajectories: description, tags, attack_analysis.

These are singleton fields only. Comments are their own sub-resource (see above) and dataset membership lives in a dataset version's item_ids (edited by publishing a version) — neither is patchable here.

Rules:

• An absent field is left unchanged.
• An explicit null clears a field, and is legal only on nullable fields (description and policy on runs, attack_analysis on trajectories); a null anywhere else is a 400. A run's name may not be set empty.
• Arrays replace wholesale — there are no add/remove operations, so read-modify-write is the client's job.
• Unknown fields are a 400, never silently ignored.
• The response is the updated document. PATCH /api/runs/{id} returns the run (same shape as its GET); PATCH /api/trajectories/{id} returns the {metadata} overlay only — a metadata edit never touches the S3 sample, so it is neither fetched nor returned (use GET for the full {metadata, sample} bundle, avoiding a post-write 502 if S3 is unavailable). An unknown id is a 404.

Register semantics

POST /api/trajectories/register is the single write path for run headers and trajectory documents (the CLI's ct run eval, ct runs make, ct run monitor, and ct traj upload all end here). The body is {run?, trajectories, eval_log_sizes?, client, schema_version}.

• Schema handshake: schema_version must equal the version the server supports, else 400 with a "your control-tower checkout is incompatible — run git pull" message. This is the G4 fail-loud mechanism for the upload contract.
• Eval logs must exist first: the server HEAD-verifies every referenced .eval object is already in S3 (add-only, S3-then-Mongo ordering); a missing object is a 400.
• Idempotent retries: if all posted trajectory ids already exist, the call returns 200 {"ok": true, "already_registered": true} — a lost response followed by a retry reads as the success it is. Partial overlap (some ids exist, some don't) stays a 409 because it is a genuine anomaly.
• Registration carries no dataset membership, so there is no lock check here. Membership lives in a dataset version's item_ids, and the lock gate sits on the publish path (POST /api/datasets/{name}/versions, a 409 when locked). Locks are an accident interlock, not authorization — there is no client-side check and no bypass flag; the only path into a locked dataset is to unlock it first.
• The run header is create-once. Re-registering an existing run_id does not rewrite the header — the run_id is the idempotency key, and header fields change only through the audited PATCH. Trajectories are inserted before the run header is upserted, so a trajectory conflict never commits a run header pointing at missing trajectories.
• The run header is optional; run_id is a soft reference. run may be omitted (ct traj upload posts trajectories with run=null), in which case only the trajectory documents are written and no run header is created. Each trajectory keeps its client-supplied run_id verbatim — it is never force-emptied and never triggers an auto-created run header — so a run_id that resolves to no run is a legitimate shape. Readers treat the reference as soft: run-less trajectories list and render normally, and a dangling run_id never fabricates a run (GET /api/runs/{id} for such an id is a 404, and the trajectory-detail "Run" link points at a plain /runs/<run_id> 404).

Presigned .eval downloads

Raw .eval archive reads are brokered, never streamed through the function: GET /api/trajectories/{id}/eval authenticates the token, then returns a 302 redirect to a short-TTL presigned S3 GET (Cache-Control: no-store). The client — browser or CLI — follows the redirect and downloads straight from S3, so no AWS credentials ever leave the server and the API token stays the only long-lived client credential. The CLI follows the redirect manually so its Authorization header never travels to S3.

In public mode this route returns 403 ("Full .eval archive download is unavailable in public mode"), as does the run_id-scoped ZIP export — public deployments do not hand out whole eval archives.

Operator workflow (ops/)

Nothing in the application or the CLI provisions Mongo indexes, seeds data, or manages login accounts on its own. Those are deliberate, out-of-band operator steps performed by someone holding write credentials for a cluster, and they live in the standalone ops/ package (the single ct-ops console script, with a subcommand per step): index provisioning, viewer login accounts, cluster copy for the viewer cutover, and local seed data. ops/ is a separate package with its own venv and zero control_tower imports. See ops/README.md for the full workflow.

Self-hosting the viewer

There is no separate "API client" viewer mode and no second implementation. A downstream user who wants their own viewer self-hosts the same Next.js app over their own MongoDB — their deployment is their API, and their CLI points at their deployment's URL (CONTROL_TOWER_API_BASE_URL). MONGOURI lives only in each deployment's own server environment (Vercel env, a self-hosted container, or ops/); it is never handed to a client. That MongoDB must be a replica set (single-node is fine), not a standalone mongod, so register's transaction has somewhere to run — see Database — replica-set requirement. See Web Viewer for the self-hosting quickstart and packages/viewer/README.md for the library shape and env vars.