> ## 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 the version using the `Tipee-Version` header:

```
Tipee-Version: 25.09.01
```

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

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