Versioning & deprecations

This page tells you what stays stable when the API evolves, and what to build so that your integration keeps working as it does. The API is in developer preview.

What is true today

One version, in the path. Every endpoint lives under /v1. There is no version header to send, and no dated versions to pin.
OpenAI formats are followed, not forked. Chat Completions, Responses, Embeddings, the model list and the error shape follow OpenAI’s wire formats, so the official SDKs work unchanged. When those formats grow, Belarel follows them under /v1.
Belarel additions are additive. What Belarel adds to an OpenAI-shaped answer lives in one extra belarel object and in response headers (X-Request-Id, X-RateLimit-*-Requests). SDKs ignore fields they do not know, so these additions never break an OpenAI client.
Belarel-only endpoints (/v1/key, /v1/keys, /v1/usage, /v1/requests/{id}, /v1/credits) are versioned with the rest of /v1.
Every change is recorded in the changelog.

Changes that can ship at any time

These changes are backward compatible. They can ship under /v1 without a new version and without advance notice:

New endpoints.
New optional request parameters.
New fields in responses, in the belarel block, in model entries, and in stream events.
New error codes, new policy rule names in belarel.policy.decisions, and new values in other string enumerations.
New webhook event types.
New models in your catalog, and new response headers.

Build for them:

Breaking changes

A breaking change is one that can make a correct integration fail: removing or renaming an endpoint or field, changing a field’s type or meaning, making an optional parameter required, or changing the HTTP status of an existing error.

Breaking changes are not made silently to /v1. When one is needed:

It is announced in the changelog, marked Deprecation, with the date it takes effect and what to do instead.
The old behavior keeps working for a notice period: at least 30 days during the developer preview, and at least 90 days once the API is generally available.
Where the change cannot coexist with /v1, it ships under a new path version (/v2), and /v1 keeps working for the notice period.

Security fixes are the exception: a change needed to close a vulnerability can take effect immediately, and is recorded in the changelog afterward.

Models come and go

Models are not part of the API version. Your catalog changes when the platform adds or retires a model, when a provider retires one, and when your organization or contract changes what you may call. A model that leaves your catalog answers 404 model_not_found.

Read GET /v1/models instead of hardcoding a list.
Send explicit model ids and keep them in configuration, so replacing one is not a code change.
Watch for 404 model_not_found in your logs.