> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blackbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Reasoning

> Enable reasoning models to think before they respond using the Responses API

Reasoning models are LLMs trained with reinforcement learning to think before they answer, producing a long internal chain of thought before responding. They excel at complex problem solving, coding, scientific reasoning, and multi-step planning for agentic workflows.

<Tip>
  The Responses API is best supported on the **Enterprise plan**. Use `https://enterprise.blackbox.ai` as the base URL for full model availability and production reliability. The API is also available on standard plans at `https://api.blackbox.ai`, where it is currently experimental.
</Tip>

## Basic Reasoning Request

Pass a `reasoning` object with an `effort` field to control how much the model thinks before responding:

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const response = await fetch('https://enterprise.blackbox.ai/v1/responses', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.BLACKBOX_API_KEY}`,
    },
    body: JSON.stringify({
      model: 'blackboxai/openai/gpt-5.3-codex',
      reasoning: {
        effort: 'medium',
      },
      input: [
        {
          role: 'user',
          content:
            'Write a bash script that takes a matrix represented as a string with format [1,2],[3,4],[5,6] and prints the transpose in the same format.',
        },
      ],
    }),
  });

  const data = await response.json();
  const msg = data.output.find((item: any) => item.type === 'message');
  const text = msg?.content?.find((part: any) => part.type === 'output_text')?.text;
  console.log(text);
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import os
  import requests

  response = requests.post(
      'https://enterprise.blackbox.ai/v1/responses',
      headers={
          'Content-Type': 'application/json',
          'Authorization': f"Bearer {os.environ['BLACKBOX_API_KEY']}",
      },
      json={
          'model': 'blackboxai/openai/gpt-5.3-codex',
          'reasoning': {
              'effort': 'medium',
          },
          'input': [
              {
                  'role': 'user',
                  'content': 'Write a bash script that takes a matrix represented as a string with format [1,2],[3,4],[5,6] and prints the transpose in the same format.',
              }
          ],
      },
  )
  print(response.json())
  ```

  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl https://enterprise.blackbox.ai/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $BLACKBOX_API_KEY" \
    -d '{
      "model": "blackboxai/openai/gpt-5.3-codex",
      "reasoning": {
        "effort": "medium"
      },
      "input": [
        {
          "role": "user",
          "content": "Write a bash script that takes a matrix represented as a string with format [1,2],[3,4],[5,6] and prints the transpose in the same format."
        }
      ]
    }'
  ```
</CodeGroup>

## Reasoning Response

When reasoning is enabled, the `output` array includes a `reasoning` item with the model's internal thinking, followed by a `message` item with the visible response:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "id": "resp_QpQxYjZSgteaeH8SXShotw4n...",
  "object": "response",
  "model": "blackboxai/openai/gpt-5.3-codex",
  "status": "completed",
  "output": [
    {
      "id": "rs_1772502265541_jj0h02gs7k",
      "type": "reasoning",
      "summary": [],
      "content": [
        {
          "type": "reasoning_text",
          "text": "Calculating arithmetic\n\nI need to resolve a simple arithmetic problem: what's 15 times 27? The answer is 405."
        }
      ],
      "encrypted_content": "gAAAAABppjz3bJfZv5_WjuJI..."
    },
    {
      "id": "msg_abc456",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "15 × 27 = **405**.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 75,
    "output_tokens": 1186,
    "output_tokens_details": {
      "reasoning_tokens": 1024
    },
    "total_tokens": 1261
  }
}
```

<Note>
  The `encrypted_content` field contains an opaque token that can be passed back in multi-turn conversations so the model can reference its previous reasoning. Use `include: ["reasoning.encrypted_content"]` to receive it.
</Note>

## Reasoning with Tool Calling

