Our promise

We don't break integrations without warning. APIs evolve — new features get added, mistakes get corrected — but we follow strict rules about what counts as a breaking change and how breaking changes are introduced.

This page covers:

• What we consider backward-compatible (we add these freely)
• What we consider breaking (we introduce these as new versions)
• How long previous versions remain supported
• How to detect schema changes before they affect your integration

Versioning by API type

What's a breaking change

A change is breaking if existing well-formed integrations could stop working after the change. Examples:

• Removing a field from a response
• Renaming a field or operation
• Changing the type of a field (e.g. string to integer)
• Removing an enum value
• Adding a required request parameter
• Changing authentication or authorisation semantics
• Reducing the maximum value of a numeric range

Any of these will only happen in a new major version (e.g. v2).

What's not a breaking change

Backward-compatible additions can be made to the current version at any time, without prior notice:

• Adding a new optional request parameter
• Adding a new field to a response
• Adding a new enum value
• Adding a new operation or endpoint
• Adding a new error code variant (existing handling for unknown errors should still work)
• Performance improvements that don't change wire behaviour

We recommend designing your integration to ignore unknown fields and unknown enum values gracefully — this lets you benefit from new fields without code changes on your side.

Version lifecycle

When we introduce a new major version (e.g. v2):

1. Both v1 and v2 run in parallel for at least 6 months
2. We send deprecation notifications through email and a banner in this portal at 6, 3, and 1 month marks
3. After the deprecation period, v1 returns a 410 Gone for new requests and is eventually removed

You're encouraged but not required to migrate to the latest version. As long as a version is still supported, you can continue to use it.

Detecting schema changes

For machine-checkable change detection, integrate one of these into your CI pipeline:

# REST: pull the OpenAPI spec
curl https://api.example.com/stats/v1/openapi.yaml -o latest.yaml
diff prev.yaml latest.yaml

# GraphQL: introspect the schema
curl https://api.example.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __schema { types { name fields { name } } } }"}' \
  > latest-schema.json
diff prev-schema.json latest-schema.json

# MCP: list available tools
curl https://api.example.com/mcp/stats \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' \
  > latest-tools.json

If you see additions, no action needed. If you see removals, that means we've started a deprecation cycle — check your email for the notification and your deprecation timeline.

Quick reference

If you're unsure about a specific change you've seen and whether it should be considered breaking, contact our partner support channel.