Versioning and deprecation

How the API is versioned, and the notice you receive before anything is withdrawn.

One version, in the path

Every public endpoint lives under /v1. There are no sub-versions, no dated versions, and no version header — /v1 is the whole versioning scheme.

That is a deliberate choice rather than an unfinished one. A date-pinned model (where each integration is frozen to the API as it stood on a given day) buys integrators stability at the cost of the provider maintaining every historical shape forever. We chose the simpler contract: /v1 moves forward additively, and anything that cannot be added is deprecated on a published notice period instead.

What may change inside /v1 without notice

Additive change only. Build your client so these do not break it:

• New endpoints, new optional query parameters, new optional request fields.
• New fields in a response object. Ignore fields you do not recognise rather than rejecting the payload.
• New members in an enumerated value, including new error codes. Handle an unrecognised error by falling back to the HTTP status — the per-endpoint code lists in the reference are a sample of what you are likely to see, not a closed union. See Errors.

What does not change without the notice below

Removing an endpoint, removing or renaming a response field, narrowing an accepted input, or changing the meaning of an existing field.

The deprecation notice

When an operation is deprecated it keeps working, and it starts announcing its own retirement in two response headers:

HTTP/1.1 200 OK
Deprecation: @1788652800
Sunset: Sat, 06 Mar 2027 00:00:00 GMT
Link: <https://docs.foxguide.io/en/docs/changelog/>; rel="deprecation"

The two values are in different syntaxes, and they are not interchangeable. This trips up almost every client that parses them:

Both examples above describe the same pair of instants: deprecated 2026-09-06, sunset 2027-03-06. Parse Deprecation by stripping the leading @ and reading an integer; parse Sunset with an HTTP-date parser. A client that feeds one to the other’s parser gets a null date and silently loses the notice.

Link is optional and, when present, points at the migration guidance for that operation.

What each header actually promises

• Deprecation is a hint, not a licence. RFC 9745 is explicit that deprecation does not change what the resource currently does. The endpoint behaves exactly as it did; you may keep calling it unchanged until it is actually gone.
• Sunset is the date it is expected to stop responding. When both headers are present, Sunset is never earlier than Deprecation.

The window: 6 months

An operation carries its deprecation notice for at least six months before it is withdrawn. That is the platform’s ratified default and the interval you can plan a migration against.

It is stated here as a floor, not a target: a specific operation may carry a longer window, and its own Sunset header is the authority for that operation. Read the header rather than counting six months from the announcement.

Headers are necessary and nowhere near sufficient

A header nobody reads is not a notice. A deprecation is accompanied by:

• a dated entry in the changelog;
• advance notice to registered integrators;
• the deprecation marked in the OpenAPI document itself, so it is visible in the reference and to anything that generates a client from it.

If you are integrating against this API, subscribing to the changelog is the cheapest way to learn about a change before your logs do.

← All documentation