> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Soju06/codex-lb/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex Responses

> Create AI responses using the Codex-LB proxy endpoints

## Overview

The Codex responses endpoints provide access to AI models through Codex-LB's load balancing and account pooling infrastructure. These endpoints support both streaming and compact (non-streaming) response formats.

## Endpoints

### POST /backend-api/codex/responses

Creates a streaming AI response using Server-Sent Events (SSE).

**Base URL:** `https://your-codex-lb-instance.com`

#### Request Body

<ParamField body="model" type="string" required>
  The model ID to use for the request (e.g., `gpt-5.1`, `gpt-4o`)
</ParamField>

<ParamField body="instructions" type="string" required>
  System-level instructions or prompt for the model
</ParamField>

<ParamField body="input" type="string | array" required>
  User input as a string or array of message objects
</ParamField>

<ParamField body="tools" type="array" default="[]">
  Array of tool definitions for function calling
</ParamField>

<ParamField body="tool_choice" type="string | object">
  Controls which tool the model should use (`auto`, `none`, or specific tool)
</ParamField>

<ParamField body="parallel_tool_calls" type="boolean">
  Whether to enable parallel tool calls
</ParamField>

<ParamField body="reasoning" type="object">
  Reasoning configuration with `effort` and `summary` options

  <Expandable title="properties">
    <ParamField body="effort" type="string">
      Reasoning effort level (e.g., `low`, `medium`, `high`)
    </ParamField>

    <ParamField body="summary" type="string">
      Request a reasoning summary format
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="text" type="object">
  Text output controls

  <Expandable title="properties">
    <ParamField body="verbosity" type="string">
      Controls output verbosity level
    </ParamField>

    <ParamField body="format" type="object">
      Structured output format specification
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="stream" type="boolean" default="true">
  Whether to stream the response
</ParamField>

<ParamField body="include" type="array" default="[]">
  Additional fields to include in the response. Allowed values:

  * `code_interpreter_call.outputs`
  * `computer_call_output.output.image_url`
  * `file_search_call.results`
  * `message.input_image.image_url`
  * `message.output_text.logprobs`
  * `reasoning.encrypted_content`
  * `web_search_call.action.sources`
</ParamField>

<ParamField body="conversation" type="string">
  Conversation ID for multi-turn conversations
</ParamField>

<ParamField body="prompt_cache_key" type="string">
  Optional cache key for prompt caching
</ParamField>

#### Response

Returns a Server-Sent Events (SSE) stream with events:

```json theme={null}
data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"in_progress"}}

data: {"type":"response.output_item.added","item":{"type":"message","status":"in_progress"}}

data: {"type":"response.output_item.done","item":{"type":"message","status":"completed","content":[{"type":"output_text","text":"Hello! How can I help you?"}]}}

data: {"type":"response.completed","response":{"id":"resp_abc123","status":"completed","usage":{"input_tokens":10,"output_tokens":8,"total_tokens":18}}}
```

#### Example Request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://your-codex-lb-instance.com/backend-api/codex/responses \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-5.1",
      "instructions": "You are a helpful assistant.",
      "input": "What is the capital of France?",
      "stream": true,
      "reasoning": {
        "effort": "medium"
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://your-codex-lb-instance.com/backend-api/codex/responses"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "model": "gpt-5.1",
      "instructions": "You are a helpful assistant.",
      "input": "What is the capital of France?",
      "stream": True,
      "reasoning": {
          "effort": "medium"
      }
  }

  response = requests.post(url, json=data, headers=headers, stream=True)
  for line in response.iter_lines():
      if line:
          print(line.decode('utf-8'))
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://your-codex-lb-instance.com/backend-api/codex/responses', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gpt-5.1',
      instructions: 'You are a helpful assistant.',
      input: 'What is the capital of France?',
      stream: true,
      reasoning: {
        effort: 'medium'
      }
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    console.log(decoder.decode(value));
  }
  ```
</CodeGroup>

***

### POST /backend-api/codex/responses/compact

Creates a non-streaming AI response that returns a complete response object.

**Base URL:** `https://your-codex-lb-instance.com`

#### Request Body

<ParamField body="model" type="string" required>
  The model ID to use for the request
</ParamField>

<ParamField body="instructions" type="string" required>
  System-level instructions for the model
</ParamField>

<ParamField body="input" type="string | array" required>
  User input as a string or array of message objects
</ParamField>

#### Response

Returns a complete response object:

```json theme={null}
{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "Paris is the capital of France."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 8,
    "total_tokens": 20
  }
}
```

#### Example Request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://your-codex-lb-instance.com/backend-api/codex/responses/compact \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-5.1",
      "instructions": "You are a helpful assistant.",
      "input": "What is the capital of France?"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://your-codex-lb-instance.com/backend-api/codex/responses/compact"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "model": "gpt-5.1",
      "instructions": "You are a helpful assistant.",
      "input": "What is the capital of France?"
  }

  response = requests.post(url, json=data, headers=headers)
  result = response.json()
  print(result)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://your-codex-lb-instance.com/backend-api/codex/responses/compact', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gpt-5.1',
      instructions: 'You are a helpful assistant.',
      input: 'What is the capital of France?'
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</CodeGroup>

## Reasoning Effort Parameter

The `reasoning.effort` parameter controls the depth of reasoning for models that support it:

* `low` - Fast, minimal reasoning
* `medium` - Balanced reasoning and speed (default)
* `high` - Maximum reasoning depth

Available reasoning levels vary by model. Check the [models endpoint](/api/codex-models) to see supported reasoning levels for each model.

## Error Handling

<ResponseField name="error" type="object">
  Error object returned when the request fails

  <Expandable title="properties">
    <ResponseField name="message" type="string">
      Human-readable error message
    </ResponseField>

    <ResponseField name="type" type="string">
      Error type (e.g., `invalid_request_error`, `server_error`)
    </ResponseField>

    <ResponseField name="code" type="string">
      Error code (e.g., `no_accounts`, `rate_limit_exceeded`, `model_not_found`)
    </ResponseField>

    <ResponseField name="param" type="string">
      Parameter that caused the error (if applicable)
    </ResponseField>
  </Expandable>
</ResponseField>

### Common Error Codes

* `no_accounts` - No available accounts in the pool
* `rate_limit_exceeded` - Rate limit reached for your API key
* `model_not_found` - Requested model is not available
* `invalid_request_error` - Invalid request parameters
* `upstream_error` - Error from upstream AI provider

## Notes

* The `/backend-api/codex/responses` endpoint always returns streaming responses
* Use `/backend-api/codex/responses/compact` for simple, non-streaming responses
* Both endpoints support the same authentication mechanism
* Streaming responses use the Server-Sent Events (SSE) protocol
* The `store` parameter is not supported and must be `false`
* The `previous_response_id` parameter is not supported
* Unsupported tool types: `file_search`, `code_interpreter`, `computer_use`, `image_generation`