When reasoning is combined with tool calling, the model thinks first (producing a `reasoning` item), then calls the tool (producing a `function_call` item):

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import os
  import requests

  response = requests.post(
      'https://enterprise.blackbox.ai/v1/responses',
      headers={
          'Content-Type': 'application/json',
          'Authorization': f"Bearer {os.environ['BLACKBOX_API_KEY']}",
      },
      json={
          'model': 'blackboxai/openai/gpt-5.3-codex',
          'reasoning': {'effort': 'medium'},
          'include': ['reasoning.encrypted_content'],
          'input': [
              {'role': 'user', 'content': "What's the weather in Paris?"}
          ],
          'tools': [{
              'type': 'function',
              'name': 'get_weather',
              'description': 'Get the current weather in a location',
              'parameters': {
                  'type': 'object',
                  'properties': {
                      'city': {'type': 'string', 'description': 'City name'}
                  },
                  'required': ['city']
              }
          }]
      },
  )
  data = response.json()

  for item in data['output']:
      if item['type'] == 'reasoning':
          print(f"[Reasoning] {item.get('content', [{}])[0].get('text', '')[:100]}...")
      elif item['type'] == 'function_call':
          print(f"[Tool] {item['name']}({item['arguments']})")
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const response = await fetch('https://enterprise.blackbox.ai/v1/responses', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.BLACKBOX_API_KEY}`,
    },
    body: JSON.stringify({
      model: 'blackboxai/openai/gpt-5.3-codex',
      reasoning: { effort: 'medium' },
      include: ['reasoning.encrypted_content'],
      input: [
        { role: 'user', content: "What's the weather in Paris?" }
      ],
      tools: [{
        type: 'function',
        name: 'get_weather',
        description: 'Get the current weather in a location',
        parameters: {
          type: 'object',
          properties: { city: { type: 'string' } },
          required: ['city']
        }
      }]
    })
  });

  const data = await response.json();
  for (const item of data.output) {
    if (item.type === 'reasoning') console.log('[Reasoning]', item.content?.[0]?.text?.slice(0, 100));
    if (item.type === 'function_call') console.log(`[Tool] ${item.name}(${item.arguments})`);
  }
  ```

  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl https://enterprise.blackbox.ai/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $BLACKBOX_API_KEY" \
    -d '{
      "model": "blackboxai/openai/gpt-5.3-codex",
      "reasoning": {"effort": "medium"},
      "include": ["reasoning.encrypted_content"],
      "input": [
        {"role": "user", "content": "What is the weather in Paris?"}
      ],
      "tools": [{
        "type": "function",
        "name": "get_weather",
        "description": "Get the current weather in a location",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }]
    }'
  ```
</CodeGroup>

```json Response — Reasoning + Tool Call theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "id": "resp_WKnCTWadviYHbIbazz8YU1C1...",
  "object": "response",
  "model": "blackboxai/openai/gpt-5.3-codex",
  "status": "completed",
  "output": [
    {
      "id": "rs_1772502274510_1t9dmjqoee5j",
      "type": "reasoning",
      "summary": [],
      "content": [
        {
          "type": "reasoning_text",
          "text": "I need to use the weather tool to get the weather for Paris."
        }
      ],
      "encrypted_content": "gAAAAABppj0BM4w_s3F9t4kb..."
    },
    {
      "id": "fc_1772502274510_g7twdw0wz7v",
      "type": "function_call",
      "name": "get_weather",
      "arguments": "{\"city\":\"Paris\"}",
      "call_id": "call_7imH3aTWGafLCivAHxauCCrV",
      "status": "completed"
    }
  ],
  "usage": {
    "input_tokens": 591,
    "output_tokens": 120,
    "output_tokens_details": { "reasoning_tokens": 64 },
    "total_tokens": 711
  }
}
```

## Multi-Turn with Reasoning

After executing the tool, pass back the reasoning item, function call, and tool result in the `input` array. The model uses its previous reasoning context to generate the final answer:

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import os
  import requests
  import json

  url = 'https://enterprise.blackbox.ai/v1/responses'
  headers = {
      'Content-Type': 'application/json',
      'Authorization': f"Bearer {os.environ['BLACKBOX_API_KEY']}",
  }

  tools = [{
      'type': 'function',
      'name': 'calculator',
      'description': 'Perform a calculation',
      'parameters': {
          'type': 'object',
          'properties': {'expression': {'type': 'string'}},
          'required': ['expression']
      }
  }]

  # Turn 1: Model reasons and calls the tool
  r1 = requests.post(url, headers=headers, json={
      'model': 'blackboxai/openai/gpt-5.3-codex',
      'reasoning': {'effort': 'medium'},
      'include': ['reasoning.encrypted_content'],
      'input': [{'role': 'user', 'content': 'What is 15 + 27? Use the calculator.'}],
      'tools': tools
  }).json()

  # Build input for Turn 2: include all output items + tool result
  input_turn2 = [{'role': 'user', 'content': 'What is 15 + 27? Use the calculator.'}]
  for item in r1['output']:
      input_turn2.append(item)
      if item['type'] == 'function_call':
          input_turn2.append({
              'type': 'function_call_output',
              'call_id': item['call_id'],
              'output': '42'
          })

  # Turn 2: Model uses reasoning context + tool result for final answer
  r2 = requests.post(url, headers=headers, json={
      'model': 'blackboxai/openai/gpt-5.3-codex',
      'reasoning': {'effort': 'medium'},
      'input': input_turn2,
      'tools': tools
  }).json()

  msg = next(item for item in r2.get('output', []) if item.get('type') == 'message')
  text = next(part['text'] for part in msg['content'] if part['type'] == 'output_text')
  print(text)  # "15 + 27 = 42"
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const url = 'https://enterprise.blackbox.ai/v1/responses';
  const headers = {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.BLACKBOX_API_KEY}`,
  };

  const tools = [{
    type: 'function',
    name: 'calculator',
    description: 'Perform a calculation',
    parameters: {
      type: 'object',
      properties: { expression: { type: 'string' } },
      required: ['expression']
    }
  }];

  // Turn 1
  const r1 = await fetch(url, {
    method: 'POST', headers,
    body: JSON.stringify({
      model: 'blackboxai/openai/gpt-5.3-codex',
      reasoning: { effort: 'medium' },
      include: ['reasoning.encrypted_content'],
      input: [{ role: 'user', content: 'What is 15 + 27? Use the calculator.' }],
      tools
    })
  }).then(r => r.json());

  // Build Turn 2 input
  const input: any[] = [{ role: 'user', content: 'What is 15 + 27? Use the calculator.' }];
  for (const item of r1.output) {
    input.push(item);
    if (item.type === 'function_call') {
      input.push({ type: 'function_call_output', call_id: item.call_id, output: '42' });
    }
  }

  // Turn 2
  const r2 = await fetch(url, {
    method: 'POST', headers,
    body: JSON.stringify({
      model: 'blackboxai/openai/gpt-5.3-codex',
      reasoning: { effort: 'medium' },
      input, tools
    })
  }).then(r => r.json());

  const r2Msg = r2.output.find((item: any) => item.type === 'message');
  const r2Text = r2Msg?.content?.find((part: any) => part.type === 'output_text')?.text;
  console.log(r2Text); // "15 + 27 = 42"
  ```
</CodeGroup>

```json Turn 2 Response — Final Answer theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "id": "resp_AaQmI9orpLppdWHhpAkPGu5o...",
  "object": "response",
  "model": "blackboxai/openai/gpt-5.3-codex",
  "status": "completed",
  "output": [
    {
      "id": "msg_1772502284627_3tpxqy1rums",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "15 + 27 = **42**.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 85,
    "output_tokens": 13,
    "output_tokens_details": { "reasoning_tokens": 0 },
    "total_tokens": 98
  }
}
```

***

## Effort Levels

The `reasoning.effort` parameter guides how many reasoning tokens the model generates before responding. The default is `medium`.

| Value      | Description                                                                    |
| ---------- | ------------------------------------------------------------------------------ |
| `"low"`    | Favors speed and economical token usage                                        |
| `"medium"` | Balanced between speed and reasoning accuracy (default)                        |
| `"high"`   | Favors more complete reasoning for complex tasks                               |
| `"xhigh"`  | Maximum reasoning depth — allocates the largest portion of tokens for thinking |

## Reasoning Summaries

The `reasoning.summary` field is part of the OpenAI Responses API spec and is accepted by the API. Support varies by model — when supported, setting it causes the `output` array to include a `reasoning` item before the `message` item containing a human-readable summary of the model's internal thinking.

| Value        | Description                                               |
| ------------ | --------------------------------------------------------- |
| `"auto"`     | Uses the most detailed summarizer available (recommended) |
| `"detailed"` | Full step-by-step reasoning summary                       |
| `"concise"`  | A shorter, high-level summary of the reasoning process    |

<Note>
  `reasoning.summary` is not currently supported by `blackboxai/openai/gpt-5.3-codex`. When unsupported, the field is accepted but ignored — the response returns only the `message` output item.
</Note>

When a model supports `reasoning.summary`, the `output` array contains a reasoning item before the message:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
[
  {
    "id": "rs_abc123",
    "type": "reasoning",
    "summary": [
      {
        "type": "summary_text",
        "text": "**Answering a simple question**\n\nThe capital of France is Paris — a well-known fact. I'll keep the answer brief and direct."
      }
    ]
  },
  {
    "id": "msg_abc456",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "The capital of France is Paris.",
        "annotations": []
      }
    ]
  }
]
```

