Deprecation & Versioning Policy

How AllAPI.io versions its API and retires endpoints — predictable timelines, clear headers, and honest migration paths. The v1 URI prefix goes live at launch.

1. API versioning

Production requests are served under a version prefix — https://api.allapi.io/v1/.... A new major version (v2) is only introduced for breaking changes, and ships with at least a 12-month sunset notice for the previous version. Non-breaking additions (new endpoints, new optional fields) never bump the major version.

2. Deprecation timeline

Every deprecation moves through three stages:

Announcement — a blog post, a docs banner, and an email to registered users.
Warning — the endpoint keeps returning 200 but adds an X-API-Deprecation response header with the ISO-8601 sunset date.
Sunset — after the notice period the endpoint returns 410 Gone with a documented error envelope.

3. Sunset periods

What changes	Minimum notice
Endpoint removed	12 months
Auth scheme changed	6 months (a security exception may shorten this)
Response field removed	6 months (with an `X-Deprecated-Field` warning header)
Third-party upstream withdrawn	Immediate — an honest `503 upstream_deprecated` envelope (out of our control)

4. Response headers

Header	Meaning
`X-API-Version`	The version serving this response
`X-API-Deprecation`	ISO-8601 sunset timestamp (present only when deprecated)
`X-API-Successor`	The replacement route, when one exists
`X-Request-ID`	Correlation ID for support and tracing

5. Error envelope

Deprecated and sunset routes return the standard honest envelope — never a fabricated success:

{
  "ok": false,
  "error": {
    "code": "ENDPOINT_DEPRECATED",
    "message": "This route is retired; use its successor.",
    "successor": "/v1/<platform>/<route>",
    "sunset": "2027-01-01T00:00:00Z",
    "retryable": false
  }
}

6. Migration & communication

Each deprecated endpoint gets a migration note in the docs. We announce changes through the blog, this policy page, the status page, email to registered users, in-response headers, and a dashboard banner. Enterprise migration support: [email protected].

7. Historical deprecations

None yet — AllAPI.io is v1.0 — production ready. This table will list every retired endpoint with its announcement and sunset dates once the first release ships.

Browse platforms · API & MCP · OpenAPI & Postman