API versioning and changes
The API is versioned so your integrations keep working as the platform evolves. New capabilities are added under a version identifier, and older versions continue to respond as documented until they are formally retired. This page explains how versions are identified, what counts as a breaking change, and how to keep your code compatible over time. (Confirm the exact version identifier and header names in your account.)
Reference
| Item | Example value | Description |
|---|---|---|
| Version identifier | v1 | The version your requests target. Usually part of the base path (for example, /api/v1/...) or sent as a header. |
| Base URL | https://api.example.com/api/v1/ | The versioned root for all endpoints. |
| Version header | X-API-Version: 2026-01-15 | Optional date-based header some accounts use to pin behavior. (Confirm whether your account uses date-pinning.) |
| Non-breaking change | New optional field in a response | Added without a version bump; safe to ignore in existing code. |
| Breaking change | Removed field, renamed field, changed type | Introduced only under a new version identifier. |
| Deprecation notice | Deprecation / Sunset response headers | Signals a version or endpoint is scheduled for retirement, with a date. |
| Retirement window | Typically several months | Grace period after deprecation before an old version stops responding. |
Notes
- Pin your version. Always send requests to an explicit version rather than an unversioned or "latest" endpoint, so a future release cannot silently change responses.
- Tolerate additions. Treat new response fields and new enum values as expected. Parse only the fields you use and ignore unknowns rather than failing on them.
- Watch deprecation headers. Log any
DeprecationorSunsetheaders you receive and review them during maintenance so migrations happen before a cutoff, not after an outage. - Test against a sandbox. Validate a new version in a test environment before switching production traffic. (Confirm sandbox availability in your account.)
- Coordinate token changes. Personalization and payload formats can shift between versions; re-check field names and personalization tags after upgrading.
Related
Canonical terms: Author, Edition, Folder (Project Folder), Broadcast. See the Glossary.