## Token Usage

Reasoning tokens are generated internally and are not visible in the response, but they are billed as output tokens and appear in `usage.output_tokens_details`:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "usage": {
    "input_tokens": 75,
    "output_tokens": 1186,
    "output_tokens_details": {
      "reasoning_tokens": 1024
    },
    "total_tokens": 1261
  }
}
```

<Warning>
  Reasoning tokens occupy space in the model's context window and are billed as output tokens even though they are not returned in the response.
</Warning>

## Handling Incomplete Responses

If the model runs out of token budget while reasoning, it may return `status: incomplete` — or in some cases return `status: completed` with an empty `output_text` when all tokens were consumed by internal reasoning. Reserve enough tokens for both reasoning and the visible output to avoid this.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const response = await fetch('https://enterprise.blackbox.ai/v1/responses', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.BLACKBOX_API_KEY}`,
    },
    body: JSON.stringify({
      model: 'blackboxai/openai/gpt-5.3-codex',
      reasoning: { effort: 'medium' },
      max_output_tokens: 300,
      input: [
        {
          role: 'user',
          content: 'Write a bash script that transposes a matrix.',
        },
      ],
    }),
  });

  const data = await response.json();
  if (data.status === 'incomplete' && data.incomplete_details?.reason === 'max_output_tokens') {
    console.log('Ran out of tokens');
    const msg = data.output?.find((item: any) => item.type === 'message');
    const text = msg?.content?.find((part: any) => part.type === 'output_text')?.text;
    if (text) {
      console.log('Partial output:', text);
    } else {
      console.log('Ran out of tokens during reasoning — no visible output produced');
    }
  }
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import os
  import requests

  response = requests.post(
      'https://enterprise.blackbox.ai/v1/responses',
      headers={
          'Content-Type': 'application/json',
          'Authorization': f"Bearer {os.environ['BLACKBOX_API_KEY']}",
      },
      json={
          'model': 'blackboxai/openai/gpt-5.3-codex',
          'reasoning': {'effort': 'medium'},
          'max_output_tokens': 300,
          'input': [
              {
                  'role': 'user',
                  'content': 'Write a bash script that transposes a matrix.',
              }
          ],
      },
  )

  data = response.json()
  if data.get('status') == 'incomplete' and data.get('incomplete_details', {}).get('reason') == 'max_output_tokens':
      print('Ran out of tokens')
      msg = next((item for item in data.get('output', []) if item.get('type') == 'message'), None)
      text = next((part['text'] for part in (msg or {}).get('content', []) if part.get('type') == 'output_text'), None)
      if text:
          print('Partial output:', text)
      else:
          print('Ran out of tokens during reasoning — no visible output produced')
  ```
</CodeGroup>

## Request Parameters

<ParamField body="reasoning" type="object">
  Configures reasoning behavior for the model.

  <Expandable title="reasoning fields">
    <ParamField body="effort" type="string">
      Controls how many reasoning tokens the model uses. One of `"low"`, `"medium"` (default), `"high"`, or `"xhigh"`.
    </ParamField>

    <ParamField body="summary" type="string">
      When set, returns a human-readable reasoning summary alongside the response. One of `"auto"`, `"detailed"`, or `"concise"`. Not included unless explicitly set.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="max_output_tokens" type="integer">
  Maximum number of tokens to generate in the response, including reasoning tokens. Increase this when using higher effort levels to avoid incomplete responses.
</ParamField>

## Next Steps

<CardGroup cols={3}>
  <Card title="Text Generation" icon="text" href="/api-reference/responses/text-generation">
    Learn the basics of the Responses API
  </Card>

  <Card title="Tool Calling" icon="wrench" href="/api-reference/responses/tool-calling">
    Combine reasoning with tool calls for complex agentic workflows
  </Card>

  <Card title="Best Practices" icon="shield-check" href="/api-reference/best-practices#preserving-reasoning-blocks-in-multi-turn-requests">
    Preserve reasoning signatures across turns and avoid common errors
  </Card>
</CardGroup>