All responses use JSON. Normalized API failures use:
{"error":{"code":"VALIDATION_ERROR","message":"...","details":{}},"requestId":"..."}Core routes
GET/POST /api/catalogsGET/PATCH /api/catalogs/:idPOST /api/catalogs/:id/transitionGET/POST /api/catalogs/:id/healthGET/POST /api/catalogs/:id/verificationGET /api/catalogs/:id/evidenceGET/POST/PATCH /api/catalogs/:id/aiGET/POST /api/catalogs/:id/environmentsGET/POST /api/catalogs/:id/repositoriesGET/POST /api/catalogs/:id/deploymentsGET/POST /api/catalogs/:id/dependenciesGET/POST /api/catalogs/:id/security-reviewsGET/POST /api/catalogs/:id/roadmapGET/POST /api/catalogs/:id/commentsGET/POST/DELETE /api/catalogs/:id/bookmarksGET /api/catalogs/:id/approvalsGET /api/catalog-typesGET /api/activityGET /api/discovery?hostname=...POST /api/infrastructure/dns/dry-runPOST /api/infrastructure/dns/execute
Reads are public where catalog information is public. Mutations use a bearer
ADMIN_TOKEN plus X-Appneural-Role. The role is honored only after the token is
validated. Supported roles are Viewer, Contributor, Reviewer, Platform Engineer
and Admin. KV applies a bounded per-token request rate to mutation routes.
Publication workflow
- Contributor creates a draft.
SUBMITcreates a pending approval.- Reviewer uses
START_REVIEWto move the submission into review. - Reviewer uses
APPROVEorREJECTwith an optional reason. - Admin uses
PUBLISHafter approval. - Archive replaces destructive deletion; the compatibility DELETE route never physically removes a catalog.
Each transition creates activity and audit records. Important mutation APIs also record before/after evidence and actor identity.
Administration
The /admin workspace summarizes review, verification and health queues. Its
catalog-type, integrations, verification and settings sections document active
system configuration without exposing secrets. UI actions requiring privileges
ask for a token at the action boundary; tokens are not placed in local storage.
AI governance
Workers AI receives only current catalog evidence. Generated content is written
to R2 and registered in D1 with DRAFT status, model, prompt version, source
references and actor. Contributors can load history, generate/regenerate and edit
drafts; reviewers can accept or reject them. Every decision is audited. Acceptance
marks the artifact as human-reviewed but never directly replaces verified fields.