HTTP API Overview

The WarmHub HTTP API provides direct access to platform operations — querying data, committing changes, managing shapes, subscriptions, and personal access tokens. Organization and repository management is available via the CLI and SDK. All endpoints accept and return JSON.

Base URL

All API paths are relative to:

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

For example:

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

WarmHub supports two token types:

Type	Obtained via	Use case
JWT	Interactive login (WorkOS)	Browser sessions, credential management
PAT	POST /api/pats	Scripts, CI/CD, programmatic access

PAT tokens carry resource-scoped permissions that limit what they can do. Each scope entry binds a resource (repo or org) to a set of permissions:

Scope	Grants
repo:read	Read repositories, queries, shapes
repo:write	Commits, shape mutations
repo:configure	Subscriptions, credentials, repo settings
repo:admin	Delete, archive, visibility
org:read	Read org profiles
org:configure	Create repos, manage members
org:admin	Rename, archive org

Scopes are independent — repo:write does not include repo:read. Request the specific scopes your token needs.

Scope entries can target a specific repo ("myorg/myrepo"), an entire org ("myorg"), or all resources (global wildcard with no resource field). More specific entries take precedence. Scopes can only narrow access, never escalate beyond the user’s role. A token created without scopes has full user access.

JWT tokens have no scope restrictions. See Authentication for details on creating and managing tokens.

Request Format

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

Parameter Types

Type	Format	Example
string	Plain text	shape=Signal
integer	Whole number	limit=50
boolean	true or false	includeInactive=true
ISO 8601	Date string	since=2026-01-01T00:00:00Z

Response Format

Success

All successful responses return JSON with a 200 (or 201 for creation) status code. The response shape varies by endpoint — see each endpoint’s documentation.

Errors

All errors return a consistent envelope:

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

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

When the API returns 429 RATE_LIMITED, it may also include a Retry-After response header with the number of seconds to wait before retrying. Clients should back off and retry after that interval when present.

Pagination

Most query endpoints support cursor-based pagination. Action endpoints (/actions/runs, /actions/notifications) support limit and since filtering but not cursor pagination.

Parameter	Description
limit	Maximum number of items to return per page (max 500). Defaults vary by endpoint.
cursor	Opaque pagination token from a previous response’s nextCursor field. Requires limit.
since	Filter items after this timestamp. On /log: ISO 8601 string or epoch milliseconds. On /actions/runs and /actions/notifications: epoch milliseconds (integer) only.
until	Filter items before this timestamp. Supported on /log.

When more results are available, the response includes a nextCursor field. Pass this value as the cursor parameter on the next request (along with limit) to fetch the next page. When all results have been returned, nextCursor is omitted.

Cursors are opaque strings prefixed with whc1_. They are scoped to the original query — changing filters or repo between pages returns a VALIDATION_ERROR. Passing cursor without limit also returns a VALIDATION_ERROR.

Not all endpoints support all parameters — see each endpoint’s documentation.

Quick Reference

Endpoints marked None are publicly accessible for public repositories. Private repositories require a valid Bearer token for all read endpoints — anonymous requests receive a 404.

Organizations & Repositories

Organization and repository CRUD is available via the CLI and SDK only — no REST endpoints are currently mounted. See Organizations & Repositories for details.

Queries

Method	Path	Description	Auth
GET	/api/repos/:org/:repo/head	HEAD snapshot	None
GET	/api/repos/:org/:repo/log	Commit log	None
GET	/api/repos/:org/:repo/history	Version history	None
GET	/api/repos/:org/:repo/things/:wref	Get thing by wref	None
GET	/api/repos/:org/:repo/about/:wref	Assertions about a thing	None
GET	/api/repos/:org/:repo/query	Filtered query	None
GET	/api/repos/:org/:repo/count	Count matching items	None
GET	/api/repos/:org/:repo/resolve/:wref	Resolve wref	None

Commits

Method	Path	Description	Auth
POST	/api/repos/:org/:repo/commit	Create commit	repo:write

Shapes

Method	Path	Description	Auth
GET	/api/repos/:org/:repo/shapes	List shapes	None
GET	/api/repos/:org/:repo/shapes/:shapeName	Get shape	None
POST	/api/repos/:org/:repo/shapes	Create shape	repo:write
PATCH	/api/repos/:org/:repo/shapes/:shapeName	Revise shape	repo:write
DELETE	/api/repos/:org/:repo/shapes/:shapeName	Delete shape	repo:write

Subscriptions & Actions

Method	Path	Description	Auth
GET	/api/repos/:org/:repo/subs	List subscriptions	None
GET	/api/repos/:org/:repo/subs/:name	Get subscription	None
POST	/api/repos/:org/:repo/subs	Create subscription	repo:write
PATCH	/api/repos/:org/:repo/subs/:name	Update subscription	repo:write
POST	/api/repos/:org/:repo/subs/:name/pause	Pause subscription	repo:write
POST	/api/repos/:org/:repo/subs/:name/resume	Resume subscription	repo:write
POST	/api/repos/:org/:repo/subs/:name/bind	Bind credentials	repo:write
DELETE	/api/repos/:org/:repo/subs/:name/bind	Unbind credentials	repo:write
DELETE	/api/repos/:org/:repo/subs/:name	Delete subscription	repo:write
GET	/api/repos/:org/:repo/actions/runs	List action runs	None
GET	/api/repos/:org/:repo/actions/subs/:sub/commits/:num/attempts	Get run attempts	None
GET	/api/repos/:org/:repo/actions/notifications	List action failure notifications	None

Credentials

Method	Path	Description	Auth
POST	/api/repos/:org/:repo/credentials/sets	Create credential set	Required
GET	/api/repos/:org/:repo/credentials/sets	List visible credential sets	Required
GET	/api/repos/:org/:repo/credentials/sets/:name	Get credential set metadata	Required

Authentication

Method	Path	Description	Auth
POST	/api/pats	Create PAT	JWT only
GET	/api/pats	List PATs	JWT only
DELETE	/api/pats/:name	Revoke PAT	JWT only