Skip to main content

​
Versions

The Apps API is versioned by month, in the form YYYY-MM. A new version ships only when there is a breaking change. Additive changes, such as a new field or a new endpoint, reach every version without one.

​
Ask for a version

Send the version you built against on every call:
Every response tells you which version answered it:
  • No header: you get the oldest supported version. That keeps an app that never sends the header working, but it will move when that version is retired, so send the header.
  • A supported version: you get it as is.
  • A retired version: you get the oldest supported version instead. Compare the response header with what you asked for to notice.
  • A malformed or unknown version: 400, with the versions you can use:

​
Deprecation

When a version starts winding down, responses served with it carry standard headers:
Deprecation is when it was deprecated, Sunset when it stops being served. Log these headers and move to a newer version before the sunset date.

​
Webhooks

Webhook deliveries carry ids only, never record fields, so they are the same in every version. The record you fetch after a webhook is shaped by the version you send on that fetch.