Versioning | Caesar | API Documentation

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.

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

API Key Default

Include the API-Version header with your request:

$ 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?"}'

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.

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:

Review the changelog below for breaking changes
Update your code to handle any schema changes
Test with the API-Version header before committing
Update your API key’s pinned version in the dashboard

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:

1 // Request body
2 {
3   "query": "What is quantum computing?",
4 - "compute_units": 3
5 + "reasoning_loops": 3,
6 + "source_timeout": 60,
7 + "reasoning_mode": true
8 }

1 // Response - result items
2 {
3   "id": "abc-123",
4   "title": "Example Source",
5   "url": "https://example.com",
6 - "score": 0.92,
7   "citation_index": 1
8 }

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?