OpenAPI
Raw spec access, spec metadata, and the small maintenance workflow behind this static docs build.
What this page is for
Raw spec access: the static docs build
exports the committed OpenAPI snapshot as
/openapi.yaml .
Keep versioning concepts separate:
route versions stay in URL paths like
/v1 and /v2, while info.version is the OpenAPI spec release
label.
Maintenance only: this page is for
syncing, validating, and deploying the snapshot, not for browsing endpoints.
Spec metadata
Spec version
0.8.3-beta
Release date
04.05.2026
Stage
beta
Route versions
/v1, /v2
OpenAPI format version
3.0.3
Paths
17
Operations
17
Schemas
34
Auth schemes
ApiKeyHeaderAuth, BearerApiKeyAuth
Repository file
src/docs/openapi/openapi.yaml
Raw route
Route/API contract versions:
the actual API versions are expressed in the URL paths above, for example
/v1/ors/*, cached /v1/suno/* song/profile routes,
and /v2/cards/taxi.
Security schemes:
ApiKeyHeaderAuth and BearerApiKeyAuth both use
the same server-issued API key.
Spec version:
0.8.3-beta identifies this OpenAPI release, not the
path contract.
Release metadata:
x-release-date and x-api-stage are tracked separately
so the date and stage do not get confused with route versioning.
Workflow
1. Sync the backend OpenAPI file into the committed snapshot.
2. Build the static docs target.
3. Deploy the resulting output to the docs host.
Commands
Sync from a local backend file
npm run openapi:sync -- --source ../velvari-api/openapi.yaml Validate or refresh the committed snapshot
npm run openapi:sync Build the docs site
npm run docs:build