Versioning and deprecation

The version is in the path: /v1. Within a version the API only grows:

• new endpoints, new optional inputs, new fields in responses;
• new values in fields documented as open-ended (event types, matching reasons, error codes).

Write clients that ignore fields they do not know and handle unknown values of open-ended fields. Anything else (removing or renaming a field, a new required input, a changed meaning) is a new version, served beside the old one.

How a removal is announced

An endpoint that will go away is announced at least 12 months before it stops working. From the announcement, its responses carry:

Deprecation: @1793491200
Sunset: Mon, 01 Nov 2027 00:00:00 GMT
Link: <https://birlesa.com/developers/deprecations#companies-list>; rel="deprecation"; type="text/html"

• Deprecation (RFC 9745(opens in a new tab)): when it was announced, in Unix seconds.
• Sunset (RFC 8594(opens in a new tab)): when it stops working.
• Link: the notice that explains what replaces it and how to move.

The OpenAPI document marks the operation deprecated. Organizations whose keys still call it are told by e-mail as well. Log these headers in your client: they are the earliest warning you get.

Webhook payloads follow the same rule. Their shape (id, type, created_at, data) does not change within /v1; new event types may appear, and a webhook receives only the types it asked for.