Versioning

The API version is the first path segment: /v1. Government integrations live for years and rarely upgrade, so the rules below bias hard toward not breaking existing callers. Integrations built against /v1 keep working.

The stability commitment

Within /v1, these are stable and will not change in a breaking way:

• Existing request fields and the values they accept.
• Existing response fields, their types, and their meaning.
• HTTP status codes and the shape of the error envelope, {"error": {"message", "type", "param", "code"}}.
• Documented endpoint paths and methods.
• The scopes an operation requires (Authentication).

A new major version (/v2) is introduced only for a breaking change that cannot be made additively. /v1 and /v2 would then run side by side, with a documented migration path; a major version is never removed without the deprecation process below.

Additive changes

Additive changes are not breaking and can ship at any time:

• New endpoints.
• New optional request fields.
• New response fields. The citations field on assistant messages is an example: an OpenAI-shaped response with one more field.
• New values in fields documented as open sets (below).
• New error codes in the registry.

The guides and the OpenAPI specification are updated in the same change, so diffing the spec shows exactly what was added.

Examples

Change	Classification
A new source_type value on documents	Additive (open set); treat unknown values as "other"
A new optional stream_options field	Additive
A new code in the error registry	Additive; fall back on the status class
A larger body cap or a higher default limit	Additive
Removing a response field or changing its type	Breaking; only with the deprecation process, or in /v2
Making an optional request field required	Breaking; same
Changing the status code of a documented error	Breaking; same
Requiring a new scope for an existing operation	Breaking; same
Repointing an alias at a different bot	Not an API change; a configuration change you request for your account

What this asks of your integration

Additive evolution only works if clients are tolerant readers:

• Ignore unknown response fields. The official OpenAI SDKs already do; a hand-written client must not fail on a field it has not seen. See unknown fields.
• Branch on known codes, default on the status class. An unrecognized error code should fall back on the handling for its HTTP status (Errors).
• Do not enumerate open sets exhaustively. Error codes, job status values, document status values, finish_reason values, and the object strings may grow. Treat a value you do not recognize as "other", not as a failure.
• Key on code and param, never on message text. Messages are for people and may be reworded.

Beta surfaces

An endpoint or field marked beta in these guides or in the reference may change or be removed with shorter notice than the deprecation process requires. Anything not marked beta is stable. No /v1 surface is marked beta today.

Deprecation process

When something stable must be retired:

1. Announcement. The deprecation is announced with a removal date, and the affected endpoints start returning the Deprecation and Sunset response headers (RFC 9745 and RFC 8594). Sunset carries the date after which the behavior may stop working.
2. Minimum 12 months between the announcement and removal for anything in /v1.
3. Unchanged during the window. The deprecated behavior keeps working exactly as before until the sunset date.
4. Direct notification. Affected agencies are told through their account contact, in addition to the public announcement, because integrators may never read release notes.

Nothing in /v1 is deprecated today, and no response carries these headers. Build the check in anyway: log any response that carries a Deprecation header, and you will learn about a retirement the day it is announced rather than the day it takes effect.

response = client.chat.completions.with_raw_response.create(
    model="default",
    messages=[{"role": "user", "content": "When is jury duty orientation?"}],
)
if "deprecation" in response.headers:
    log.warning("Deprecated API surface in use; sunset %s", response.headers.get("sunset"))
completion = response.parse()

Model ids

Model ids (bot slugs and aliases) follow the same lifecycle. The underlying language model behind a bot can be upgraded by eCourtDate without changing the id you call, and such an upgrade is not a breaking change to the API contract. If a bot or alias is to be retired, you are notified with advance notice through your account contact, and calls to the retired id then return 404 model_not_found with the message listing the ids that remain. Aliases exist for exactly this purpose: keep calling a stable alias and let eCourtDate repoint it. See Models.

OpenAI compatibility

"OpenAI-compatible" means the official OpenAI SDKs work against this API unmodified when pointed at the base URL. The guarantee is verified against the official OpenAI Python SDK on every change. It covers the shape of the /v1/chat/completions, /v1/models, and /v1/embeddings requests and responses and the error envelope; it does not mean every OpenAI parameter has an effect. Chat completions lists which parameters are supported, which are accepted and ignored, and which are rejected; SDKs covers client configuration.

Spec-first

The OpenAPI specification (also published as YAML) is the contract this API is built against. The interactive reference and these guides are checked against it. Pin your client generation to the spec version you tested, and diff the spec on upgrade to see exactly what was added. The spec describes only the public /v1 surface and GET /health.