Component Registry Install Routes

These routes are narrow helpers around the backend-managed install pipeline. The full install and update flow — resolving the manifest, minting an install id, reconciling the install record, and optionally running setup — is orchestrated by the backend. The CLI, SDK, and MCP surface that pipeline through the higher-level component.install backend operation. The REST routes documented here cover only the resolve and setup-call steps; they do not expose the reconcile step or mint install ids. If you need a fully self-contained install flow from a custom client, use the SDK or CLI rather than these routes directly. 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 — 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 or update 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 or updated into a repo and return the latest published manifest snapshot. 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": "9f86d081884c",
  "hasSetup": true
}

manifest is the full resolved manifest object; manifestHash is an opaque version token identifying the published version — treat it as an opaque string and echo it back to setup-call as expectedManifestHash without inspecting or transforming it; hasSetup indicates whether the component declares a setup callback. resolve does not allocate an install id — that is minted by the backend install pipeline.

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 or update. This route supports both fresh installs and registered updates: on update, pass the existing installId together with the manifestHash from the latest resolve response so the backend can re-fetch the manifest, rotate minted tokens, and rerun setup against the new revision.

Request

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

All three fields are required. installId is the id of the ComponentInstall record being set up or updated (minted by the backend install pipeline, not by resolve); pass the manifestHash that resolve 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 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.
• These routes cover only the resolve and setup-call steps of the install pipeline. The reconcile step and install-id minting are handled by the backend; they are not accessible through these REST routes. Custom clients that need the full install flow should use the SDK or CLI.
• Custom HTTP clients should pass the installId of the install or update being set up, and the manifestHash from the preceding resolve response as 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>