> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.caesar.xyz/2025-11-27/documentation/integration/open-ai-compatibility/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.caesar.xyz/_mcp/server.

# OpenAI Compatibility

Caesar provides OpenAI-compatible endpoints that let you use existing OpenAI client libraries to access Caesar's research API. With minimal code changes, you can integrate Caesar into applications already using the OpenAI SDK.

> **Tip**
>
> This compatibility layer is useful for quick integration and testing. For full access to Caesar's features, we recommend using the native [Research API](/api-reference/research/create-research).

## Getting started

To use Caesar with the OpenAI SDK:

1. Point the base URL to `https://api.caesar.xyz/compat`
2. Use your Caesar API key
3. Use `caesar-research` as the model name

#### Python

```python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CAESAR_API_KEY",
    base_url="https://api.caesar.xyz/compat"
)

response = client.chat.completions.create(
    model="caesar-research",
    messages=[
        {"role": "user", "content": "What are the latest developments in quantum computing?"}
    ]
)

print(response.choices[0].message.content)
```

#### TypeScript

```typescript
import OpenAI from "openai";

const client = new OpenAI({
    apiKey: "YOUR_CAESAR_API_KEY",
    baseURL: "https://api.caesar.xyz/compat"
});

const response = await client.chat.completions.create({
    model: "caesar-research",
    messages: [
        { role: "user", content: "What are the latest developments in quantum computing?" }
    ]
});

console.log(response.choices[0].message.content);
```

#### cURL

```bash
curl https://api.caesar.xyz/compat/chat/completions \
  -H "Authorization: Bearer YOUR_CAESAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "caesar-research",
    "messages": [
      {"role": "user", "content": "What are the latest developments in quantum computing?"}
    ]
  }'
```

## Available endpoints

| Endpoint                        | Description                           |
| ------------------------------- | ------------------------------------- |
| `POST /compat/chat/completions` | Chat completions format (recommended) |
| `POST /compat/completions`      | Text completions format               |

> **Info**
>
> Both endpoints trigger Caesar's research workflow. The last user message becomes the research query, and the response includes synthesized findings with citations.

---

## Including files in research

Caesar extends the OpenAI chat completions format to support file attachments for document-grounded research. This is a two-step process:

#### Upload files

First, upload your files using the Caesar files endpoint:

```bash
curl -X POST https://api.caesar.xyz/research/files \
  -H "Authorization: Bearer YOUR_CAESAR_API_KEY" \
  -F "file=@document.pdf"
```

Response:

```json
{
  "id": "9c6f8b1a-2a4f-4a35-86b9-0d0b5e25d5e5",
  "filename": "document.pdf",
  "size": 245678,
  "created_at": "2025-01-15T10:30:00Z"
}
```

#### Reference files in messages

Include the file ID in your chat completion request using multimodal content parts:

```json
{
  "model": "caesar-research",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Summarize the key findings from this document"
        },
        {
          "type": "file",
          "file": {
            "filename": "document.pdf",
            "fileData": "9c6f8b1a-2a4f-4a35-86b9-0d0b5e25d5e5"
          }
        }
      ]
    }
  ]
}
```

> **Warning**
>
> **Important:** The `fileData` field must contain the Caesar file UUID returned from the upload endpoint, not base64 data or a URL. Files are only supported on `/compat/chat/completions`, not `/compat/completions`.

### Python example with files

```python
import requests
from openai import OpenAI

# Step 1: Upload file
upload_response = requests.post(
    "https://api.caesar.xyz/research/files",
    headers={"Authorization": "Bearer YOUR_CAESAR_API_KEY"},
    files={"file": open("report.pdf", "rb")}
)
file_id = upload_response.json()["id"]

# Step 2: Research with file context
client = OpenAI(
    api_key="YOUR_CAESAR_API_KEY",
    base_url="https://api.caesar.xyz/compat"
)

response = client.chat.completions.create(
    model="caesar-research",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What are the main conclusions in this report?"},
                {"type": "file", "file": {"filename": "report.pdf", "fileData": file_id}}
            ]
        }
    ]
)

print(response.choices[0].message.content)
```

---

## Research configuration

Caesar extends the OpenAI format with a `metadata` object for fine-tuning research behavior:

