Versioning & deprecation
Versions
The API version is in the path: /v1/… for the OpenAI-compatible API and
/generation/v1/… for the platform-native API. Everything under v1 follows the
rules below.
What can change without notice
These changes are backwards compatible and can ship at any time, so build clients that tolerate them:
- New endpoints.
- New optional request fields and parameters.
- New fields in responses.
- New values in enums such as
status,workflowand webhook event names. - New error codes. (Handle errors by HTTP status; see Errors.)
- New models in the catalog.
- Wording of error
messagestrings.
Breaking changes
A breaking change is one that can stop a working client: removing or renaming an endpoint or field, making an optional field required, changing a field's type, or changing an endpoint's success status code.
- Breaking changes go into a new version (
v2), not intov1. - When a
v1endpoint or field is deprecated we announce it in the changelog at least 90 days before it is removed. - Exceptions: urgent security or legal fixes may need a shorter notice. We announce them in the changelog as soon as we can.
Models
Models come and go as makers release and retire them. When a model is retired we
announce it in the changelog with at least 30 days' notice where the maker allows
it, and name a replacement where there is one. Requests to a retired model ID return
404.