API versioning and deprecation

The Endless REST API at https://api.endless.app is versioned by a request header, not the URL. Nothing is deprecated today.

Pin a version

The current version is 1.0.0. Paths have no version segment (/assets, not /v1/assets).

Endless-Api-Version: 1

• Only the major counts: 1 and 1.0.0 mean the same thing.
• Omitting the header accepts the current version.
• Every response carries Endless-Api-Version with the version that served it.
• A major the API can't serve fails with 400 and unsupported_api_version:

{
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "This deployment serves API version 1.0.0; the request asked for 2.",
  "data": {
    "code": "unsupported_api_version",
    "hint": "Send `Endless-Api-Version: 1`, or omit the header to accept the current version.",
    "documentation": "https://endless.app/docs/api"
  }
}

What changes inside a major

Only additions: new operations, new optional inputs, new response fields. Ignore response fields you don't recognize. Removing an operation or field, or changing a field's type, is a new major.

Deprecation

A deprecated operation keeps working for at least 180 days after its first Deprecation header ships, and its Sunset date is never sooner. Every response from it carries these signals:

Machine-readable sources

• OpenAPI document: info.description states this policy, info.version is the current version.
• API index: its versioning object lists the header, current version, supported majors and deprecation_notice_days.
• API reference: every operation, generated from the OpenAPI document.