One version for your team.

Choose it in Dashboard → API version. It applies to every key and connected app in the team.

Existing teams keep 1.0.0. New teams start on 2.0.0. New and replacement keys use their team's setting. Publishing a new API version does not upgrade existing teams.

Review in the dashboard

Open API version to see your team's current version and the available update. Review the release notes, then explicitly confirm the upgrade when your integrations are ready. Team owners and admins can change this setting. Keep using the same key, API URL and authentication header. There is no version parameter to add to each request.

The Parse-Version response header identifies the version that answered. Check it after changing your team's setting before relying on the new response. Requests already in progress can finish with their original version.

The public, keyless IP and User-Agent self-lookups keep 1.0.0. Requests with a key use the team's selected version.

Read the matching reference

API version	Contract	JSON reference
1.0.0	Existing response fields and depth.	Browse 1.0.0
2.0.0	Simpler core responses, expanded deep detail and consistent local-name fields.	Browse 2.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.

Upgrade when your team is ready

Read the release notes and compare the references for the endpoints your app uses. Check field names, types, nulls, depth and error behavior.
Test the target version in a separate development team with a compatible SDK. Update code that reads changed fields in every affected integration.
Review and confirm the upgrade for your production team in the dashboard after those checks pass. The change applies to all its keys and connected apps. Verify the response header and your integrations' 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

While the earlier version is supported, you can review and confirm a return to it in the dashboard. Keep the matching application code available if you need to return to it.

Match your SDK and API version

SDK package numbers and API contract numbers are separate. SDK/MCP 0.4.0 targets API 2.0.0; 0.3.2 targets API 1.0.0. Keep the team on the API version its installed package supports, and read the release notes before upgrading.

Installing an SDK does not change your team's saved version. Typed responses describe the API contract that SDK supports; they are not a union of every historical response. The same rule applies to MCP: its supported tools and response descriptions must match the connected team's version.

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 inactive team is not automatically upgraded. If a version is retired, requests from a team still set to it receive api_version_retired (410), rather than silently receiving another version.