API surfaces and publication
The application serves several audiences. Registering a route makes it callable;
publication is a separate decision recorded in
route-catalog.json.
| Audience | Purpose | Customer reference |
|---|---|---|
customer | Supported data products and API-key account reads | Only live and beta operations |
app | Login, account settings, dashboard and billing | Excluded |
integration | Provider callbacks such as billing and received email | Excluded |
internal | Administration, telemetry and operational tooling | Excluded |
Each group records audience, release status, product, owner, configuration
requirements and exact METHOD /path operations. Parameter names use OpenAPI
braces. Approval belongs to a method/path pair, not a display tag or a prefix:
adding a new POST beside an approved GET never publishes it automatically.
Change an endpoint
- Define and register the route with its existing authentication model.
- Add its method/path to an appropriate catalog group. Start unapproved
products in a
draftgroup; split a group when operations need different audiences or release states. Do not mark an unfinished operationlivejust to satisfy the catalog check. - Confirm its configuration, responses, metering and support readiness before
changing it to
betaorlive. The configuration list documents dependency names, not values, and does not certify production readiness. Existing customer products retain their availability during this migration. - Run the focused tests and
pnpm --filter api openapi:emit. The emit fails on unclassified OpenAPI operations or stale catalog entries.
In production, draft and retired operations return 404 before authentication
or credit metering. Unclassified /v1, /v2 and /v3 operations also return
404. Document extraction (invoice and receipt) is currently draft. Development
keeps drafts available for implementation and testing. The worker's direct
internal interfaces are not changed by this API gateway policy.
Removing a route from customer docs does not replace its access controls. App
routes retain session and capability checks; callbacks verify provider
signatures; staff routes retain their existing permissions. internal describes
the audience, not a promise that a route is reachable only over a private network.
Public outputs
buildOpenApiDocument() filters by the catalog and removes unused tags, sidebar
groups and component schemas. /openapi.json, /llm.txt, and the emitted
apps/api/openapi.json share that builder. Customer operations carry
x-audience, x-status, and x-product metadata.
The documentation importer requires these publication markers on local, remote
and cached specifications. Legacy or unfiltered documents fail the build;
PUBLISH_ALL_TAGS=1 is no longer a supported bypass. Generate SDKs and marketplace
exports from the public emitted file, never from the private builder or a raw
router registry. Independently maintained external catalogs still require their
own release; this change does not publish them automatically.
Private catalog
Run pnpm --filter api routes:catalog to write
/tmp/toolzerhub-route-catalog.json, or pass an output path. It includes the
complete OpenAPI document and catalog metadata, including operational routes
that do not define OpenAPI operations. The file is local; there is deliberately
no new public HTTP route serving it. Do not put this artifact in the docs site's
public directory or marketplace exports.
For incoming support messages, see email forwarding.