Skip to main content

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
Field names are 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 engines as “other” rather than crashing.
  • Don’t depend on field order in JSON objects or on the exact wording of title and detail in errors. Branch on the problem type instead. See Errors.
  • Pin to the path, not the date. X-Api-Version is 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 a schema_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.
Last modified on November 18, 2026