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 Enterprise surface This reference shows the complete enterprise API surface — every endpoint every addon exposes. A self-hosted Orkestra instance running a leaner SKU profile (e.g. starter, billing, ai, saas) only serves the subset of endpoints whose addons are compiled in, and within those, only the ones currently enabled at /admin/modules. Routes for disabled-or-not-compiled modules return 503 Service Unavailable.

To find out which SKU includes which endpoints, see the Module Catalog — each addon page lists its routes. :::

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, the client's own self-service surfaces (subscriptions, payments webhooks). Tokens carry aud=client. Served on the client host (e.g. api.orkestra.cc).

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

Browse endpoints​

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

  • Authentication, MFA, sessions
  • Users, tenants, RBAC
  • Module administration (/admin/*)
  • Billing (FatturaPA/SDI invoicing)
  • Documents (PDF generation)
  • AI: models, RAG, agents
  • Subscriptions + payments (Stripe)
  • Compliance + identity