Skip to content

Versioning

The API is versioned in the path. Additive changes ship in place; breaking changes go to a new major version so your integration keeps working.

Path version

Every endpoint is prefixed with /api/v1. When a breaking change is necessary, it ships under /api/v2 — the previous major stays available during a documented migration window.

What's an additive (non-breaking) change

These can appear within /api/v1 without a version bump — write your client to tolerate them:

  • New endpoints or new resource types.
  • New optional fields in a response.
  • New optional query parameters.
  • New error.code values.
  • New webhook event types.

Write a tolerant client

Ignore unknown fields rather than failing on them, and treat the resource set as extensible. That way additive changes never break you.

What's a breaking change

These only ship in a new major version:

  • Removing or renaming a field, endpoint, or scope.
  • Changing a field's type or meaning.
  • Making a previously optional parameter required.
  • Changing the response envelope structure.

Webhook versioning

Webhook deliveries carry an api_version field so you can branch on payload shape. Breaking changes to event payloads are versioned the same way as the REST API.