Backend API Reference

This section is generated from apps/backend/src/documentation. The docs build first exports the current result of createOpenApiDocument() to a temporary public schema snapshot, then Fumadocs builds the API pages from that snapshot.

There is no copied hand-authored API schema and no symlink. A backend contract change must update the owning OpenAPI module; the local backend explorer and this site then receive the same document.

Reference Groups

Local API Surfaces

With the backend on its default port:

• Scalar explorer: http://127.0.0.1:3000/docs
• Machine-readable schema: http://127.0.0.1:3000/docs/spec.json
• Static docs snapshot: Download OpenAPI JSON

The interactive request playground is disabled on this public static site. Use the local backend explorer when you intentionally need to issue requests against a running local stack.

Generated request examples target http://localhost:3000 by default. A deployment with a stable backend address can set OBLIVE_API_DOCS_SERVER_URL during the docs build; the value is validated as an HTTP or HTTPS URL and written only to the public OpenAPI snapshot.

Authentication Boundaries

Organization-facing routes and trusted runtime routes have different authentication contracts. Pages under Trusted Runtime API are service or execution-capability boundaries used by Oblive runtimes; they are not general public client APIs.

Keeping the Reference Current

When a route, parameter, request, response, authentication rule, status, error, or example changes:

1. Update the resource module under apps/backend/src/documentation.
2. Add or update documentation tests.
3. Run bun run docs:openapi:sync from the product workspace.
4. Run bun run docs:openapi:check and bun run --cwd sites --filter @oblive/site-docs api:generate.
5. Run the backend and docs checks.
6. Update operator/developer pages when the behavior or workflow also changed.