Versioning and deprecation

/api/v1 is stable. A breaking change (removing or renaming a field, tightening a parameter, changing a status) needs /api/v2. Additive changes can happen in v1: a new field, a new optional parameter, a new error code on an existing status. Ignore fields you don’t know.

• Stable routes are covered by these promises.
• Beta routes (x-stability: beta, marked in the reference) may still change. Today that’s 66 operations, including the admin routes and the assistant.
• Internal routes aren’t documented and may change at any time.

A deprecated route keeps working until its sunset date, and answers with:

• Deprecation: @<unix seconds> (RFC 9745);
• Sunset: <HTTP date> (RFC 8594);
• Link: <successor>; rel="successor-version".

It’s marked deprecated in the document and the reference, and listed in the changelog. Deprecated today:

Nothing is deprecated.