API CHANGE EXAMPLE
API version change release notes example
A useful API change note separates the new capability, the migration action, the compatibility window, and any related fix.
RAW CHANGES
Engineering input
- feat(api): launch /v2/events with cursor pagination
- feat(api): add status and created_after filters to v2 events
- docs(api): publish v2 migration guide; keep v1 available through 2026-10-31
- fix(api): preserve idempotency keys when v2 writes retry
CUSTOMER-READY DRAFT
API v2 adds cursor pagination and clearer event filtering
API v2 is available now. Existing v1 event requests remain supported through October 31, 2026, giving integrations a defined window to move using the published migration guide.
What changed
- The new /v2/events endpoint uses cursor pagination.
- Event requests can filter by status and creation time.
Migration
- Move event-list requests to /v2/events by October 31, 2026, using the published v2 migration guide.
Fixes
- Retried v2 writes now preserve the original idempotency key.
EDITING NOTES
Why this draft works
- Puts the compatibility date beside the migration action.
- Separates new API behavior from the retry fix.
- Uses only the date and capabilities present in the engineering input.