API versioning
The version in the path (/api/v1) covers the whole API. When we publish a new version, we
support the previous one for at least 12 months.
What can change within v1
Section titled “What can change within v1”Within /api/v1 we may, at any time and without notice:
- add fields to a response — ignore fields you do not recognise;
- add new values to an existing enum — handle unknown values without failing;
- add new endpoints, and new optional parameters to existing ones;
- change the order of keys in an object, and of items in a collection not documented as ordered;
- change default page sizes and the contents of pagination cursors;
- change the wording of error messages — key on the HTTP status and error code, never on message text;
- rotate certificates and change IP addresses — pin neither.
What needs a new version
Section titled “What needs a new version”We only issue a new version when we:
- remove or rename a field or endpoint;
- change a field’s type;
- tighten validation on an input you already send;
- change the meaning of a value in use.
Was this page helpful?Thanks for your feedback!