Versioning and deprecation

Every API is versioned in its path, starting with /api/v1/.

What we change without a new version

• Adding endpoints.
• Adding optional request fields.
• Adding response headers or response fields.
• Adding new error codes for new failure modes.
• Raising limits.

Breaking changes

Removing or renaming fields, changing types or defaults, tightening validation and changing authentication all require a new version (for example /api/v2/).

Deprecation policy

When a version is deprecated:

1. We announce it in the changelog and email workspace owners.
2. The version keeps working for at least 6 months.
3. Responses carry Deprecation and Sunset headers during that period.
4. The endpoint reference shows the deprecation and a migration guide.