Deprecation policy

Ninety days, minimum

When we deprecate an endpoint or a field, it keeps working for at least 90 days from the day we announce it. That is a floor, not a target; anything widely used gets longer.

The clock starts when the deprecation is announced, not when you notice it.

How you find out

Three places, and you do not have to watch all of them:

1. The reference marks it. A deprecated operation or field is struck through with the removal date on it.

2. The changelog records it with its date and the migration step.

3. The spec carries it as machine-readable metadata, so tooling can flag it without anybody reading prose:

   {
     "deprecated": true,
     "x-deprecated-on": "2026-08-23",
     "x-removed-on": "2026-11-30"
   }

That last one is enforced in our CI: a change that marks something deprecated without both dates, or with fewer than 90 days between them, fails the build. The policy is not a promise we remember to keep — it is a rule that stops the change landing.

What counts as breaking

Breaking, and therefore subject to the above:

• removing an endpoint, a field, or an enum value
• making an optional request field required
• narrowing a type, or tightening validation
• changing the meaning of an existing field

Not breaking, and shipped without notice:

• adding an endpoint
• adding a response field
• adding an optional request field
• adding an enum value to a field you only read

That last pair is why you should ignore unrecognised properties rather than reject them, and why matching on code beats matching on message.

Nothing is deprecated right now

This page exists before it is needed on purpose. A deprecation policy written during the first deprecation is a policy written to justify a decision already made.