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

# Versioning

The tipee API is versioned. Each time a breaking change is introduced, a new version is released. The API version name is based on the date when it was released. For example, the API version `25.09.01` was released on Mon, 01 Sep 2025.

You can select a version from the header of this documentation to view the reference for that specific version.

## Selecting an API version

When issuing calls to the API, you must provide a version using the `Tipee-Version` header:

```
Tipee-Version: 26.07.01
```

This header ensures that the API processes your request and formats its response according to that version's behavior.

The value is a date in the `YY.MM.DD` format — it does not need to match an official release date exactly.

### Version resolution

When you provide a date that does not correspond to a released version, the API automatically resolves it to the **closest released version on or before that date**.

For example, with the currently released versions `25.09.01` and `26.06.25`:

| Requested version | Resolved version |
| ----------------- | ---------------- |
| `25.09.01`        | `25.09.01`       |
| `26.01.15`        | `25.09.01`       |
| `26.06.25`        | `26.06.25`       |
| `27.07.01`        | `26.06.25`       |

This is intentional: it lets you **pin your integration to a date** rather than to a specific release. A common pattern is to set the `Tipee-Version` header to the date your integration went live. The API is then guaranteed to keep serving the exact behavior that was stable on that date, even as new versions are released afterwards.

## Breaking vs. non-breaking changes

<Tabs>
  <Tab title="Non-breaking changes">
    Additive changes are available in **all supported API versions** and should not break an integration:

    | Type of change                     |
    | ---------------------------------- |
    | Adding an operation                |
    | Adding an optional parameter       |
    | Adding an optional request header  |
    | Adding a response field            |
    | Adding a response header           |
    | Adding enum values (request)       |
    | Removing enum values (response)    |
    | Change the order of the parameters |
  </Tab>

  <Tab title="Breaking changes">
    Breaking changes are released in a **new API version**. They can potentially break an existing integration:

    | Type of change                                        |
    | ----------------------------------------------------- |
    | Removing an entire operation                          |
    | Removing or renaming a parameter                      |
    | Removing or renaming a response field                 |
    | Adding a new required parameter                       |
    | Making a previously optional parameter required       |
    | Changing the type of a parameter or response field    |
    | Adding enum values (response)                         |
    | Removing enum values (request)                        |
    | Adding a new validation rule to an existing parameter |
    | Changing authentication or authorization requirements |
  </Tab>
</Tabs>

## Preview endpoints

New endpoints are first released in the `preview` version, available in the version dropdown of this documentation alongside the stable versions. In that version, each endpoint carries a badge: <span data-nav-tag="preview" style={{padding: '2px 6px', borderRadius: '6px', fontWeight: 'bold', fontSize: '0.75rem'}}>preview</span> for endpoints that are not part of a stable version yet, and <span data-nav-tag="stable" style={{padding: '2px 6px', borderRadius: '6px', fontWeight: 'bold', fontSize: '0.75rem'}}>stable</span> for endpoints already released in a stable version (which remain visible there, as they keep working in every later version).

To call preview endpoints, use the `preview` version in the `Tipee-Version` header:

```
Tipee-Version: preview
```

<Warning>Preview endpoints should only be used for testing purposes. They are transitioning toward the next stable release — their behavior may change without prior notice. Using them in production is discouraged, especially if you are not able to adapt your integration quickly when a breaking change occurs.</Warning>

## Deprecation and backward compatibility

When a new REST API version is released, the previous API version will be supported for at least **6 more months** following the release of the new API version.