OpenAPI contract

The Cascades HTTP API is described by a single OpenAPI 3.1 document. It is the canonical contract for automation and codegen—the same logical document powers the interactive API Reference explorer.

SDK contract vs full OpenAPI

The first-party Python SDK (cascades-sdk on PyPI, repository https://github.com/no1rstack/cascades-sdk) and other generated clients align with contracts/api.yaml in this repository: that file lists the HTTP paths that are considered the stable SDK boundary.

/openapi.json is a superset: it also documents dashboard, account, and ops routes (for example GET /api/runs/{id}/logs, GET /api/system/status, /api/secrets, and the read-only GET /api/workflow-echo preset) so Scalar and CI see one generated document. Some POST /api/integrations/*/test paths are included in the SDK contract where we ship them to PyPI integrators; others are OpenAPI-only—see the provider’s row in contracts/api.yaml and run npm run validate:contract after edits.

CI guardrails: npm run audit:api fails if any app/api/**/route.ts lacks a co-located schema.ts. npm run generate:openapi then materializes openapi/cascades-openapi.json (tracked; CI diffs it).

API revision label: see API versioning (GET /api/system/version).

Tracing: Cascades emits OTLP to your collector when configured — there is no GET /api/traces/{id} product API; read OTLP tracing (export-only).

What this spec is for

Use /openapi.json when you need a portable, machine-readable contract for:

• SDK generation — OpenAPI generators (Kiota, OpenAPI Generator, etc.)
• Postman / Insomnia — Import OpenAPI to bootstrap collections
• API gateways & mocks — Contract-first tooling
• CI contract validation — Diff specs between releases or gate breaking changes
• Scalar / external explorers — Ingest the JSON URL (the hosted explorer uses the sibling /openapi JSON route for embedding)

Human-friendly exploration

For browsing and searching the API interactively, use API Reference first—it stays the primary onboarding surface for humans.

Download the JSON

The raw document is always available at a stable URL (ideal for scripts and bookmarks):

Download OpenAPI JSON

Browsers are encouraged to download the file (cascades-openapi.json) rather than rendering a large JSON page; integrations that fetch the URL programmatically behave unchanged.

Command-line example

Production (public deployment):

curl -sS -o cascades-openapi.json https://cascades.work/openapi.json

Local development (next dev, default port 3000):

curl -sS -o cascades-openapi.json http://localhost:3000/openapi.json

Validate JSON quickly:

curl -sS https://cascades.work/openapi.json | jq '.openapi'

Related

• API Reference — Interactive explorer (recommended for humans)
• API quickstart — Auth, sessions, and first requests
• SDK documentation — Python SDK cascades-sdk on PyPI and no1rstack/cascades-sdk on GitHub (BSL 1.1 in the SDK repo, aligned with this platform’s governed licensing) plus OpenAPI-driven clients. This Cascades repository’s contracts/api.yaml is the authoritative concise HTTP boundary; /openapi.json is the full aggregated spec for tooling.