Versioning
What can change without notice, and what never will.
The major version is part of the path: /v1. Within v1:
- We add without notice. New endpoints, new optional request fields, new response fields, new enum values, new webhook event types. Ignore fields you do not know and handle unknown enum values with a default branch.
- We never break. Removing or renaming a field, changing a type, making an optional field required, or changing what an existing value means ships as a new major version, with at least six months during which both versions run side by side.
Every change is listed in the changelog.
What the status labels promise
LiveThe operation is served by the v1 API today: try it in development with your credentials.
BuildingIn development for the v1 API. The contract is set; the route is not served yet.
PlannedDesigned and scheduled for the v1 API. The contract can still change; the route is not served yet.
An operation labeled Building or Planned is part of the v1 contract. When it goes live it keeps its path, and any change to its shape before then is listed in the changelog.
Earlier paths
Customers already in production reach the live capabilities at earlier paths. Those keep working; the /v1 routes open with the new gateway, and your account team will agree the switch date with you.