Versioning

The major version is in the path: /v1. Within v1 we only make additive changes:

• new endpoints, resources, and optional request fields;
• new fields on response objects;
• new error code values within existing types;
• new values in fields documented as open-ended (for example a record's source).

Build clients that ignore unknown fields and handle unknown codes by their type.

Breaking changes — removing or renaming a field, changing a type, tightening validation, changing default behaviour — only ship in a new major version (/v2). When that happens, /v1 keeps working for at least 12 months, and we announce the deprecation in the changelog and by email to workspace admins.

The machine-readable spec for the current version is always at /v1/openapi.json.