HTTP reference
83 endpoints, read at build time out of the endpoint tables in 13 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 13 of 24 specifications contribute at all.
Carrying no endpoint section, and therefore no rows below:
SPEC-0008The cairn Command-Line InterfaceSPEC-0012Outbound WebhooksSPEC-0013GitHub Login for the Web App ShellSPEC-0014Prometheus MetricsSPEC-0015Embedded Documentation ServingSPEC-0016Annotation and Trace Lifecycle EventsSPEC-0017Secret Detection and Redaction at IngestSPEC-0019Actionable Validation ErrorsSPEC-0024Artifact Relations and Trace ContextSPEC-0025Artifact Assignment
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 |
SPEC-0020 Opt-In Permanent Retention
Derived from Endpoint Table
| Method | Path | Purpose | Auth |
|---|---|---|---|
| POST | /v1/artifacts/{id}/retain | Make permanent | Required: owner (or team admin); agents need retention:write plus the operator gate |
| POST | /v1/artifacts/{id}/release | Return to ephemeral with a bounded TTL | Required: owner (or team admin); sharing:manage, human-only |
| DELETE | /v1/artifacts/{id} | Delete; tombstones when ever-retained | Required: owner, human-only (unchanged) |
| GET | /v1/retention/usage | Caller's (or a team's) usage and limits | Required |
| GET | /v1/artifacts/{id} | Read; 410 + tombstone for a tombstoned id | Public: the capability URL is the read token (ADR-0007); a tombstone discloses only to a link holder |
| GET | /{id} | Web shell; 410 tombstone page | Public: same capability-URL rationale |
SPEC-0021 Structured Receipts
Derived from Endpoint Table
| Method | Path | Purpose | Auth |
|---|---|---|---|
| POST | /v1/receipts | Create a structured receipt | Required: artifacts:write (humans and agents) |
| GET | /v1/artifacts/{id} | Read, including metadata | Public: the capability URL is the read token (ADR-0007) |
| GET | /{id} | Web shell with the receipt card | Public: same capability-URL rationale |
SPEC-0022 Search, Semantic Search, and Export by Tag
Derived from Endpoint Table
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /v1/search | Ranked or list search over the caller's reachable artifacts | Required: artifacts:read; agents subject to CAIRN_SEARCH_AGENTS |
| GET | /(Bin) with ?q= | Web search results | Required: web session |
SPEC-0023 Teams and Tenancy
Derived from HTTP Endpoints
| Method | Path | Purpose | Auth |
|---|---|---|---|
| POST | /v1/teams | Create a team | Required (session or token with teams:manage) |
| GET | /v1/teams | List the caller's teams | Required |
| GET | /v1/teams/{slug} | Team detail | Required, member |
| PATCH | /v1/teams/{slug} | Rename | Required, owner |
| DELETE | /v1/teams/{slug} | Delete team | Required, owner, browser session |
| GET | /v1/teams/{slug}/members | List members | Required, member |
| PATCH | /v1/teams/{slug}/members/{user} | Change role | Required, admin (owner for owner) |
| DELETE | /v1/teams/{slug}/members/{user} | Remove or leave | Required, admin, or self |
| POST | /v1/teams/{slug}/invites | Invite | Required, admin |
| GET | /v1/teams/{slug}/invites | List pending invites | Required, admin |
| DELETE | /v1/teams/{slug}/invites/{id} | Revoke invite | Required, admin |
| GET | /invites/{token} | Invite page | Required (session), addressee |
| POST | /invites/{token}/accept | Accept | Required (session), verified email match |
| PUT | /v1/teams/{slug}/group-link | Link or unlink an OIDC group | Required, owner |
| POST | /v1/artifacts/{id}/move | Move a personal artifact into a team | Required, owner of the artifact, member of the team |
| GET | /v1/subscriptions | List the caller's and their admin teams' subscriptions | Required |
| POST | /v1/subscriptions | Create a subscription (secret shown once) | Required; admin for a team owner |
| PATCH | /v1/subscriptions/{id} | Pause, resume, change filters | Required, subscription owner scope |
| POST | /v1/subscriptions/{id}/rotate | Rotate the secret | Required, subscription owner scope |
| DELETE | /v1/subscriptions/{id} | Delete | Required, subscription owner scope |
| GET | /operator | Operator console | Required, operator |
| GET | /v1/operator/directory | Users and teams with counts | Required, operator |
| POST | /v1/operator/suspensions | Suspend or unsuspend | Required, operator |
| PUT | /v1/operator/quotas/{scope} | Per-owner quota | Required, operator |
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 |