```json
{
  "model": "caesar-research",
  "messages": [{"role": "user", "content": "Your query"}],
  "metadata": {
    "reasoning_loops": 3,
    "source_timeout": 60,
    "reasoning_mode": true,
    "allow_early_exit": true,
    "exclude_social": false,
    "system_prompt": "Focus on peer-reviewed sources"
  }
}
```

| Parameter          | Type    | Default | Description                   |
| ------------------ | ------- | ------- | ----------------------------- |
| `reasoning_loops`  | integer | auto    | Research iterations (1-10)    |
| `source_timeout`   | integer | auto    | Seconds per source (3-180)    |
| `reasoning_mode`   | boolean | auto    | Use advanced reasoning models |
| `allow_early_exit` | boolean | auto    | Complete early if sufficient  |
| `exclude_social`   | boolean | auto    | Exclude social media sources  |
| `system_prompt`    | string  | -       | Custom synthesis instructions |

> **Tip**
>
> When `metadata` is omitted, Caesar uses **auto mode** to intelligently configure parameters based on your query. See [Research Parameters](/documentation/get-started/research-parameters) for details.

---

## Streaming

Enable streaming to receive results as Server-Sent Events:

#### Python

```python
stream = client.chat.completions.create(
    model="caesar-research",
    messages=[{"role": "user", "content": "Latest AI research trends"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

#### TypeScript

```typescript
const stream = await client.chat.completions.create({
    model: "caesar-research",
    messages: [{ role: "user", content: "Latest AI research trends" }],
    stream: true
});

for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content || "");
}
```

---

## Response format

Responses follow the OpenAI format with Caesar's research content:

```json
{
  "id": "f2f6e5db-2c7d-4f56-bb0c-5a6b6a7a9b10",
  "object": "chat.completion",
  "created": 1705312200,
  "model": "caesar-research",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Based on current research...\n\n## References\n[1] https://example.com/source1\n[2] https://example.com/source2"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}
```

> **Info**
>
> Caesar appends a **References** section to responses with numbered citations linking to source URLs.

---

## Supported parameters

### Request fields

| Field         | Support                                |
| ------------- | -------------------------------------- |
| `model`       | Accepted (use `caesar-research`)       |
| `messages`    | Fully supported                        |
| `prompt`      | Fully supported (completions endpoint) |
| `stream`      | Fully supported                        |
| `max_tokens`  | Accepted for compatibility             |
| `temperature` | Accepted for compatibility (0-2)       |
| `top_p`       | Accepted for compatibility (0-1)       |
| `stop`        | Accepted for compatibility             |
| `seed`        | Accepted for compatibility             |
| `metadata`    | Caesar extension for research config   |

### Response fields

| Field                     | Support                           |
| ------------------------- | --------------------------------- |
| `id`                      | Fully supported (Caesar job UUID) |
| `object`                  | Fully supported                   |
| `created`                 | Fully supported                   |
| `model`                   | Echo of request model             |
| `choices`                 | Always length 1                   |
| `choices[].message`       | Fully supported                   |
| `choices[].finish_reason` | Fully supported                   |
| `usage`                   | Included (values are 0)           |

---

## Limitations

#### No token counting

Usage statistics return 0 for all token fields. Caesar uses research-based pricing rather than token counting.

#### Single choice

The `n` parameter is not supported. Responses always contain exactly one choice.

#### No function calling

Tool/function calling is not supported. Caesar focuses on research synthesis rather than tool use.

#### Files require chat endpoint

File attachments only work with `/compat/chat/completions`, not the text completions endpoint.

### Ignored parameters

These OpenAI parameters are accepted but have no effect:

* `logprobs`, `top_logprobs`
* `logit_bias`
* `presence_penalty`, `frequency_penalty`
* `response_format`
* `tools`, `tool_choice`
* `user`

---

## Error handling

Errors follow the OpenAI format:

```json
{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error"
  }
}
```

| Status | Meaning                                                       |
| ------ | ------------------------------------------------------------- |
| 400    | Invalid request (missing required fields, invalid parameters) |
| 401    | Invalid or missing API key                                    |
| 429    | Rate limit exceeded                                           |
| 500    | Internal server error                                         |

#### Need the native API?

For full access to Caesar's features including real-time progress events, collections, and detailed research metadata, use the [Research API](/api-reference/research/create-research) directly.

> Use OpenAI SDKs to access Caesar's research capabilities