Skip to main content
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, 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: 
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!"}]
  }'

​
Version 2 Rollout Timeline

DateWhat Happens
January 21, 2026Version 2 available for testing via header
July 21, 2026Version 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: 
// ❌ 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:
ValidationWhat it checks
Tool response completenessEvery tool_call_id in an assistant message must have a corresponding tool message immediately following
Orphan tool messagesTool messages cannot reference a tool_call_id that doesn’t exist in a prior assistant message
Tool choice consistencytool_choice cannot be set unless tools is also provided
Unique tool call IDsDuplicate 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 prepare for version 2:
1

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

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
4

You're done

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.