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

# API Versioning

> How Platform API versions work, how to set a version on each request, and how long each version is supported.

The Platform API uses dated versions, such as `v20260929`. MX releases a new version when a change isn't backwards compatible. A version's changes may affect one endpoint or many.

## Specify a version

Every request must include a valid API version. Set it in the `Accept-Version` header, and set `Accept` to `application/json`:

```bash theme={null}
curl -X GET 'https://int-api.mx.com/users' \
  -H 'Accept: application/json' \
  -H 'Accept-Version: v20260929' \
  -H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}'
```

<Note>
  The legacy header `Accept: application/vnd.mx.api.v1+json` still works and requests v20111101. Move to `Accept: application/json` with an `Accept-Version` header.
</Note>

A request without a valid version returns `406 Not Acceptable`. This includes requests that send `Accept: application/json` without an `Accept-Version` header, and requests for a version that doesn't exist.

## Version support

Each version is supported for at least 18 months after release. To announce a version's end of life, MX may set a deprecation date for it when a new version is released. After a year-long deprecation period, the version is sunset.

* **Supported:** MX actively supports the version and keeps its documentation up to date.
* **Deprecated:** You can still use the version for 12 months after its deprecation date, but its documentation is no longer updated.
* **Sunset:** At the end of the deprecation period, MX removes the version, and requests to it return an error.

Deprecating and sunsetting individual endpoints follows its own timeline and doesn't create a new version. For endpoint dates, see [Deprecations](./deprecations).

### Breaking changes

These changes aren't backwards compatible, so MX releases them only in a new version:

* Adding a required request parameter, or making an optional parameter required
* Removing a request parameter from the URL or request body (optional or required)
* Changing the meaning of a parameter
* Changing the type of a parameter
* Adding a validation rule to an existing parameter
* Removing a response field
* Renaming a response field
* Removing enum values
* Changing the structure of a response body in a way that isn't backwards compatible
* Changing the type of data a response field returns (for example, from an integer to a string)
* Removing, moving, or changing endpoint paths

### Non-breaking changes

These changes are backwards compatible and can be released in any version at any time. Build your integration to tolerate them:

* Adding API endpoints
* Adding an optional request header
* Adding optional parameters to existing endpoints
* Adding fields to existing response bodies
* Adding a response header
* Changing the order of properties in API responses
* Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings
* Making a required request parameter optional

For non-breaking changes, see the [Changelog](/resources/changelog).

## Versions

| Version | `Accept-Version` header | Description | Upgrade guide |
| :- | :- | :- | :- |
| **v20260929** | `v20260929` | Current version. Layered response structure, updated aggregation behavior, and sunset managed endpoints. | [Upgrade to v20260929](./upgrade-guide#upgrading-from-v20250224-to-v20260929) |
| **v20250224** | `v20250224` | Product-based institution search and filtering, and the `data_request` field for product-based aggregation. | [Upgrade to v20250224](./upgrade-guide#upgrading-from-v20111101-to-v20250224) |
| **v20111101** | `v20111101` | Legacy version. Not recommended for new integrations. | N/A |