Versioning

What's compatible (we may do without notice)

• Add a new endpoint.
• Add a new optional field to a request body.
• Add a new field to a response body.
• Add a new event type or new field inside data on an existing event.
• Add a new error code (existing codes don't change meaning).
• Tighten validation around values already documented as invalid.

What's incompatible (next major only)

• Remove or rename a field.
• Change a field's type.
• Change response shape from object to array or vice versa.
• Change the meaning of an existing error code.
• Remove an event type.

Deprecation

1. Annotated in OpenAPI.
2. Responses carry a Deprecation header (RFC 9745) with a sunset date.
3. Minimum 6 months between announcement and removal.