Skip to content
WarmHub

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 three routes are mounted under:

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

The caller must have things:write on the install repo named in the request body. Private registered components are installable only into repos in the owner org.

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

Section titled “POST /api/component-registry/:orgName/:componentName/resolve”

Check whether a registered component can be installed into a repo and mint a fresh install id.

Request

Section titled “Request”
{
  "installRepo": "acme/world"
}

Response

Section titled “Response”
{
  "sourceUrl": "https://github.com/warmhub/veritas-component",
  "sourceDefaultRef": "main",
  "hasSetup": true,
  "installId": "019e..."
}

Errors

Section titled “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 installable source URL

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

Section titled “POST /api/component-registry/:orgName/:componentName/source”

Download the component source archive through the backend. For private GitHub sources, the backend uses the bound GITHUB_TOKEN server-side so the token does not reach the client.

Request

Section titled “Request”
{
  "installRepo": "acme/world",
  "ref": "main"
}

Response

Section titled “Response”

Binary response body containing the source archive.

Headers:

  • content-type
  • x-warmhub-source-url
  • x-warmhub-source-ref (optional)
  • x-warmhub-resolved-sha (optional)
  • x-warmhub-component-ref

Errors

Section titled “Errors”

Same auth and visibility rules as resolve.

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

Section titled “POST /api/component-registry/:orgName/:componentName/setup-call”

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

Request

Section titled “Request”
{
  "installId": "019e...",
  "installRepo": "acme/world",
  "ref": "release-2026-05",
  "resolvedSha": "1f2e3d4c5b6a79808796a5b4c3d2e1f0a9b8c7d6"
}

ref and resolvedSha are optional but should be forwarded from the preceding /source response when the caller is implementing the install handshake directly. When resolvedSha is present, WarmHub uses that commit to fetch the manifest for setup/runtime token scope derivation; otherwise it falls back to ref, then the registration default ref.

Response

Section titled “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

Section titled “Notes”
  • The backend reads SETUP_* keys and optional GITHUB_TOKEN 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.
  • setup-call is invoked after the source archive has been downloaded and installed locally by the CLI.
  • Custom HTTP clients should pass the /source response’s x-warmhub-source-ref and x-warmhub-resolved-sha values as ref and resolvedSha in setup-call.

Setup credential keys

Section titled “Setup credential keys”

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

KeyEffect
SETUP_BEARER_TOKENSends Authorization: Bearer <token>
SETUP_API_KEYSends an API key header
SETUP_API_KEY_HEADERHeader name for SETUP_API_KEY; defaults to X-API-Key
SETUP_BASIC_USERNAME + SETUP_BASIC_PASSWORDSends HTTP Basic auth when no bearer token is set
SETUP_SIGNING_SECRETSends X-WarmHub-Signature and X-WarmHub-Timestamp; signature is HMAC-SHA256 over <timestamp>.<body>

Hit a problem or have a question? Get in touch.