Skip to main content

API Reference

Orkestra is OpenAPI-first — every endpoint is defined via Huma v2, which generates a full OpenAPI 3.1 document at runtime. The pages in this section are auto-generated from that document, per-endpoint, with deep-linkable URLs and inline schemas.

:::info Core API surface This reference shows the core API surface — the base ships only the eight core modules, with an empty optional-module catalog. A fork that adds verticals regenerates this spec to include its own routes. Routes for an optional module that is disabled at /admin/modules return 503 Service Unavailable via the module gate.

For what each module contributes, see the Module Catalog. :::

Audience split​

Two audiences consume the API:

  • Operator (Tier-1 self-hosters) — the /admin/* surface plus operator-facing module endpoints. Tokens carry aud=operator. Served on the console host (e.g. console.orkestra.cc).
  • Client (Tier-2 external clients) — public signup, login, and the client's own account self-service. Tokens carry aud=client. Served on the client host (e.g. api.orkestra.cc). (A fork that sells services to external clients adds its consumption surfaces — catalog, subscriptions, payment webhooks — here.)

Both audiences are rendered together in this reference because Huma currently generates a single shared OpenAPI document — the audience separation lives at the host/mux level, not at the spec level. Each route's tag tells you which surface it lives on; routes scoped to internal-tenant or with aud=operator security implications belong to the operator surface.

Authentication​

All non-public endpoints require a Bearer JWT:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

See Architecture › Authentication Flow for how to mint one (email/password, OAuth 2.1, or — in dev — ./scripts/devtoken.sh).

Live spec​

The canonical spec lives at backend/openapi/enterprise.json in the monorepo. It is regenerated by make openapi-dump and gated by make openapi-check in ci-backend, so it never drifts from the routes in main.

On a running instance, the live spec is served at:

  • Operator surface: https://<your-console-host>/openapi.json
  • Interactive docs (Scalar UI): https://<your-console-host>/docs

Both are served only when API_DOCS_ENABLED is true — the default in development, off in staging and production. The document is a complete route inventory and the docs page runs a third-party bundle on the API origin, so a production-like deployment that opts in should also gate the two paths at the edge (Cloudflare Access or an IP allowlist, for example).

Browse endpoints​

Use the sidebar to navigate by tag, or jump to a section:

  • Authentication, MFA, sessions
  • Users, tenants, RBAC (roles, permissions, bindings)
  • Module administration (/admin/*)
  • Navigation
  • Observability — runtime log-levels (/admin/observability/*)

(A fork that adds verticals — invoicing, documents, AI, subscriptions/payments, compliance, identity, … — regenerates the spec, and those tags appear here too.)