API versioning & breaking changes
Set the version header
Send the X-Moov-Version header with every request, set to a version such as v2026.07.00. Without the header, Moov uses the oldest supported version, v2024.01.00. See the version reference for every version and what changed.
curl -X GET "https://api.moov.io/accounts/{accountID}" \
-H "Authorization: Bearer {token}" \
-H "X-Moov-Version: v2026.07.00"
How API versions work
API versions use the format vYYYY.QQ.BB:
| Part | Meaning |
|---|---|
YYYY |
The year |
QQ |
The two-digit month that starts the quarter: 01, 04, 07, or 10 |
BB |
The build number, starting at 00, for later builds in the same quarter |
For example, v2026.01.00 is the API version for Q1 2026.
Each quarter's version is published one quarter early with an in development status. Breaking changes can land in an in development version without notice, so use it with caution. On the first day of its quarter, the version is officially released, and no breaking changes are added to it after that. The next quarter's version then becomes the new in development version.
For example, v2027.01.00 is published as in development on October 1, 2026. On January 1, 2027, v2027.01.00 is released and v2027.04.00 is published as in development.
How Moov announces breaking changes
Moov can change the API at any time. Moov communicates breaking changes to you directly, with enough time to update your integration, and announces them in the changelog (subscribe for notifications). Moov may also update its SDKs with any of the breaking changes below; SDK fixes can result in changes to the API.
In the tables below, "field" means a field in a request or response body, a query parameter, a header value, or any other value the API uses.
Breaking changes
These changes require you to update your integration.
| Change | Example | Impact on your integration |
|---|---|---|
| Removing a field | Removing lastName from the user profile response |
Code that depends on the field gets errors or incomplete data |
| Changing a field's data type | Changing id from a string to an integer |
Code expecting a string may fail to parse the integer |
| Changing the response structure | Changing a flat JSON response to nested JSON | Parsing based on the old structure must change |
| Removing an endpoint | Removing GET /users/{userID}/profile |
Calls to the endpoint stop working |
| Changing an endpoint URL | Moving /user to /profile/user |
Calls fail until they use the new URL |
| Changing required request fields | Making email required where it was optional, or adding a new required field |
Requests fail if the field isn't provided |
| Changing an HTTP method | Changing POST to PUT to create a resource |
Requests must use the new method |
| Changing a default value | Changing the default sortOrder from ASC to DESC |
Code that relied on the old default must adapt; otherwise it can be ignored |
| Changing a date format | Changing MM-DD-YYYY to YYYY-MM-DD |
Date parsing must adapt |
| Adding authentication requirements | Requiring an API key on an endpoint that didn't need one | You must add the new authentication |
| Renaming a field | Renaming username to user_name |
References must use the new name |
| Changing pagination logic | Switching from page-based to cursor-based pagination | Pagination handling must change |
| Changing a field's valid values | Removing a previously valid enum value | Requests must use a different value |
| Adding a response field that requires action | Adding a disabledOn timestamp that marks the resource as disabled and non-interactable |
New fields are usually non-breaking, but this one changes how you can use the resource |
| Adding an enum value that Moov sets and you read | Adding DISABLED to an existing status enum |
Code that doesn't handle the new value may fall through to a catch-all error |
| Changing a specific status code in a bug fix | Changing 404 Not Found to 409 Conflict |
Code that expects 404 for that case must handle 409 |
Non-breaking changes
These changes don't require updates, as long as your integration follows common API client practices, such as ignoring unknown response fields.
| Change | Example | Why it's non-breaking |
|---|---|---|
| Adding an optional response field | Adding an optional middleName to the user profile response |
Unaffected, unless you strictly validate response fields |
| Adding an informational response field | Adding a createdAt or updatedOn timestamp that's always returned |
Unaffected, unless you strictly validate response fields |
| Adding an endpoint | Adding GET /users/{userID}/friends |
Existing calls don't change |
| Deprecating an endpoint with adequate notice | Marking GET /users/{userID}/profile deprecated while it still works |
The endpoint keeps working while you update |
| Improving performance or fixing non-behavioral bugs | Faster responses, or fixing a documentation typo | The interface and behavior don't change |
| Adding a response header | Adding X-Request-ID to responses |
Existing headers don't change |
| Adding an enum value that you set and Moov reads | Adding NEW_FEATURE to an existing action enum |
You only receive values you sent |
| Fixing an error response | Changing 500 Internal Server Error to 409 Conflict |
A 500 is never a valid response from a working API, so replacing it with a defined error code is a fix, not a breaking change |
| Ordering arrays consistently when no order is specified | Returning ['b', 'a'] without an ordering query argument |
Array items don't depend on order |
| Ordering maps consistently | Returning {"b": true, "a": true} |
Values are looked up by key |
Next steps
- Version reference: every API version and what changed in it
- Changelog: new features, fixes, and API versions as they ship
- Authenticate API requests: the other headers every request needs