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

# Versioning

Caesar uses date-based API versioning to ensure backward compatibility while allowing the API to evolve. Each version is identified by a release date in `YYYY-MM-DD` format.

> **Info**
>
> The current API version is **2025-11-27**. When you create an API key, it's automatically pinned to the current version.

## Specifying a version

You can specify which API version to use in two ways:

#### Header

Include the `API-Version` header with your request:

```bash
curl https://api.caesar.xyz/research \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "API-Version: 2025-11-27" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is quantum computing?"}'
```

#### API Key Default

Each API key is pinned to a specific version. If you don't include the `API-Version` header, requests will use your API key's pinned version.

You can view and update your API key's version in the [dashboard](https://www.caesar.xyz/api-keys).

## Version resolution

The API determines which version to use in the following order:

#### API-Version header

If you include the `API-Version` header, that version is used. This allows you to override your API key's default version for testing.

#### API key's pinned version

If no header is provided, the version pinned to your API key is used.

#### Latest version

If neither is available (e.g., for unauthenticated endpoints), the latest version is used.

The `API-Version` header is always included in responses, confirming which version was used.

## Backward compatibility

When you make a request using an older API version, Caesar automatically transforms your request and response to maintain compatibility:

* **Request transformation**: Old field names and formats are converted to the current internal format
* **Response transformation**: Current response data is converted back to match the older version's schema

This means you can continue using an older API version without code changes, even as the API evolves.

> **Warning**
>
> While older versions remain supported, we recommend upgrading to newer versions to access new features and improvements.

## Upgrading your version

To upgrade your API key to a newer version:

1. Review the [changelog](#changelog) below for breaking changes
2. Update your code to handle any schema changes
3. Test with the `API-Version` header before committing
4. Update your API key's pinned version in the dashboard

> **Tip**
>
> Use the `API-Version` header to test a new version before updating your API key's default. This lets you verify compatibility without affecting production traffic.

## Changelog

#### 2025-11-27 (Current)

**Research endpoint changes:**

| Change             | Details                                                                 |
| ------------------ | ----------------------------------------------------------------------- |
| Renamed parameter  | `compute_units` → `reasoning_loops`                                     |
| New parameter      | `source_timeout` - Maximum seconds to wait per source (default: 60)     |
| New parameter      | `reasoning_mode` - Enable advanced reasoning model (default: false)     |
| New parameter      | `allow_early_exit` - Allow completion before max loops (default: false) |
| New parameter      | `exclude_social` - Exclude social media sources (default: false)        |
| New parameter      | `auto` - Auto-configure based on query analysis                         |
| New response field | `reasoning_loops_consumed` - Actual loops executed                      |
| New response field | `running_time` - Total execution time in seconds                        |
| Removed field      | `score` removed from result items                                       |
| New endpoints      | Collections API for organizing files                                    |
| New endpoint       | Research events endpoint for progress tracking                          |

**Migration guide:**

```diff
// Request body
{
  "query": "What is quantum computing?",
- "compute_units": 3
+ "reasoning_loops": 3,
+ "source_timeout": 60,
+ "reasoning_mode": true
}
```

```diff
// Response - result items
{
  "id": "abc-123",
  "title": "Example Source",
  "url": "https://example.com",
- "score": 0.92,
  "citation_index": 1
}
```

#### 2025-08-08 (Initial)

Initial API release with:

* Research object creation and retrieval
* File upload and management
* `compute_units` parameter for controlling research depth
* Result items with relevance `score`

## Version support policy

* **Current version**: Fully supported with all new features
* **Previous versions**: Maintained for backward compatibility with automatic request/response transformation
* **Deprecation**: Versions may be deprecated with 12 months notice

#### Need help upgrading?

Contact us at [support@caesar.xyz](mailto:support@caesar.xyz) if you need assistance migrating to a newer API version.

> How Caesar handles API versioning and backward compatibility