The version travels with your code.

Choose a version in your application

Use an exact supported version, such as 2.0.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 "Parse-Version: 2.0.0"

The request header takes precedence over the team default for that request. The Parse-Version response header identifies the version that answered. The request does not change the saved default or any key.

The public, keyless IP and User-Agent self-lookups also accept the header. Without it, they use 1.0.0.

Keep a team default

Settings → API version controls requests that omit Parse-Version. Team owners and admins can review the release notes and explicitly confirm the upgrade. Applications that send a version keep using that version.

Leave the default 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

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

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

For example, Carrier 1.0.0 returns state in core. In 2.0.0, request ?deep=true and read deep.state. This detail is included in the same Carrier unit. A version change keeps the request URL and key valid; it does not rewrite your field-reading code.

Field access example:

// API 1.0.0
result.state

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

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 that omits the header still depends on the team default.

Match your SDK and API version

SDK package numbers and API contract numbers are separate. Version-pinned SDKs send Parse-Version: 2.0.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.