Skip to main content
Caesar is one API with four client surfaces. Pick the surface that matches your harness; everything else — verbs, field names, presets, limits — is identical across them.
For agents reading the docs: use /llms.txt to discover pages, append .md to page URLs for markdown, and start with Install for agents when you need client-specific setup.

​
Pick your surface

Your harnessUseWhy
Inner-loop shell work (Claude Code, terminal agents, scripts)The CLI, plus the forked skills in Claude Code--json machine output, -o <file> keeps large payloads out of your context window, stable exit codes to branch on
Chat or IDE assistant (Cursor, Windsurf, any MCP client)The remote MCP server at /mcpZero install, streamable HTTP, two tools: caesar_search and caesar_read
Building an applicationPython SDK or TypeScript SDK; caesar-search/ai for Vercel AI SDK agentsTyped clients with retries built in; caesarTools() is a drop-in tool set
Everything elseRaw HTTP — spec served at /openapi/public.json on the API hostSee the API reference

​
Same three verbs everywhere

VerbRESTCLIMCPSDKs
SearchPOST /v1/searchcaesar-search searchcaesar_searchclient.search()
ReadPOST /v1/documentcaesar-search readcaesar_readclient.read()
FeedbackPOST /v1/feedbackcaesar-search feedbacknot exposedclient.feedback()
The same search on each surface: 
curl -s https://search-api-staging-779189860552.europe-west1.run.app/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"zig comptime explained","max_results":5,"response":{"verbosity":"compact"}}'

​
Conventions that hold on every surface

​
Wire fields are snake_case

doc_id, search_id, max_results, start_char, canonical_url — exactly as the API returns them. No surface converts to camelCase. Do not expect docId in any response.

​
One set of verbosity presets

verbosity (REST/SDKs), --format (CLI search), and response_format (MCP, AI SDK tools) are the same presets. Use compact in agent loops — it is the token-efficient choice. standard adds quotable passages; full adds provenance. See response shaping.
SurfaceParameterValuesDefault
REST / SDKsresponse.verbosity / verbosityids_only, compact, standard, fullstandard
CLI--formatids_only, compact, standard, fullstandard
MCPresponse_formatcompact, standard, full (ids_only falls back to compact)compact
AI SDK toolsresponse_formatcompact, standard, fullcompact

​
max_results is 1-50

REST and SDKs default to 10 and reject out-of-range values with 400 validation_error. The CLI also defaults to 10 but rejects out-of-range values locally before any request is sent (bad_input, exit 2). MCP defaults to 8 and silently clamps out-of-range values into 1-50. The AI SDK tools (caesarTools()) also default to 8, like MCP.

​
Continue truncated reads with start_char

A truncated read reports truncated: true with start_char and char_count (nested under content on REST/CLI/SDKs, top-level over MCP). Continue from start_char + char_count: 
caesar-search read "$DOC_ID" --start-char 12000 --json
Do not retry with a bigger max_chars. A non-zero start_char forces full_document selection so offsets stay contiguous — a query passed alongside it will not excerpt.

​
Preserve identifiers, cite only returned URLs

doc_id and search_id are stable handles: thread them verbatim between search, read, and feedback. Cite only URLs the API returned (canonical_url, url, source_url) — never construct or guess a URL.

​
Errors and retries

All API errors use one envelope: 
{
  "type": "error",
  "request_id": "ee314ccd-dbcd-418f-9c6a-f2917c599c67",
  "error": { "code": "rate_limited", "message": "rate limit exceeded" }
}
Retry 429 and 5xx with exponential backoff; the CLI and SDKs already do (3 retries, 500 ms doubling, 8 s cap). Rate-limit windows are one second — the X-RateLimit-Reset header says when the window resets. Do not retry other 4xx. The CLI mirrors errors as a JSON envelope on stderr and exits 2 (bad input), 3 (auth), 4 (API error), or 5 (timeout) — branch on exit codes, not output. See errors and rate limits.

​
Keyless works

CAESAR_API_KEY is optional. Keyless requests run on the anonymous tier (30 requests/second per IP on staging). A present-but-invalid key returns 401 invalid_api_key — it never falls back to anonymous. See authentication.

​
Close the loop with feedback

After acting on results, send feedback — it improves ranking. Use result_helpful when a result answered the task and stale_result when content was outdated, with the search_id and doc_id you got back: 
caesar-search feedback --event-type result_helpful --search-id "$SID" --doc-id "$DID"
Feedback is deliberately not exposed over MCP; use any other surface.

​
Install

Install for agents

Copy-paste install blocks per environment — Claude Code, MCP clients, skills directories, shell agents, the Vercel AI SDK, and raw HTTP — each with a verification step.