Skip to content

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:*.

MethodPathDescriptionAuth
GET/api/graphs/:orgName/:graphName/headHEAD snapshotNone
GET/api/graphs/:orgName/:graphName/about/:wrefAssertions about a thingNone
GET/api/graphs/:orgName/:graphName/queryFiltered queryNone
GET/api/graphs/:orgName/:graphName/exportExport 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

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:

ParameterValuesDescription
preferasyncStart an async export job instead of streaming synchronously
token<exportToken>Fetch a previously started async export job
modeheads (default)What to export. heads is the only mode available; ops is not yet available and returns 501 (export-mode-not-enabled)
sinceGraphSeqinteger, default 0Export only what changed after this graph sequence. 0 exports everything
atGraphSeqintegerPin 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
afterDurableIddurable IDResume 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
afterVersionpositive integerWith 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
formatVersionintegerRequired 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
MethodPathDescriptionAuth
GET/api/graphs/:orgName/:graphName/actions/runsList action runsrepo:configure
GET/api/graphs/:orgName/:graphName/actions/runs/:runId/attemptsGet run attemptsrepo:configure
GET/api/graphs/:orgName/:graphName/actions/notificationsList graph-scoped action notification records for terminal failuresrepo:configure
POST/api/action-runs/:runId/callbackReport async action progress or completionrepo:action-callback (graph-scoped runs); org:action-callback (org-scoped runs)
MethodPathDescriptionAuth
POST/mcpMCP HTTP transport (GET returns 405)Bearer token required for some tools; others are accessible without credentials. See MCP Server for details.
GET/sseServer-sent invalidation stream with a live ticketLive ticket
POST/api/graphs/:orgName/:graphName/streams/:streamId/submissionsNDJSON streaming submission routerepo:write

Note: The NDJSON submission route (/streams/:streamId/submissions) is enabled per graph. On a graph where it is not enabled it answers 404 — the same response as an unknown path, so a 404 here does not distinguish “not enabled” from “no such graph”.

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.

MethodPathDescriptionAuth
POST/api/component-registry/:orgName/:componentName/resolveResolve the latest manifest and check install eligibilityrepo:write on the install graph
POST/api/component-registry/:orgName/:componentName/setup-callDispatch the optional registered-component setup callbackrepo:write on the install graph
POST/api/component-registry/:orgName/:componentName/cli/:methodDispatch 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 gets 404, even when the graph is public. A private component additionally requires membership in the org that owns it; non-members get 404. Component tokens cannot call this route and get 401.

These surfaces are intentionally documented through SDK, CLI, and MCP workflows rather than REST endpoint references:

SurfaceUse Instead
Shape managementSDK shape APIs, wh shape, or commit writes
Organization and graph managementCLI org/graph commands or SDK org/graph APIs
Graph writesWrites
Subscription managementSubscription CLI/MCP workflows
Credential set managementCredential CLI workflows
PAT managementPersonal Access Tokens guide

A few other mounted routes are documented on the pages that own those surfaces, so they are not repeated here:

RoutesDocumented 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-serverMCP Server
Raw graph content — /:org/:graph/readme.md, /:org/:graph/agents.md, /:org/:graph/llms.txtContent shapes