Versioning and changelog

The API version is in the path: /api/v1. Within v1 we only make changes that don't break a correct integration:

• New endpoints, new optional parameters, new fields in responses and webhook payloads.
• New event types (endpoints subscribed to * receive them; ignore types you don't know).
• New error codes for new situations (treat an unknown code by its HTTP status).
• New values in status-like fields only where documented as open.

Anything that would break an integration (removing or renaming a field, changing a type, making an optional parameter required) would ship as /api/v2, announced here and by email to technical contacts with at least six months' overlap.

Build to last

• Parse JSON leniently: ignore fields you don't use.
• Branch on code, never on error text.
• Handle unknown event types by acknowledging them with 2xx and ignoring them.
• Don't depend on the order of keys in JSON or of items you didn't sort.

Changelog