Versioning

The major version is part of the path: /v1. Within v1 we make only backward-compatible changes, and we may make them at any time:

• new endpoints;
• new optional request parameters;
• new fields in responses and events;
• new event types and paper warnings;
• new values in existing lists, such as a new status, failure code, error code or test_outcome;
• longer IDs, up to 64 characters;
• different wording in message fields.

Build your integration to tolerate these: ignore unknown fields, event types and warnings, and treat unknown values as a generic case rather than an error. Any new status we add will be an intermediate one: every object still ends in one of the final statuses listed in this document.

A breaking change means a new major version (/v2). Breaking changes include removing or renaming a field, changing a field’s type or meaning, and adding a required parameter. When a new major version ships, v1 keeps working for at least 12 months. We announce a deprecation by email and in the changelog, and mark affected responses with Deprecation and Sunset headers.