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.

WarmHub does not currently publish an OpenAPI specification. For exact request and response shapes, see the documentation in this section or the SDK reference.

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 on the Endpoints page.

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
413	PAYLOAD_TOO_LARGE
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.

A 413 PAYLOAD_TOO_LARGE is returned when a request body exceeds the endpoint’s size limit. The SDK’s write helpers stay under the limit automatically, so you generally only see this on oversized requests built by hand.

Idempotency and retries

GET endpoints — repository reads and action observability — are idempotent. Retrying one returns the same result with no side effects, so they are always safe to retry after a network error.

When a request returns 429 RATE_LIMITED, the response may carry a Retry-After header. The same value is mirrored in the body as error.retryAfter (in seconds). Back off until that interval has elapsed before retrying.

The action callback endpoint, POST /api/action-runs/:runId/callback, is safe to retry with the same status: re-reporting a status the run has already reached succeeds without repeating side effects such as notifications. Reporting a status that conflicts with the run’s current state returns 409 CONFLICT. A retry_requested status is the exception — it is a command, not a report, so each accepted one queues a new delivery attempt and it is rejected once the run’s attempts are exhausted.

WarmHub does not accept an inbound Idempotency-Key header. For action delivery, WarmHub sends your webhook handler an X-WarmHub-Idempotency-Key header so the handler can recognize and discard duplicate deliveries.

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.

Endpoint reference

See Endpoints for the complete map of mounted endpoints with their auth requirements, plus the surfaces that are handled through the SDK, CLI, and MCP rather than REST.