Endpoints
This page maps WarmHub’s mounted REST endpoints for graph reads, action observability, component installs, and the MCP and streaming transports. Most rows link to the page that documents the endpoint in detail. A few mounted routes are owned by other pages — see Documented elsewhere below. For base URL, authentication, request and response format, idempotency, and pagination, see the Overview.
Endpoints marked None are publicly accessible for public graphs. Private graphs require a valid Bearer token. Graphs were formerly called repos, which is why the PAT scopes below are still spelled repo:*.
Graph Reads
Section titled “Graph Reads”| Method | Path | Description | Auth |
|---|---|---|---|
GET | /api/graphs/:orgName/:graphName/head | HEAD snapshot | None |
GET | /api/graphs/:orgName/:graphName/about/:wref | Assertions about a thing | None |
GET | /api/graphs/:orgName/:graphName/query | Filtered query | None |
GET | /api/graphs/:orgName/:graphName/export | Export graph contents as NDJSON; supports synchronous streaming, starting an async export job (prefer=async), and fetching a finished async export with the returned token (token=<exportToken>) | repo:read (unrestricted) and repo:checkpoint-read; not available to component tokens |
Graph Export
Section titled “Graph Export”GET /api/graphs/:orgName/:graphName/export
Exports the contents of a graph. The endpoint has three response modes selected by query parameters:
Synchronous NDJSON stream (default)
Omit both prefer and token. The server streams the export as NDJSON directly in the response body.
Start an async export job (prefer=async)
Pass prefer=async. The server starts an async export job and returns 202 immediately:
{ "exportToken": "<token>", "atGraphSeq": 42 }Use the returned exportToken to poll for completion.
Fetch a finished async export (token=<exportToken>)
Pass token=<exportToken> (the value from the job-start response). While the job is still building, the server returns 202. The state field will be either pending (queued, not yet started) or running (actively building):
{ "state": "pending" }{ "state": "running" }Continue polling on any 202 response regardless of the state value.
Once the job is complete, the server returns 200 application/json with a signed download URL and metadata:
{ "url": "<signed-storage-url>", "expiresAt": 1718000000000, "atGraphSeq": 42, "recordCount": 1234, "contentSha256": "<hex digest>"}expiresAt is a Unix timestamp in milliseconds (a JSON number). Download the NDJSON export directly from the url in the response. The URL expires at expiresAt.
Auth: repo:checkpoint-read plus unrestricted repo:read. A token whose repo:read is narrowed to particular refs or shapes gets a 403 from this endpoint even when repo:checkpoint-read is also present — see Personal access tokens for how scope narrowing works.
Component tokens cannot use this endpoint at all. A component call returns 403 on both the synchronous stream and the async paths whatever scopes the token carries, including repo:checkpoint-read with unrestricted repo:read. A component that needs graph bytes must have a user or PAT-backed caller drive the export.
Query parameters:
| Parameter | Values | Description |
|---|---|---|
prefer | async | Start an async export job instead of streaming synchronously |
token | <exportToken> | Fetch a previously started async export job |
mode | heads (default) | What to export. heads is the only mode available; ops is not yet available and returns 501 (export-mode-not-enabled) |
sinceGraphSeq | integer, default 0 | Export only what changed after this graph sequence. 0 exports everything |
atGraphSeq | integer | Pin the export to this graph sequence. Omit it and the server pins the current committed sequence and echoes it in the export header, so you can resume against the same pin |
afterDurableId | durable ID | Resume a synchronous stream after the last whole row you received (exclusive). Requires the atGraphSeq the opening header pinned, and formatVersion. Refused with prefer=async or token |
afterVersion | positive integer | With afterDurableId only: when the last row you received was a Shape version, the version number, so the stream continues with that Shape’s later versions |
formatVersion | integer | Required with afterDurableId: the formatVersion from the opening header. A resume whose value does not match the server’s current export format is refused with 412; restart the export instead |
Action Observability
Section titled “Action Observability”| Method | Path | Description | Auth |
|---|---|---|---|
GET | /api/graphs/:orgName/:graphName/actions/runs | List action runs | repo:configure |
GET | /api/graphs/:orgName/:graphName/actions/runs/:runId/attempts | Get run attempts | repo:configure |
GET | /api/graphs/:orgName/:graphName/actions/notifications | List graph-scoped action notification records for terminal failures | repo:configure |
POST | /api/action-runs/:runId/callback | Report async action progress or completion | repo:action-callback (graph-scoped runs); org:action-callback (org-scoped runs) |
MCP And Streaming
Section titled “MCP And Streaming”| Method | Path | Description | Auth |
|---|---|---|---|
POST | /mcp | MCP HTTP transport (GET returns 405) | Bearer token required for some tools; others are accessible without credentials. See MCP Server for details. |
GET | /sse | Server-sent invalidation stream with a live ticket | Live ticket |
POST | /api/graphs/:orgName/:graphName/streams/:streamId/submissions | NDJSON streaming submission route | repo:write |
Note: The NDJSON submission route (
/streams/:streamId/submissions) is enabled per graph. On a graph where it is not enabled it answers404— the same response as an unknown path, so a404here does not distinguish “not enabled” from “no such graph”.
Component Registry
Section titled “Component Registry”The first two routes are the install handshake. cli/:method is the transport behind wh component exec — see the CLI reference for how to invoke component methods.
| Method | Path | Description | Auth |
|---|---|---|---|
POST | /api/component-registry/:orgName/:componentName/resolve | Resolve the latest manifest and check install eligibility | repo:write on the install graph |
POST | /api/component-registry/:orgName/:componentName/setup-call | Dispatch the optional registered-component setup callback | repo:write on the install graph |
POST | /api/component-registry/:orgName/:componentName/cli/:method | Dispatch an installed component’s CLI method (via wh component exec) | Membership in the install graph’s org and repo:read on the install graph, plus any per-method permission the method declares |
Note: For
cli/:method, a caller who is not a member of the install graph’s org gets404, even when the graph is public. A private component additionally requires membership in the org that owns it; non-members get404. Component tokens cannot call this route and get401.
Not Mounted As REST
Section titled “Not Mounted As REST”These surfaces are intentionally documented through SDK, CLI, and MCP workflows rather than REST endpoint references:
| Surface | Use Instead |
|---|---|
| Shape management | SDK shape APIs, wh shape, or commit writes |
| Organization and graph management | CLI org/graph commands or SDK org/graph APIs |
| Graph writes | Writes |
| Subscription management | Subscription CLI/MCP workflows |
| Credential set management | Credential CLI workflows |
| PAT management | Personal Access Tokens guide |
Documented elsewhere
Section titled “Documented elsewhere”A few other mounted routes are documented on the pages that own those surfaces, so they are not repeated here:
| Routes | Documented on |
|---|---|
MCP OAuth metadata — /.well-known/oauth-protected-resource, /.well-known/oauth-protected-resource/mcp, /mcp/.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server | MCP Server |
Raw graph content — /:org/:graph/readme.md, /:org/:graph/agents.md, /:org/:graph/llms.txt | Content shapes |