Stability and versioning - Sayless

Current version

The public HTTP surface is URI-versioned as /api/v1. Machine-readable contract: GET /api/v1/openapi.json (also checked into the gateway as openapi.json). CI fails on unintended Broad OpenAPI diffs (openapi:check) and on SDK resource drift (sdk:check).

Stability

Routes marked @PublicApi in the gateway are the only integration surface:

Label	Meaning
stable (default)	Safe to build on; breaking changes require changelog + migration window
beta (`@PublicApi({ stability: 'beta' })`)	May change faster; still documented in OpenAPI

App-only routes (broadcasts, triggers, analytics, sync, …) may change without a public changelog.

Breaking changes

Removals or incompatible request/response changes on public routes will be:

Announced in the developer changelog
Guarded in CI against unintentional OpenAPI diffs
Prefer additive changes; avoid relying on undocumented fields

Auth product notes

Personal API keys and OAuth tokens only. Workspace/service tokens are not part of Broad v1 (see authentication docs). Fine-grained resource scopes are a later follow-on.