The version travels with your code.

Send X-API-Version to choose the response contract for a request. When neither version header is sent, the request uses your team's saved default. Keep the same keys, lookup URLs and authentication.

New teams start on 2.1.0. Existing teams keep their saved default until an owner or admin changes it. Publishing a new API version does not upgrade existing teams.

Choose a version in your application

Use an exact supported version, such as 2.1.0. Configure the header once in your HTTP client so it accompanies every lookup.

curl "https://api.parseapi.com/name/Grace%20Hopper" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Version: 2.1.0"

The request header takes precedence over the team default for that request. The X-API-Version response header identifies the exact version that answered, such as 2.1.0. The request does not change the saved default or any key.

Existing integrations can still send Parse-Version. If both headers are sent, their values must match.

The public, keyless IP and User-Agent self-lookups also accept the header. With neither version header, they use 1.0.0.

Keep a team default

Settings → API version controls requests with neither version header. Team owners and admins can review the release notes and explicitly confirm the upgrade. Applications that send a version keep using that version.

Upgrading the team default is permanent. Leave it unchanged while older integrations depend on it. Updating an application that sends its own version needs no dashboard change. Requests already in progress can finish with their original version.

Read the matching reference

API version	Contract	JSON reference
2.1.0	Plan detail at natural field homes, complete Carrier/HLR results and explicit Email verification.	Browse 2.1.0
2.0.0	Simpler core responses, expanded deep detail and consistent local-name fields.	Browse 2.0.0
1.0.0	Existing response fields and depth.	Browse 1.0.0

The API root and unversioned endpoint help show the latest reference. Versioned links stay on their named version, such as Carrier 1.0.0 and Carrier 2.0.0. Browsing the reference does not change your team's API version or lookup URLs.

A version preserves the documented contract, not a historical copy of the data. Current facts, observations and corrections continue to update.

Test in staging, then deploy

Read the release notes and compare the references for the endpoints your app uses. Check field names, types, nulls, depth and error behavior.
Pin the existing application to its current contract before preparing an upgrade. Keep that version alongside the application code so rollback restores both.
In staging, set X-API-Version: 2.1.0 or use an SDK that pins that contract. Update field access and test the results.
Deploy the tested code and its version setting. Keep your existing production key. Verify the response header and the application's results.

In API 2.1, paid profiles include available plan detail at their resource's natural field paths. Existing explicit HTTP depth options retain their behavior. A list item owns its own fields; Weather measurements stay in current. Unavailable optional fields are omitted; included unknown values remain null. Carrier and HLR return the complete purchased result without a deep option. Email mailbox checks move to explicit POST /email/verify with a JSON email body.

// Earlier response
result.deep?.population

// API 2.1.0
result.population

During a rolling deployment, old and new instances can request their own contracts. While the earlier version is supported, rolling back the application also restores its version pin. A build with no version pin still depends on the team default.

Match your SDK and API version

SDK package numbers and API contract numbers are separate. The maintained SDK line uses 2.1; existing factories and methods select it. Upgrading requires changing old .deep field reads. Older API contracts remain a temporary migration bridge until callers move. Version-pinned SDKs send X-API-Version: 2.1.0 automatically, matching their response types. Keep the package version in your application's dependency lockfile and review its release notes before upgrading.

Previously published SDK/MCP 0.4.0 packages target API 2.0.0 and 0.3.2 packages target API 1.0.0, but omit the version header and depend on the team default. Installing a package leaves that saved default alone. Use a package whose documented API contract matches your application.

What a version number means

The release history records each version's changes. Read the 2.0.0 release notes or the 1.0.0 baseline.

1.0.1: Patch: a compatible correction.
1.1.0: Minor: compatible additions. Allow new response fields and documented open-string values.
2.0.0: Major: changes that can require an application update, such as moving or removing fields.

An invalid or unsupported header value returns invalid_request (400). Use one exact version, not latest, a range or a list. A selected retired version returns api_version_retired (410). Neither error silently selects another contract.