How versions work
The API has two version markers:
You never send a version header. The path you call decides the major version, and every successful response tells you which contract date it follows.
Breaking and additive changes
Breaking: new major version
- Removing or renaming a field
- Changing a field’s type
- Changing what a status code means
Additive: same path, new date
- A new field in a response
- A new endpoint
- A new scope
snake_case and part of the contract: a rename is always a breaking change.
Write clients that survive additive changes
- Ignore fields you don’t know. New fields can appear in any response object. Don’t fail on them, and don’t use strict schemas that reject them.
- Handle unfamiliar values gracefully. For example, treat an engine id you don’t recognize in a brand’s
enginesas “other” rather than crashing. - Don’t depend on field order in JSON objects or on the exact wording of
titleanddetailin errors. Branch on the problemtypeinstead. See Errors. - Pin to the path, not the date.
X-Api-Versionis informational. Log it if you want to know when the contract moved.
Deprecation
When a major version is deprecated, the API changelog announces it and names its replacement, and the deprecated version keeps working for at least six months before it’s removed.Webhook payloads
Webhook deliveries version their payload separately, with aschema_version field in every event. It’s 1 for every event today. See Webhook events.
Next steps
API changelog
Every change to the API, MCP server and webhooks.
Errors
Problem types are part of the contract too.