> ## Documentation Index
> Fetch the complete documentation index at: https://inference-docs.cerebras.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Versions
> Understand how Cerebras uses versioning to manage breaking changes.
Cerebras uses API versioning to manage breaking changes to request validation and response formats. The latest version is available for testing via the `X-Cerebras-Version-Patch` header and becomes the default on July 21, 2026.
**This versioning does not change the API interface.** You'll continue using the same endpoints (e.g., `/v1/chat/completions`) and the same SDKs. New versions only affect validation rules and response field behavior. No new endpoints or SDK updates required.
Review [what changed](#what-changed-in-version-2), then set `X-Cerebras-Version-Patch: 2` to test your integration before the July 21, 2026 cutover.
## What's Guaranteed
Within a given API version, we guarantee:
* Existing request parameters continue to work as documented
* Existing response fields remain present with the same types
Non-breaking changes that may occur:
* New optional request parameters may be added
* New fields may be added to responses
* Error message text may change (but not error types within a version)
Breaking changes only happen in new API versions, giving you time to test and migrate. This includes stricter validation, removed parameters, or changed defaults.
***
## Setting the API Version
Override the default API version per-request by passing the `X-Cerebras-Version-Patch` header:
```bash cURL theme={null}
curl https://api.cerebras.ai/v1/chat/completions \
-H "Authorization: Bearer $CEREBRAS_API_KEY" \
-H "X-Cerebras-Version-Patch: 2" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-oss-120b",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```python OpenAI SDK theme={null}
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.cerebras.ai/v1",
api_key=os.environ.get("CEREBRAS_API_KEY")
)
completion = client.chat.completions.create(
model="gpt-oss-120b",
messages=[{"role": "user", "content": "Hello!"}],
extra_headers={"X-Cerebras-Version-Patch": "2"}
)
```
```python Cerebras SDK (Python) theme={null}
import os
from cerebras.cloud.sdk import Cerebras
client = Cerebras(
api_key=os.environ.get("CEREBRAS_API_KEY")
)
completion = client.chat.completions.create(
model="gpt-oss-120b",
messages=[{"role": "user", "content": "Hello!"}],
extra_headers={"X-Cerebras-Version-Patch": "2"}
)
```
```javascript Cerebras SDK (Node.js) theme={null}
import Cerebras from '@cerebras/cerebras_cloud_sdk';
const client = new Cerebras({
apiKey: process.env['CEREBRAS_API_KEY'],
});
async function main() {
const completion = await client.chat.completions.create(
{
model: 'gpt-oss-120b',
messages: [{ role: 'user', content: 'Hello!' }],
},
{
headers: { 'X-Cerebras-Version-Patch': '2' },
}
);
console.log(completion);
}
main();
```
***
## Version 2 Rollout Timeline
| Date | What Happens |
| -------------------- | --------------------------------------------------------- |
| **January 21, 2026** | Version 2 available for testing via header |
| **July 21, 2026** | Version 2 becomes the default; older versions end-of-life |
After July 21, 2026, all requests will use version 2.
***
## What Changed in Version 2
Version 2 introduces stricter validation for structured outputs and tool calling, refines reasoning model behavior, and fixes edge cases. If your application uses JSON schemas, tool calls, or reasoning models, review these changes carefully.
### Structured Outputs: Stricter Schema Validation
When using `strict: true`, Version 2 requires explicit, strictly-typed schemas. `additionalProperties: false` is required at every level of nested objects:
```json theme={null}
// ❌ Fails: missing additionalProperties
{
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"name": { "type": "string" }
},
"required": ["name"]
}
},
"required": ["user"]
}
```
```json theme={null}
// ✅ Works: additionalProperties at all levels
{
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"name": { "type": "string" }
},
"required": ["name"],
"additionalProperties": false
}
},
"required": ["user"],
"additionalProperties": false
}
```
### Tool Calling: Stricter Message Validation
Version 2 validates the structure of multi-turn conversations involving tool calls:
| Validation | What it checks |
| -------------------------- | --------------------------------------------------------------------------------------------------------- |
| Tool response completeness | Every `tool_call_id` in an assistant message must have a corresponding tool message immediately following |
| Orphan tool messages | Tool messages cannot reference a `tool_call_id` that doesn't exist in a prior assistant message |
| Tool choice consistency | `tool_choice` cannot be set unless `tools` is also provided |
| Unique tool call IDs | Duplicate `tool_call.id` values in the same request are rejected |
### Reasoning Logprobs Added
For reasoning models, version 2 adds a separate `reasoning_logprobs` field that contains logprobs for the reasoning tokens. Previously, reasoning logprobs were included in the main `logprobs` field alongside content logprobs.
See [Reasoning](/capabilities/reasoning) for details on reasoning format options.
```json theme={null}
// Before: reasoning logprobs included in main logprobs field
{
"message": {
"content": "Here is the answer...",
"reasoning": "Let me think..."
},
"logprobs": {
"content": [
{"token": "Let ", "logprob": -0.3},
{"token": "me", "logprob": -0.4},
...
{"token": "Here", "logprob": -0.1},
{"token": " is", "logprob": -0.2},
...
]
}
}
```
```json theme={null}
// After (version 2): reasoning logprobs are separated
{
"message": {
"content": "Here is the answer...",
"reasoning": "Let me think..."
},
"logprobs": {
"content": [
{"token": "Here", "logprob": -0.1},
{"token": " is", "logprob": -0.2},
...
]
},
"reasoning_logprobs": {
"content": [
{"token": "Let ", "logprob": -0.3},
{"token": "me", "logprob": -0.4},
...
]
}
}
```
### Unicode Handling Fix
Logprobs now reflect partial Unicode tokens as they appear in the model's vocabulary. Previously, the Unicode replacement character (`\uFFFD`) was not handled correctly in logprobs output. This fix is backward-compatible and requires no code changes.
***
## Migration Checklist
Use this checklist to prepare for version 2:
Add `X-Cerebras-Version-Patch: 2` to your requests and run your test suite.
```python theme={null}
extra_headers={"X-Cerebras-Version-Patch": "2"}
```
* Add all properties to the `required` array
* Add `additionalProperties: false` to all object definitions
* Ensure enum values match their property types
If you parse reasoning content, update your code to read from the `reasoning` field in the response instead of extracting it from `content`.
```python theme={null}
# Before
reasoning = extract_reasoning_from_content(response.choices[0].message.content)
# After (version 2)
reasoning = response.choices[0].message.reasoning
content = response.choices[0].message.content
```
Once your tests pass, no further action is required. On July 21, 2026, version 2 takes effect and the header is no longer needed.
***
## Future Versions
We strive to maintain backward compatibility whenever possible. In rare cases where breaking changes are necessary, a new API version will be released and made available for testing via the `X-Cerebras-Version-Patch` header for a minimum of 6 months before taking effect. Cerebras Cloud users will be notified via email before each version transition.