Component Registry

These routes back the registered-component install flow used by wh component install <org/name>. Registry management itself is not exposed as REST: create, list, view, update, and unregister use the SDK/tRPC client.component.registry.* surface.

All routes are mounted under:

/api/component-registry/:orgName/:componentName

The mounted routes are resolve and setup-call — the two-step install handshake documented below. A third route, cli/:method, is the transport behind wh component exec; it dispatches an installed component’s CLI methods rather than serving the install flow, so it is not documented as a standalone REST call here — see the component CLI reference for how those methods are defined and invoked.

The caller must have the repo:write scope on the install repo named in the request body. Private registered components are installable by members of the owner org into any repo they have write access to.

POST /api/component-registry/:orgName/:componentName/resolve

Check whether a registered component can be installed into a repo, return the latest published manifest snapshot, and mint a fresh install id. Registered installs resolve the stored manifest snapshot directly through the registry.

Request

{
  "installRepo": "acme/world"
}

Response

{
  "manifest": { "component": { "id": "com.warmhub.Veritas", "name": "veritas", "version": "1.2.0" } },
  "manifestHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b",
  "hasSetup": true,
  "installId": "019e..."
}

manifest is the full resolved manifest object; manifestHash identifies the published version and must be echoed back to setup-call as expectedManifestHash.

Errors

• 400 VALIDATION_ERROR — malformed installRepo
• 401 UNAUTHENTICATED
• 403 FORBIDDEN — caller lacks install-repo write access, or private registration is being installed into a foreign org
• 404 NOT_FOUND — registration does not exist
• 409 CONFLICT — registration has no published manifest version

POST /api/component-registry/:orgName/:componentName/setup-call

Ask the backend to dispatch the optional setup callback for a registered component install.

Request

{
  "installId": "019e...",
  "installRepo": "acme/world",
  "expectedManifestHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b"
}

All three fields are required. Pass the installId minted by resolve and the manifestHash it returned as expectedManifestHash. WarmHub uses that resolved manifest version to derive setup/runtime token scope. If the latest published manifest has moved since resolve, the call is rejected with 409 CONFLICT — re-run resolve (reinstall) to pick up the new version.

Response

{
  "ok": true,
  "status": 202,
  "warnings": []
}

The WarmHub HTTP response status matches the setup dispatch result: 200 when ok is true, otherwise the non-2xx status shown in the JSON body.

On non-2xx setup dispatch:

{
  "ok": false,
  "status": 400,
  "body": "Webhook target is not reachable or not allowed",
  "warnings": []
}

Before outbound dispatch begins, the route can also return the standard WarmHub error envelope:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing required permissions"
  }
}

Handle this envelope for validation, auth, missing setup URL, private-registration visibility, conflict, and manifest/token-preparation failures.

Notes

• The backend reads SETUP_* keys from the registered credential set.
• When the registration has mintedTokens: true, the setup payload may include a minted setup token and a runtime token derived from the manifest’s runtimeAccess. Re-running setup-call rotates these tokens against the resolved manifest version and revokes the prior ones.
• setup-call is invoked after the CLI has resolved the manifest and applied the local install.
• Custom HTTP clients should pass the installId and manifestHash from the preceding resolve response as installId and expectedManifestHash.

Setup credential keys

The registered credential set can include these setup-auth keys:

Key	Effect
SETUP_BEARER_TOKEN	Sends Authorization: Bearer <token>
SETUP_API_KEY	Sends an API key header
SETUP_API_KEY_HEADER	Header name for SETUP_API_KEY; defaults to X-API-Key
SETUP_BASIC_USERNAME + SETUP_BASIC_PASSWORD	Sends HTTP Basic auth when no bearer token is set
SETUP_SIGNING_SECRET	Sends X-WarmHub-Signature and X-WarmHub-Timestamp; signature is HMAC-SHA256 over <timestamp>.<body>