---
title: "Versioning & preview"
description: "How the Bodo API is versioned: /v1 in the path, a date version in a header, a preview channel per request. What counts as breaking, how long a replaced version keeps running and what a deprecation looks like."
lang: en
url: https://developers.bodo-app.com/en/guides/versioning/
apiVersion: 2026-11-01
---

# Versioning & preview

How the Bodo API is versioned: /v1 in the path, a date version in a header, a preview channel per request. What counts as breaking, how long a replaced version keeps running and what a deprecation looks like.

- **/v1**: The bracket in the path. There will only be a `v2` for a change of paradigm.
- **Bodo-Version: 2026-11-01**: Date version in a header. Without the header the pin of the key applies; every response names the version it used.
- **Bodo-Preview: true**: A moving channel for new operations. Breaking changes are allowed there and are listed in the changelog. Not a basis for production, cannot be pinned.

## Life cycle of the versions

Drawn from the API's version registry. A replaced version keeps running for 12 months after its successor is released; brownouts fall into the last 6 weeks before that.

**Life cycle of the API versions**

- `2026-11-01`: released 1 Nov 2026 · running, no successor; Support ends only 12 months after a successor is released

[Download openapi.2026-11-01.json](/openapi/openapi.2026-11-01.json)

## Which version applies to my call?

| Order | Source | Example |
| --- | --- | --- |
| 1 | Header in the request | Bodo-Version: 2026-11-01 |
| 2 | Pin of the key (the current stable when it was created) | versionPin: 2026-11-01 |
| – | There is no organization default | on purpose, so there is no hidden state |

## Breaking only with a new version

- field or operation removed or renamed
- type of a field changed
- new required field in the request, stricter validation
- changed default, removed enum value
- changed `code`, changed semantics

## Not breaking: live at once, in the changelog

- new optional field in the request
- new field in the response
- new enum value in the response (`x-extensible-enum`)
- new operation
- new `code` for a new condition

## Tolerant reader

Ignore unknown fields and enum values, never fail on them.

Breaking versions: at most 2 a year · Support window: 12 months

[What a deprecation looks like](/en/guides/migrate-2027-05-01/)