API versioning and deprecation policy

An integration should be able to tell, without asking, whether the surface it depends on can change under it. This page is that answer.

Nothing is currently deprecated

Every operation listed at /api/v1/index.json is current and none has a removal date. The machine-readable form of this page is the deprecation_policy object on that same document and on /api/v1/app.json, where currently_deprecated is an empty array and sunset is null.

Versioning

Stable operations live under the major-version path /api/v1. A change that could break a client reading the current payload — removing a member, renaming one, narrowing a type, changing what a value means — appears under a new major path such as /api/v2. It never lands in place. Additive changes, such as a new optional member or a new operation, may land under /api/v1, so parse defensively and ignore members you do not recognize.

How a removal is announced

  • At least 180 days of notice. The interval between the first announcement and the removal is never shorter than that.
  • On this page. The affected operations, the replacement, and the removal date are listed here for the whole notice period.
  • On the response itself. A deprecated operation carries an RFC 9745 Deprecation header giving the date the deprecation took effect, and an RFC 8594 Sunset header giving the date the operation stops being served. A client that reads those two headers learns about a removal without polling this page.
  • In the contract. The operation is marked deprecated: true in /openapi.json and added to currently_deprecated in the API index.

What is not covered

This policy governs the published API surface only. The application interface itself, the layout of the venue view and the wording of the documentation may change at any time. The CSV formats are covered: they are part of the contract, documented at /api/v1/csv-schema.json, and a breaking change to a required column would follow the same 180-day path.

Questions about a specific integration belong on the contact page. The rest of the API surface is described in the developer portal.