Guides

API and administration guide

All responses use JSON.

All responses use JSON. Normalized API failures use:

JSON
{"error":{"code":"VALIDATION_ERROR","message":"...","details":{}},"requestId":"..."}

Core routes

  • GET/POST /api/catalogs
  • GET/PATCH /api/catalogs/:id
  • POST /api/catalogs/:id/transition
  • GET/POST /api/catalogs/:id/health
  • GET/POST /api/catalogs/:id/verification
  • GET /api/catalogs/:id/evidence
  • GET/POST/PATCH /api/catalogs/:id/ai
  • GET/POST /api/catalogs/:id/environments
  • GET/POST /api/catalogs/:id/repositories
  • GET/POST /api/catalogs/:id/deployments
  • GET/POST /api/catalogs/:id/dependencies
  • GET/POST /api/catalogs/:id/security-reviews
  • GET/POST /api/catalogs/:id/roadmap
  • GET/POST /api/catalogs/:id/comments
  • GET/POST/DELETE /api/catalogs/:id/bookmarks
  • GET /api/catalogs/:id/approvals
  • GET /api/catalog-types
  • GET /api/activity
  • GET /api/discovery?hostname=...
  • POST /api/infrastructure/dns/dry-run
  • POST /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

  1. Contributor creates a draft.
  2. SUBMIT creates a pending approval.
  3. Reviewer uses START_REVIEW to move the submission into review.
  4. Reviewer uses APPROVE or REJECT with an optional reason.
  5. Admin uses PUBLISH after approval.
  6. 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.

Last updated 2 November 2026