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

Version 2 requires explicit, strictly-typed schemas. The following patterns will return errors:
Schemas must use $defs for reusable definitions. The definitions keyword is not supported.
Fields omitted from required may be absent from the response instead of returning null. Update your code to handle missing fields rather than expecting null values.
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["age"],
  "additionalProperties": false
}

# Before: optional fields returned as null
name = response.name  # None

# After (version 2): optional fields may be absent
name = getattr(response, 'name', None)  # or use .get() for dicts

​
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 Format Default Changed

For reasoning models, the default reasoning_format is now parsed, which returns reasoning in a separate reasoning field and logprobs in a separate reasoning_logprobs field. If your application parses reasoning from the content field, you’ll need to update it to read from the reasoning field instead, or explicitly set reasoning_format: "raw" to preserve the previous behavior. See Reasoning for details on reasoning format options. 
// Before: reasoning included inline with content
{
  "message": {
    "content": "<think>Let me think...</think>Here is the answer..."
  },
  "logprobs": {
    "content": [
      {"token": "Let ", "logprob": -0.3},
      {"token": "me", "logprob": -0.4},
      ...
      {"token": "Here", "logprob": -0.1},
      ...
    ]
  }
}

// After (version 2): reasoning, content, and logprobs are all separated
{
  "message": {
    "content": "Here is the answer...",
    "reasoning": "Let me think..."
  },
  "logprobs": {
    "content": [
      {"token": "Here", "logprob": -0.1},
      ...
    ]
  },
  "reasoning_logprobs": {
    "content": [
      {"token": "Let ", "logprob": -0.3},
      {"token": "me", "logprob": -0.4},
      ...
    ]
  }
}

​
Unicode Handling Fix

Logprobs now correctly handle the Unicode replacement character (\uFFFD). Previously, requests returning this character could show a mismatch between logprobs tokens and the actual content. 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.