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

# Versioning

> How the API is versioned, and which changes can reach you without a new version.

The version is in the path. Every endpoint today is under `/v1`.

## Changes we make within a version

We add to `v1` without notice. Build your integration so these changes don't break it:

| Change                                                                                        | What your code should do                                                                                      |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| A new endpoint                                                                                | Nothing.                                                                                                      |
| A new field in a response or an event                                                         | Ignore fields you don't use. Don't fail on fields you don't recognise.                                        |
| A new event type                                                                              | Ignore types you don't handle.                                                                                |
| A new value in a list of values, such as an order state, a `reject_reason` or an error `code` | Handle an unknown value with a safe default. Don't generate clients with closed enums that reject new values. |
| A new optional request field                                                                  | Nothing.                                                                                                      |
| New wording in `message` or `reason`                                                          | Nothing. These are for people to read, so never match on them.                                                |

## Breaking changes

These changes never happen within a version:

* removing or renaming an endpoint, a field or a value,
* changing a field's type or meaning,
* making an optional request field required,
* changing the status code or error `code` for an outcome.

A breaking change comes in a new version, such as `/v2`, and we tell you in advance. We record changes in the [changelog](/changelog).