> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyclemate.club/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```text theme={null}
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`:

```json theme={null}
{
  "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](/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.