> ## 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. Version 2 is now the default for API requests.

<Tip>
  **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.
</Tip>

<Note>
  Review [what changed](#what-changed-in-version-2). The `X-Cerebras-Version-Patch: 2` header remains supported, but is no longer required to receive version 2 behavior.
</Note>

## 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:

<CodeGroup>
  ```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();
  ```
</CodeGroup>

***

## Version 2 Rollout Timeline

| Date                 | What Happens                                                                        |
| -------------------- | ----------------------------------------------------------------------------------- |
| **January 21, 2026** | Version 2 available for testing via header                                          |
| **July 22, 2026**    | Phased rollout of Version 2 as the default begins; older versions reach end-of-life |

***

## 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 validate your integration with version 2:

<Steps>
  <Step title="Test with the version header">
    Add `X-Cerebras-Version-Patch: 2` to your requests and run your test suite.

    ```python theme={null}
    extra_headers={"X-Cerebras-Version-Patch": "2"}
    ```
  </Step>

  <Step title="Update JSON schemas">
    * Add all properties to the `required` array
    * Add `additionalProperties: false` to all object definitions
    * Ensure enum values match their property types
  </Step>

  <Step title="Update reasoning parsing (if using reasoning models)">
    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
    ```
  </Step>

  <Step title="You're done">
    Once your tests pass, no further action is required. Version 2 is now the default, and the header is no longer needed.
  </Step>
</Steps>

***

## 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.