Versioning

URL versioning

Every endpoint is under /api/v1/. When we need to make a breaking change, a new /api/v2/ path ships alongside /api/v1/. Additive changes (new endpoints, new optional fields, new enum values) land on v1 continuously and are non-breaking.

What counts as breaking

• Removing or renaming an endpoint, query parameter, or response field.
• Narrowing a response field's type (e.g., string → enum).
• Removing an enum value.
• Changing an error code's code string.
• Requiring a previously optional request field.

What counts as non-breaking

• New endpoints under /api/v1/.
• New optional request fields with sensible defaults.
• New response fields (clients must ignore unknown keys).
• New enum values (clients must tolerate unknown strings).
• New webhook events (subscribers that don't subscribe to them don't care).

Deprecation

When v2 ships, v1 enters a 3-month read-only window: GETs keep working; mutations return a deprecation banner header. At the end of the window, v1 returns 410 GONE. All deprecations are announced via the PSG status page and in the Deprecation response header on the soon-to-be- retired endpoints.

Staying current

• Platform status is at /status; release notes are at /support/release-notes.
• Inspect Deprecation and Sunset response headers in monitoring — both advertise upcoming retirement.
• Treat the filtered OpenAPI spec (/api/v1/public/openapi.json) as the machine-readable source of truth.