HTTP API Overview

The WarmHub HTTP API exposes mounted JSON endpoints for repository reads, action observability, callbacks, MCP HTTP transport, and SSE.

Repository data writes and management operations are not REST CRUD endpoints. Use the SDK, CLI, or MCP tools for those workflows.

Base URL

Most REST endpoints use the /api prefix:

https://api.warmhub.ai/api/

Root-mounted transports use the origin without /api:

https://api.warmhub.ai/mcp
https://api.warmhub.ai/sse

For example, the repository HEAD endpoint is:

https://api.warmhub.ai/api/repos/acme/world/head

Authentication

Authenticated endpoints require an Authorization header with a Bearer token:

curl -H "Authorization: Bearer <token>" \
  https://api.warmhub.ai/api/repos/acme/world/head

Repository data read endpoints (/head, /about/:wref, /query) on public repositories can be read anonymously; the same endpoints on private repos require authentication. Action-observability endpoints (/api/repos/:org/:repo/actions/*) and MCP POST endpoints (POST /mcp, POST /mcp/:org/:repo) always require authentication regardless of repo visibility — see the per-endpoint Auth column in the tables below.

PAT management REST endpoints are not currently mounted. Create and manage PATs with the CLI (wh token) or the SDK (client.token.*); see Authentication.

Request Format

• Content-Type: application/json for JSON request bodies
• Path parameters: URL-encoded (for example, Shape%2FMyShape for Shape/MyShape)
• Query parameters: Standard URL query string format

Response Format

Repository read and action observability endpoints return JSON on success. The /sse endpoint streams text/event-stream, and MCP endpoints follow JSON-RPC over HTTP.

Most REST errors use this envelope:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Thing not found: Sensor/temp-1"
  }
}

HTTP Status	Common Error Codes
400	VALIDATION_ERROR, SHAPE_MISMATCH, RESERVED_NAME, ILLEGAL_OP_SEQUENCE
401	UNAUTHENTICATED
403	FORBIDDEN
404	NOT_FOUND
409	CONFLICT, ARCHIVED
429	RATE_LIMITED
500	INTERNAL_ERROR

SDK callers receive these as WarmHubError.code / kind. See the ErrorKind reference for retryability and corrective actions per kind.

Repository read endpoints (/head, /about/:wref, /query) collapse missing-repo and unauthorized-private-repo cases into the same 404 so repo existence stays opaque. See Queries for the full deny-path behavior.

Transport-specific endpoints can use their own error shape. For example, early /sse failures return a simple string-valued error object.

When REST endpoints return 429 RATE_LIMITED, they may include a Retry-After response header. Clients should back off until that interval has elapsed.

Pagination

Repository query endpoints support cursor-based pagination with limit and cursor. Action endpoints support limit and since filtering.

Parameter	Description
limit	Maximum number of items to return per page.
cursor	Opaque pagination token from a previous response’s nextCursor field.
since	Filter action records after this epoch-milliseconds timestamp.

Mounted Endpoints

Endpoints marked None are publicly accessible for public repositories. Private repositories require a valid Bearer token.

Repository Reads

Method	Path	Description	Auth
GET	/api/repos/:org/:repo/head	HEAD snapshot	None
GET	/api/repos/:org/:repo/about/:wref	Assertions about a thing	None
GET	/api/repos/:org/:repo/query	Filtered query	None

Action Observability

Method	Path	Description	Auth
GET	/api/repos/:org/:repo/actions/runs	List action runs	repo:configure
GET	/api/repos/:org/:repo/actions/runs/:runId/attempts	Get run attempts	repo:configure
GET	/api/repos/:org/:repo/actions/notifications	List action notifications (terminal failures, plus successes when notifyOnSuccess is enabled)	repo:configure
POST	/api/action-runs/:runId/callback	Report async action progress or completion	repo:write

MCP And Streaming

Method	Path	Description	Auth
POST	/mcp	MCP HTTP transport (GET returns 405)	Bearer token
POST	/mcp/:orgName/:repoName	Repo-scoped MCP HTTP transport (GET returns 405)	Bearer token
GET	/sse	Server-sent invalidation stream with a live ticket	Live ticket

Component Registry Install Handshake

Method	Path	Description	Auth
POST	/api/component-registry/:orgName/:componentName/resolve	Check install eligibility and mint an install id	things:write on the install repo
POST	/api/component-registry/:orgName/:componentName/source	Download the component source archive through the backend	things:write on the install repo
POST	/api/component-registry/:orgName/:componentName/setup-call	Dispatch the optional registered-component setup callback	things:write on the install repo

Not Mounted As REST

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

Surface	Use Instead
Commit writes	SDK commit APIs, wh commit submit, or warmhub_commit_submit
Shape management	SDK shape APIs, wh shape, or commit writes
Organization and repository management	CLI org/repo commands or SDK org/repo APIs
Subscription management	Subscription CLI/MCP workflows
Credential set management	Credential CLI workflows
PAT management	Personal Access Tokens guide