> 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/get-started/introduction/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.caesar.xyz/_mcp/server.

# Caesar API

![Alt text](file:assets/header.png "Caesar")

**Give your application the ability to research anything.**

Caesar is an agentic research API that transforms questions into comprehensive, citation-backed answers. Unlike traditional search APIs that return links, Caesar reads, reasons, and synthesizes, delivering expert-level research in seconds.

Explore the API

Get your API key

---

## See it in action

**`Create a research job`**

```bash title="Create a research job"
curl -X POST https://api.caesar.xyz/research \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the leading approaches to nuclear fusion?", "auto": true}'
```

**`Response with citations`**

```json title="Response with citations" {4-5,8-16}
{
  "id": "res_7f3a2b1c",
  "status": "completed",
  "reasoning_loops_consumed": 2,
  "running_time": 34,
  "content": "Nuclear fusion research is advancing through several key approaches...\n\n**Magnetic Confinement (Tokamaks)**\nThe ITER project [1] represents the largest tokamak...\n\n**Inertial Confinement**\nThe National Ignition Facility achieved ignition in December 2022 [2]...",
  "results": [
    {
      "title": "ITER - the way to new energy",
      "url": "https://www.iter.org/",
      "citation_index": 1
    },
    {
      "title": "National Ignition Facility Achieves Fusion Ignition",
      "url": "https://www.llnl.gov/news/...",
      "citation_index": 2
    }
  ]
}
```

> **Tip**
>
> Every response includes numbered citations linking to source URLs. Your users can verify any claim.

---

## Why Caesar?

Traditional search APIs return links. RAG systems retrieve chunks. Caesar does something different: it **researches**.

| Approach    | What you get                                         |
| ----------- | ---------------------------------------------------- |
| Search APIs | 10 blue links to sort through                        |
| RAG         | Retrieved chunks, often lacking context              |
| LLMs        | Answers with no sources, potential hallucinations    |
| **Caesar**  | Synthesized research with live sources and citations |

#### Real-time knowledge

Every query searches live sources. No stale training data, no knowledge cutoffs. Ask about today's news or last week's research papers.

#### Agentic reasoning

Caesar doesn't just retrieve. It analyzes, identifies gaps, formulates follow-up queries, and iteratively builds understanding.

---

## How it works

Caesar uses an **agentic research loop** that mirrors how expert researchers work:

#### Analyze

Parses your question to understand intent and identify key concepts.

#### Gather

Searches web, academic databases, news, and financial data. Reads and extracts relevant content.

#### Evaluate

Identifies knowledge gaps. If critical information is missing, formulates follow-up queries.

#### Iterate

Repeats the cycle (controlled by `reasoning_loops`) until thoroughly answered.

#### Synthesize

Combines findings into a coherent, cited response.

**`Control research depth`**

```json title="Control research depth" focus={3-4}
{
  "query": "Comprehensive analysis of quantum computing applications in drug discovery",
  "reasoning_loops": 5,
  "reasoning_mode": true,
  "exclude_social": true
}
```

> **Info**
>
> Use `auto: true` to let Caesar automatically configure parameters based on your query complexity.

---

## Quick start

### 1. Get your API key

Create an API key in your [dashboard](https://www.caesar.xyz/api-keys). Keys start with `csk-` and should be kept secret.

### 2. Make your first request

#### cURL

```bash
curl -X POST https://api.caesar.xyz/research \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What companies are leading in solid-state battery development?", "auto": true}'
```

#### Python

```python
import requests

response = requests.post(
    "https://api.caesar.xyz/research",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "query": "What companies are leading in solid-state battery development?",
        "auto": True
    }
)

job = response.json()
print(f"Job ID: {job['id']}")
```

#### TypeScript

```typescript
const response = await fetch("https://api.caesar.xyz/research", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    query: "What companies are leading in solid-state battery development?",
    auto: true
  })
});

const job = await response.json();
console.log(`Job ID: ${job.id}`);
```

### 3. Retrieve results

Research jobs run asynchronously. Poll for completion or stream results:

**`Poll for results`**

```bash title="Poll for results"
curl https://api.caesar.xyz/research/{job_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**`Or stream as results arrive`**

```bash title="Or stream as results arrive"
curl https://api.caesar.xyz/research/{job_id}/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream"
```

---

## Use cases

| Use case                    | Example query                                          | Recommended config                         |
| --------------------------- | ------------------------------------------------------ | ------------------------------------------ |
| **Quick lookups**           | "Apple Q3 2024 revenue"                                | `reasoning_loops: 1`                       |
| **Comparative analysis**    | "Compare React vs Vue for enterprise apps"             | `reasoning_loops: 3`                       |
| **Deep research**           | "Systematic review of CRISPR applications in oncology" | `reasoning_loops: 5, reasoning_mode: true` |
| **Technical due diligence** | "Architecture and scaling challenges of company X"     | `reasoning_loops: 4, exclude_social: true` |

---

## Integration options

Choose how you want to integrate:

#### Native API

Full access to all features: research parameters, file uploads, collections, and streaming.

```bash
curl -X POST https://api.caesar.xyz/research \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"query": "...", "reasoning_loops": 3}'
```

View API Reference

#### OpenAI SDK

Drop-in replacement. Change your base URL and you're ready.

```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": "Your research question"}]
)
```

OpenAI Compatibility Guide

#### SDKs

Official libraries with typed interfaces and automatic retries.

```bash
pip install caesar-ai
# or
npm install @caesar-ai/sdk
```

SDK Documentation

---

## Key concepts

#### Research Parameters

Control depth with `reasoning_loops` (1-10), model quality with `reasoning_mode`, and source filtering with `exclude_social`. Or use `auto: true` to let Caesar optimize.

[Learn more →](/documentation/get-started/research-parameters)

#### Document grounding

Upload PDFs and documents, then include them in research. Caesar combines your files with live web research.

[Learn more →](/api-reference/files/upload-file)

#### System prompts

Shape output format. Get responses as JSON, bullet points, executive summaries, or custom structures.

[Learn more →](/documentation/get-started/prompt-guidance)

#### Streaming

Get results via Server-Sent Events as they're generated. Show progress and reduce perceived latency.

[Learn more →](/api-reference/research/get-research-events)

---

## Next steps

#### [API Reference](/api-reference)

Explore all endpoints

#### [Research Parameters](/documentation/get-started/research-parameters)

Fine-tune research depth

#### [Rate Limits](/documentation/get-started/rate-limits)

Understand usage limits

**Need help?** Contact us at [support@caesar.xyz](mailto:support@caesar.xyz)