Versioning
What can change within /v1, how breaking changes and model retirements are handled.
The API version is in the path: /v1. Within a version we only make changes that don't break correct
clients. Anything that would break one gets a new version.
Changes we make within v1
- New endpoints, and new optional request fields and query parameters.
- New fields in responses and webhook events.
- New values in enums, such as statuses, error codes, modes, reference roles and event types.
- New models, and new accepted values for a model's parameters.
- New
X-response headers.
Write clients that tolerate these. Ignore fields you don't know, and treat unknown enum values as
"other", for example an unknown error.code as not retryable. The SDKs already do this.
Breaking changes
Removing or renaming a field, endpoint or enum value, changing a type, making an optional field
required, or changing what a status means all need a new version. When there is a /v2, /v1 keeps
working for at least 12 months after /v2 becomes generally available. We announce it in the
changelog and by email to organization owners.
Every change to the OpenAPI spec is checked for breaking changes before it ships.
Models
Models have a lifecycle: preview, ga, deprecated and retired.
- Preview models may still change their parameters and limits.
- Deprecated models keep working until
retires_at, which is at least 90 days after deprecation, or as long as the provider allows if it retires the model sooner. They're marked on their model page and inGET /v1/models. - Retired models reject new generations with
model_not_found. Existing generations and their files are unaffected.
A provider sometimes changes a model under the same name. When that changes results noticeably, we add it as a new model id rather than swapping it in place.
SDKs
The SDKs follow semantic versioning. New API features arrive in minor versions. A major version can drop old runtimes (Node.js and Python releases past end of life) or change method signatures, and its release notes say what to change.