Versioning
What can change inside /v1, and what can't.
The API version is in the path: /api/v1. Inside v1, changes are additive and announced in the changelog.
Can change without notice
Section titled “Can change without notice”- New endpoints, new optional request fields and new query parameters.
- New fields in responses. Ignore fields you don’t know.
- New values in open lists: platforms, content types, error messages, notification and webhook event types, pre-flight issue codes. Handle unknown values gracefully.
- Error
messagewording. Match oncode, not on the message. - Platform limits in
GET /content-types, when a platform changes its rules.
Won’t change inside v1
Section titled “Won’t change inside v1”- Removing or renaming endpoints, fields or
codevalues. - Changing a field’s type or meaning.
- Making an optional request field required.
If something must break, it goes into /v2, and /v1 keeps working for at least 6 months after it’s announced.
Tool names and their required inputs follow the same rules. New tools and optional inputs may appear at any time;
clients get them from tools/list.