Skip to main content
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:
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.
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.

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

​
Versions