Versions

Cerebras uses API versioning to manage breaking changes to request validation and response formats. Version 2 is now the default for API requests.

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. The X-Cerebras-Version-Patch: 2 header remains supported, but is no longer required to receive version 2 behavior.

Z.ai GLM 4.7 is scheduled for deprecation on August 17, 2026. It will retain its existing default logprobs response behavior and will not receive the separate reasoning_logprobs default before then. Requests that explicitly include X-Cerebras-Version-Patch: 2 can receive the separated reasoning_logprobs behavior. This affects only the placement of reasoning-token logprobs. See the GLM 4.7 deprecation notice.

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:

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!"}]
  }'

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"}
)

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"}
)

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 22, 2026	Phased rollout of Version 2 as the default begins; older versions reach end-of-life

Version 2 is now the default. Z.ai GLM 4.7 is scheduled for deprecation on August 17, 2026. It will retain its existing default logprobs response behavior and will not receive the separate reasoning_logprobs default before then. Requests that explicitly include X-Cerebras-Version-Patch: 2 can receive the separated reasoning_logprobs behavior. This affects only the placement of reasoning-token logprobs. See the GLM 4.7 deprecation notice.

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:

// ❌ Fails: missing additionalProperties
{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" }
      },
      "required": ["name"]
    }
  },
  "required": ["user"]
}

// ✅ 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 for details on reasoning format options.

// 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},
      ...
    ]
  }
}

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

Test with the version header

Add X-Cerebras-Version-Patch: 2 to your requests and run your test suite.

extra_headers={"X-Cerebras-Version-Patch": "2"}

Update JSON schemas

Add all properties to the required array
Add additionalProperties: false to all object definitions
Ensure enum values match their property types

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.

# 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

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.

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.

Introduction

Chat

Completions

Models

Batch

Files

Metrics

Management

What’s Guaranteed

Setting the API Version

Version 2 Rollout Timeline

What Changed in Version 2

Structured Outputs: Stricter Schema Validation

Tool Calling: Stricter Message Validation

Reasoning Logprobs Added

Unicode Handling Fix

Migration Checklist

Future Versions

​What’s Guaranteed

​Setting the API Version

​Version 2 Rollout Timeline

​What Changed in Version 2

​Structured Outputs: Stricter Schema Validation

​Tool Calling: Stricter Message Validation

​Reasoning Logprobs Added

​Unicode Handling Fix

​Migration Checklist

​Future Versions

What’s Guaranteed

Setting the API Version

Version 2 Rollout Timeline

What Changed in Version 2

Structured Outputs: Stricter Schema Validation

Tool Calling: Stricter Message Validation

Reasoning Logprobs Added

Unicode Handling Fix

Migration Checklist

Future Versions