Skip to main content

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, workflow and webhook event names.
  • New error codes. (Handle errors by HTTP status; see Errors.)
  • New models in the catalog.
  • Wording of error message strings.

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 into v1.
  • When a v1 endpoint 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.