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.

Specifying a version

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

$
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:

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.

Upgrading your version

To upgrade your API key to a newer version:

1. Review the 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

Changelog

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
}

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