Versioning

The API's version is the first part of every path: /v1.

What can change in v1

These changes can arrive in v1 at any time, and each is listed in the Changelog:

• new endpoints and new resources, with their own permissions;
• new optional request fields and query parameters;
• new fields in replies;
• new error codes;
• new values in fields that name a kind or a channel, such as createdVia.

So your client must ignore reply fields it does not know, and handle a value it does not know, for example by treating an unknown createdVia like unknown.

What does not change in v1

• An existing field keeps its name, its type and its meaning.
• An error code keeps its meaning. Branch on code; message is text for people and can be reworded or translated at any time.
• A request that works today keeps working.

Requests stay strict: a field or query parameter that an endpoint does not know is refused with 400 unknown_parameter. A new optional field becomes accepted only once it is released and listed in the changelog.

A breaking change

A change that would break a working client, such as removing or renaming a field, comes as a new version with its own path prefix, such as /v2.