Unlimited Open Source Models

Get Plan
Skip to main content

API versioning and deprecation policy

ModelsLab versions its APIs in the URL path. The generation API is served at /api/v6, /api/v7 and /api/v8; the agent control plane is served at /api/agents/v1. A breaking change is only ever introduced on a new versioned base path — the path you integrated against keeps the behaviour it had on the day you integrated.

Current version status

VersionStatusDeprecated onSunset on
/api/v6Supported——
/api/v7Supported——
/api/v8Current——
/api/agents/v1Current——

How deprecation is signalled

You do not have to read a changelog to find out that a version is going away. Every response from a versioned API path carries its lifecycle state in the headers, so an integration learns about a sunset from the traffic it is already making:

  • ModelsLab-Api-Version — the version segment this request resolved to.
  • ModelsLab-Api-Lifecycle — current, supported or deprecated.
  • Deprecation (RFC 9745) — an HTTP date. Sent only once a version is deprecated.
  • Sunset (RFC 8594) — the HTTP date after which the version stops responding.
  • Link: <…>; rel="deprecation" — a pointer back to this page, sent on every versioned API response.

Notice period

We commit to at least 90 days between the Deprecation date and the Sunset date of any API version. During that window the deprecated version keeps working unchanged. The same commitment is published as x-versioning.minimum_notice_days in both OpenAPI specs, so it is machine-readable as well.

What counts as a breaking change

  • Removing an endpoint, a request parameter or a response field.
  • Changing the type or meaning of an existing response field.
  • Making a previously optional request parameter required.
  • Changing an HTTP status code or error code for an existing failure.

Adding a new endpoint, a new optional request parameter or a new response field is not breaking, and can happen inside a version without notice. Write clients that ignore unknown response fields.

Machine-readable sources