An API version belongs with the code

An API upgrade changes the code that reads its responses. It should be possible to test that change in staging and deploy it with the application, while production keeps using the earlier contract.

That is why we put the version in the request. The Parse-Version header selects the contract that the application was written for:

X-API-Key: YOUR_API_KEY
Parse-Version: 2.0.0

The key still identifies the team. The version describes what the code expects. Requests without the header keep using the team's saved default, so an existing integration can carry on while another prepares an upgrade.

Consider Carrier. Version 1.0.0 returns the issuing state as state. In 2.0.0, that detail lives in deep.state and needs ?deep=true on the request. The field-reading code changes with it:

// API 1.0.0
result.state

// API 2.0.0, requested with ?deep=true
result.deep?.state

For that upgrade, first pin the existing application to 1.0.0. Then set 2.0.0 in staging, update the field access, and test. When the new code goes to production, its version setting goes with it. The production key stays where it is.

During a rolling deployment, the old instances can keep asking for 1.0.0 while the new instances ask for 2.0.0. Rolling back restores the old code and its old version setting. This works because both builds declare their contract. A build that omits the header still depends on the team default.

The official SDKs, starting with package version 1.0.0, send Parse-Version: 2.0.0 automatically. Pinning the SDK package in the application's dependency lockfile keeps the response types and requested contract together. Earlier package versions keep their original behavior.

The dashboard's Default API version remains useful for requests that don't select a version. An owner or admin can change that fallback after reviewing the release notes. Applications with an explicit version keep their own contract, so deploying one application won't require a dashboard change.

The Parse-Version response header confirms which version answered. Unknown version values return an error, and a retired contract returns api_version_retired. A request won't silently switch to a different shape.

Versioning preserves the documented response contract while the underlying facts continue to update. Keeping a version doesn't freeze exchange rates, weather observations, or other changing data. The versioning guide links to the matching references and the staging-to-production workflow.