API versioning

How endpoint versions work, what counts as a breaking change, and how deprecations are handled

How versions work

Each endpoint is versioned independently with a path segment after the endpoint name. The bare path is version 1, and later versions append /v2/, /v3/, and so on.

POST https://api.cyclemate.club/directions/       (v1, deprecated)
POST https://api.cyclemate.club/directions/v2/    (v2, current)

Versions are per endpoint, not platform wide: one endpoint can move to a new version while the others stay where they are.

Requesting a version that does not exist returns 404:

{
  "error": "Unknown endpoint or API version"
}

Current versions

Endpoint	Current version	Notes
POST /directions/v2/	v2	v1 (POST /directions/) is deprecated and closed to new integrations
POST /multi-modal/v2/	v2	v1 (POST /multi-modal/) is deprecated and closed to new integrations
POST /explain-supersafe/	v1
POST /reports/	v1
GET /reports/{id}/	v1

Breaking and additive changes

A new version is introduced only for breaking changes:

• Removing, renaming, or changing the type or nesting of a response field.
• Changing a field’s meaning or casing.
• Removing a request parameter, or changing authentication requirements.

Additive changes ship within the current version: new optional response fields and new optional request parameters can appear at any time. Integrations must tolerate response fields they do not recognise.

Deprecation

When a new version replaces an old one:

1. The change is announced on the changelog, naming the new version path.
2. The old version keeps working, unchanged, for at least 6 months from the announcement.
3. After the deprecation window, the old version is retired. Retired paths return 410 and, later, 404.

Deprecated versions are closed to new integrations: build against the current version documented on these pages. If a deprecation timeline is a problem for your integration, contact us.