OpenAPI contract
This directory holds openapi.yaml, the single source of truth for the Aetherin API.
Versioning
The contract version is tracked in three places that must stay in sync:
../VERSION— canonical contract version (e.g.1.0.0-rc.2).info.versioninopenapi.yaml.versionin../package.json.
Rules:
- Patch / minor (non-breaking): add fields, endpoints, or enum values;
bump the minor or patch component of VERSION.
- Major (breaking): remove or rename fields/endpoints, change types, or
alter semantics; bump the major component and introduce a new /v2 prefix while keeping /v1 available for a deprecation window (see ../API_STABILITY.md).
- Pre-release suffixes (
-rc.2,-beta) mark release candidates.
Generating clients
TypeScript (frontend / middleware):
npm run generate:tsUses openapi-typescript to emit generated/api.ts.
Go (core runtime):
oapi-codegen -config codegen/go.yaml openapi/openapi.yamlUses oapi-codegen (see ../codegen/go.yaml). The config enables skip-prune so webhook-only schemas (e.g. UsageAlertEvent) are emitted and sets a response-type suffix to avoid collisions with schema names.
Lint
npm run lintRuns Redocly against openapi/openapi.yaml; must report zero warnings.
Errors
Every operation returns the ErrorResponse envelope on failure. The stable ErrorCode values, their HTTP statuses, and their meanings are documented in ERROR_CODES.md.