Core concepts

Versioning

The API is versioned in the URL path. The version prefix is part of each route — e.g. /v1/tracks — rather than the base URL, so endpoints can move to a new version independently.

How versions evolve

Breaking changes to an endpoint ship under a new prefix (/v2/…) while the existing /v1/… route keeps working.
Backwards-compatible additions — new endpoints, new optional fields — are added to the current version without a prefix bump. Build clients to ignore unknown fields.
We give advance notice and a deprecation window before retiring a route version.

Version headers

Every response carries two version headers:

X-API-Versionstringoptional
The URL-path contract version, e.g. v1.
X-Service-Versionstringoptional
The semver of the running build, e.g. 1.0.0. Diagnostics only.

Discover the version without auth

Two unauthenticated endpoints report the current version:

GET /version
GET /health-check

{
  "data": {
    "apiVersion": "v1",
    "serviceVersion": "1.0.0"
  },
  "error": { "code": 0, "message": "OK" }
}

Pin the major version

Pin the major version (/v1) in your client. Do not parse X-Service-Version to drive behavior — it is for diagnostics only.

PreviousPagination & filtering Next Get access token