Endpoints
This page maps WarmHub’s mounted REST endpoints for repository 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 repositories. Private repositories require a valid Bearer token.
Repository Reads
Section titled “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
Section titled “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 repo-scoped action notification records for terminal failures | repo:configure |
POST | /api/action-runs/:runId/callback | Report async action progress or completion | repo:action-callback (repo-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 |
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 repo |
POST | /api/component-registry/:orgName/:componentName/setup-call | Dispatch the optional registered-component setup callback | repo:write on the install repo |
POST | /api/component-registry/:orgName/:componentName/cli/:method | Dispatch an installed component’s CLI method (via wh component exec) | repo:read on the install repo, plus any per-method permission the method declares; owner-org membership is additionally required when the component is private |
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 repository management | CLI org/repo commands or SDK org/repo APIs |
| Repository 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 repository content — /:org/:repo/readme.md, /:org/:repo/agents.md, /:org/:repo/llms.txt | Content shapes |