Cascades
Docs
API versioning

API versioning

How Cascades signals HTTP API revisions without `/api/v1/` path prefixes today.

Current strategy (documented)

  • Machine-readable revision: GET /api/system/version returns { "apiVersion": "v1" } (see contracts/api.yaml / ApiVersionResponse). SDKs should treat this label as the compatibility epoch for the HTTP surface bundled in contracts/api.yaml.
  • No path prefix: Public routes remain under /api/... without embedding /v1/ in the path. Breaking HTTP changes are expected to coincide with an apiVersion bump (or a documented migration window) rather than silent URL churn.

Contract sources

  • SDKs and external codegen: contracts/api.yaml (narrower, stable boundary).
  • Full product + dashboard routes: /openapi.json (superset; includes paths intentionally omitted from the SDK contract).

Alternatives (not implemented)

Prefix versioning (/api/v1/workflows/run) could be introduced later behind routing + reverse-proxy rules; it would require explicit gateway mapping and a migration plan for cookies and relative URLs.

CommunityReport issue / Discuss(tags: Cascades, workflows)
Repository mapAPI Reference