HTTP reference
48 endpoints, read at build time out of the endpoint tables in 9 specifications. Nothing on this page is typed by hand; adding a row to a specification adds it here.
This is not the whole API. It is every row of every endpoint table the specifications carry under a section named HTTP Endpoints, REST Endpoints, Endpoint Table and Web Routes. A specification that documents its surface some other way contributes nothing, and 9 of 15 specifications contribute at all.
Carrying no endpoint section, and therefore no rows below:
Carrying an endpoint section that is deliberately out of scope — a route map for this website rather than a service API:
SPEC-0001 Web App Shell and the Bin
Derived from Web Routes
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /{id} | Render the artifact shell (header · panel · registry-selected body) | Publiclink-based capability read (ADR-0007); unknown/unauthorized/expired ids return a uniform 404 |
| GET | /run/{id} | Render the trajectory shell (/run/ sub-path per SPEC-0002) | Publicsame link-capability justification |
| GET | /bin(and /) | Render the Bin listing (keyset paginated) | Requiredworkspace-scoped listing |
| GET | /{id}/share | Render the Share dialog partial | Requiredonly the owner may open sharing controls |
| GET | /{id}/comments | Load-more comments partial (HTMX) | Publicannotation read is granted by the same capability link as the artifact |
SPEC-0002 Artifact Core and Share Types
Derived from REST Endpoints
| Method | Path | Purpose | Auth |
|---|---|---|---|
| POST | /v1/artifacts | Create an artifact; streams the body to storage with checksum verification (ADR-0008) | Required |
| GET | /v1/artifacts/{id} | Fetch metadata + preview payload for the resolved share type | Publiclink-based capability read (ADR-0007); unknown/unauthorized/expired ids return a uniform 404 |
| GET | /v1/artifacts/{id}/body | Download raw body bytes (re-verifiable against the stored SHA-256) | Publicsame link-capability justification |
| GET | /v1/artifacts/{id}/members/{name} | Read a bundle member <bundle_id>/<name> (web tabs / MCP) | Publicsame link-capability justification |
| DELETE | /v1/artifacts/{id} | Delete an artifact (owner only; also honors expiry) | Requiredowner only |
| POST | /v1/artifacts/{id}/share | Set/adjust link access policy or rotate the id (ADR-0007) | Requiredowner only; no sharing:manage for agents |
| GET | /v1/bin | List the Bin, keyset-paginated over (created_at, id), optionally narrowed to artifacts carrying every ?tag= | Requiredworkspace-scoped |
SPEC-0003 Artifact Viewers
Derived from HTTP Endpoints
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /{id}(web) | Render the app shell + resolved body viewer | Publicgated by link capability (ADR-0007); returns 404/403 without it |
| GET | /v1/artifacts/{id} | Fetch metadata + rendered/preview payload for a viewer | Publicgated by link capability (ADR-0007) |
| GET | /v1/artifacts/{id}/body | Download raw, checksum-verifiable bytes (file/bundle download) | Publicgated by link capability (ADR-0007) |
SPEC-0004 Trajectory Share
Derived from HTTP endpoints
| Method | Path | Purpose | Auth |
|---|---|---|---|
| POST | /v1/runs | Ingest a run — a complete run (batch) or open a live run | Required |
| POST | /v1/runs/{id}/spans | Append one or more spans to an open run (incremental) | Required |
| POST | /v1/runs/{id}/close | Close an open run (stamp ended_at, freeze derived stats) | Required |
| GET | /v1/runs/{id} | Fetch run metadata, span tree, and derived stats | Link-cap |
| GET | /v1/runs/{id}/spans/{span_id}/output | Lazily fetch a span's large (output_ref) output | Link-cap |
| GET | /v1/runs/{id}/stream | SSE: live span-append events for an open run (ADR-0009/ADR-0012) stream | Link-cap |
SPEC-0005 Webhook Inspector
Derived from HTTP endpoints
| Method | Path | Purpose | Auth |
|---|---|---|---|
| POST | /v1/hooks | Create a webhook endpoint (owner); returns id, ingress URL, mcp://cairn/hook/<id> | Required |
| GET | /v1/hooks/{id} | Endpoint metadata + recent request buffer | Link-cap |
| GET | /v1/hooks/{id}/requests | List captured requests (keyset paginated, seq order) | Link-cap |
| GET | /v1/hooks/{id}/requests/{seq} | Full detail of one captured request (metadata + body ref) | Link-cap |
| GET | /v1/hooks/{id}/requests/{seq}/body | Raw captured body bytes (lazy, checksum-verifiable) | Link-cap |
| GET | /v1/hooks/{id}/stream | SSE: live captured requests (ADR-0010/ADR-0012) stream | Link-cap |
| ANY | /h/{id}(also hook.cairn.stump.wtf/{id}) | Ingress: capture an inbound request of any method | Public |
SPEC-0006 Annotations — Reactions & Comments
Derived from HTTP Endpoints
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /v1/artifacts/{id}/reactions | List reactions (grouped tallies + "did I react") | Publicgated by artifact link capability (ADR-0007) |
| POST | /v1/artifacts/{id}/reactions | React (idempotent; registry-gated anchor) | Required |
| DELETE | /v1/artifacts/{id}/reactions/{rid} | Un-react (delete own reaction) | Required |
| GET | /v1/artifacts/{id}/comments | List comment threads for the artifact | Publicgated by artifact link capability (ADR-0007) |
| POST | /v1/artifacts/{id}/comments | Comment (registry-gated anchor; refused on non-commentable types) | Required |
SPEC-0007 MCP Server and OAuth Authorization
Derived from Endpoint Table
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /.well-known/oauth-authorization-server | AS metadata (RFC 8414) discovery | Publicclients must read metadata before they can authenticate; contains no secrets |
| GET | /.well-known/oauth-protected-resource | Protected-resource metadata | Publicsame discovery bootstrap; no secrets |
| POST | /oauth/register | Dynamic Client Registration (RFC 7591) | PublicDCR must accept unregistered clients per the MCP auth spec; rate-limited, redirect-URI validated |
| GET | /oauth/authorize | Render login + consent screen | Requiredhuman session; unauthenticated visitors are redirected to login |
| POST | /oauth/authorize | Submit consent (approve/deny) | Requiredhuman session + CSRF token |
| POST | /oauth/token | Code exchange, refresh rotation | Client-authenticated (PKCE)no Cairn session; authenticated by PKCE code_verifier / client credentials |
| POST | /oauth/revoke | Revoke a grant's tokens (RFC 7009) | Client-authenticatedpresented token + client credentials authenticate the call |
| POST / GET (SSE) | /mcp | MCP transport: tools + resource reads stream | RequiredOAuth 2.1 bearer access token, audience-bound to Cairn |
SPEC-0009 Provenance, Link-Based Access, and Retention
Derived from Endpoint Table
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /{id} | Resolve + read an artifact/bundle by capability-URL | Publicthe capability-URL is the read token (ADR-0007); unguessable id + uniform 404 + rate limit |
| GET | /run/{id} | Read a trajectory by capability-URL | Publicsame capability-URL rationale |
| POST | /{id}/annotations | Post a comment/reaction | Requiredannotation is never anonymous |
| PATCH | /{id}/policy | Change sharing (e.g. owner-only) | Requiredowner only |
| PATCH | /{id}/ttl | Change expiry / extend / no-expiry | Requiredowner only |
| POST | /{id}/rotate | Rotate the id (revoke a leaked link) | Requiredowner only |
SPEC-0011 OTLP Trace Ingestion
Derived from HTTP endpoints
| Method | Path | Purpose | Auth |
|---|---|---|---|
| POST | /v1/otlp/v1/traces | OTLP/HTTP trace export → native run/span ingest | Required |
Streaming
The rows above that the specifications describe as server-sent event streams rather than as request/response calls — an SSE method, an SSE purpose, or a /stream path. This is a view of this page, so it inherits this page's scope: a stream a specification documents outside an endpoint table is not here either.
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /v1/runs/{id}/stream | SSE: live span-append events for an open run (ADR-0009/ADR-0012) stream | Link-cap |
| GET | /v1/hooks/{id}/stream | SSE: live captured requests (ADR-0010/ADR-0012) stream | Link-cap |
| POST / GET (SSE) | /mcp | MCP transport: tools + resource reads stream | RequiredOAuth 2.1 bearer access token, audience-bound to Cairn |