Core API discovery routes
Engineering-only reference for machine clients (HEAT toolkit, agentic-cli, in-cluster agents). These routes are on the Core API, not the versioned v2 public API.
Purpose
Discovery answers two questions for a connected HEAT environment:
- Environment-specific: which node templates are registered in Postgres for this cluster.
- Release-specific: which v2 dashboard widgets and public platform-config keys ship with this Core API image (from a build-time bundle).
Documentation excerpts are copied from MDX at image build time (deploy/generate-discovery-bundle.mjs). They are not parsed at request time.
Regenerating the bundle
From the monorepo root:
node deploy/generate-discovery-bundle.mjsdeploy/build_all.sh runs this after write-heat-platform-build.sh. Output: core/api/build-info/heat-discovery-bundle.json (gitignored, embedded in the Core API publish output).
Routes
| Method | Path | Description |
|---|---|---|
| GET | /api/discovery | Index: build info, bundleAvailable, section paths, counts |
| GET | /api/discovery/node-templates | Registered templates + schemas + MDX excerpts |
| GET | /api/discovery/dashboard-components | Dashboard manifest + excerpts (scope: release) |
| GET | /api/discovery/platform-configuration-keys | Public config key catalog (summaries only, not live values) |
| GET | /api/discovery/docs/{key} | Single excerpt by template name, component id, or docsPath |
Responses use the usual Core API GenericResponse<T> envelope (status, message, template).
Auth
Same as other Core API routes: CoreAuthMiddleware. External toolkit clients should send Authorization: Bearer using HEAT_API_TOKEN or HEAT_API_KEY.
Warnings
GET /api/discovery/node-templates may include warnings:
discovery_bundle_unavailable— local run or image built without the bundle step.no_documentation_in_bundle— one or more registered templates have no MDX entry in the bundle.
Related
tools/agentic-cli—discoverysubcommands.GET /version— platform build metadata only.