API reference
Every operation of the OrkStage Control API v1, with request and response schemas, generated from the OpenAPI document a running API serves.
fumadocs-openapi generates these pages from openapi/orkstage.json, the document a running API
serves at /api/docs-json. The interactive Swagger UI is at /api/docs. Read the
REST API overview first for authentication, errors, pagination and
correlation ids.
Sections
Authentication
Providers, OIDC login, development login, logout and the current principal.
Instances
Create, preview, deploy, upgrade and destroy instances; logs and metrics.
Deployments
Progress, events, approval, cancellation and retry.
Templates
Templates, versions, validation, publishing and cloning.
API keys and webhooks
Credentials for automation and outbound events.
CI/CD and imports
Stateless validation, image versions and IaC import.
Authentication in the reference
The document declares two security schemes: the orkstage_session cookie and an API key sent as
Authorization: Bearer ork_… (apiKey). A key works only on operations
that declare a scope, as described in API keys.
Refreshing
The site never calls the API at build time. To update the reference after an API change:
# with the platform running (for example: pnpm platform:up in the platform repository)
pnpm openapi:refresh # saves http://localhost:4000/api/docs-json
ORKSTAGE_API_URL=https://api.example.com pnpm openapi:refresh
pnpm build # regenerates these pages (prebuild step)After the repositories are split, the platform's CI will publish the OpenAPI file as a release asset, and the site will pin the version it documents.