Authentication

Caesar uses standard Bearer authentication. Sign up in the Caesar app, create an API key, and set it in the Authorization header:

curl -s https://alpha.api.trycaesar.com/v1/search \
  -H "Authorization: Bearer $CAESAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "rust async runtime comparison", "max_results": 3}'

For a limited time, all accounts receive a $1,000 starting credit grant after signup.

API keys

Property	API key behavior
Setup	Create in the Caesar app
Rate limit	per-key limit, default 100 requests/second
Account attribution	recorded to your account
Document access by `doc_id`	account-granted documents

An API key controls four things:

Usage and credits. Calls are attributed to the account or team that owns the key.
A dedicated rate limit. Requests are counted per key, not per IP. See rate limits.
Account-scoped attribution. Keyed searches are recorded to your account, and /v1/feedback referencing a search_id or doc_id is checked against that ownership. Your feedback provably belongs to your searches.
Document grants. /v1/document lookups by doc_id resolve documents your account has been granted — by appearing in your search results or by a prior direct canonical_url lookup.

Getting a key

Create keys in the Caesar app. Store the secret once; the full key is only shown at creation time.

Key format

Console-issued keys start with csk_. Legacy alpha keys may start with sk_live_, followed by a 12-character key_prefix and a longer secret. Non-secret key prefixes are safe to display in dashboards and logs to identify a key. The full key is returned exactly once at creation and stored only as a hash; it cannot be retrieved again.

Scopes

Scope	Grants
`search:read`	`POST /v1/search`
`document:read`	`POST /v1/document`
`feedback:write`	`POST /v1/feedback`

New keys get all three scopes by default. Calling an endpoint your key lacks the scope for returns 403:

{
  "type": "error",
  "request_id": "ee314ccd-dbcd-418f-9c6a-f2917c599c67",
  "error": { "code": "insufficient_scope", "message": "API key is not allowed to call this endpoint" }
}

Invalid keys are rejected

Every API request must authenticate. A missing, malformed, unknown, expired, or revoked key returns 401:

{
  "type": "error",
  "request_id": "ee314ccd-dbcd-418f-9c6a-f2917c599c67",
  "error": { "code": "invalid_api_key", "message": "missing or invalid API key" }
}

One environment variable everywhere

Every first-party client reads CAESAR_API_KEY:

# set in your shell profile, or inject it from your secret manager
export CAESAR_API_KEY="$(your-secret-manager get caesar-api-key)"

The Python SDK and TypeScript SDK pick it up automatically in their constructors, the CLI resolves it after the --key flag, and the MCP server accepts it as a Bearer header. If the variable is unset and no key is stored in client config, API calls fail with 401 missing_api_key.

Client attribution: X-Caesar-Client

First-party clients send an attribution header of the form X-Caesar-Client: cli/0.2.0 (or python-sdk/0.2.0, ts-sdk/0.2.0). It is a convention, not a contract: the server does not validate or act on it. If you build on the raw API, sending X-Caesar-Client: yourtool/1.2.3 is encouraged because it helps the Caesar team understand client traffic.

Key hygiene

Never paste an API key into a chat, an issue, or a commit. Keys belong in CAESAR_API_KEY or your secret manager. The CLI stores keys safely via caesar-search auth login — the browser flow mints a named, revocable key straight into the OS keychain, --device covers SSH/headless machines, and --key - pipes one from a secret manager — and masks them in all output. If a key leaks, contact the Caesar team to revoke it — the key itself cannot be recovered or rotated in place.

​API keys

​Getting a key

​Key format

​Scopes

​Invalid keys are rejected

​One environment variable everywhere

​Client attribution: X-Caesar-Client

​Key hygiene

API keys

Getting a key

Key format

Scopes

Invalid keys are rejected

One environment variable everywhere

Client attribution: X-Caesar-Client

Key hygiene