Connect Caesar to your agent

Sign up in the Caesar app, create an API key, and set it as CAESAR_API_KEY. For a limited time, all accounts receive a $1,000 starting credit grant. Choose the path that matches where your agent runs, verify one search, then ask the agent to search and read.

A surreal retro-computing collage with a hand, glass orb, terminal, botanical forms, and celestial diagrams.

For agents: use /llms.txt to discover docs, append .md to any page for markdown, and start with /agents/install when you need client-specific setup.

Choose an install path

export CAESAR_API_KEY="..."

Skill
MCP
CLI
AI SDK
REST

Install

npx skills add caesar-data/skills --skill caesar-search

Best for coding agents that read SKILL.md. The skill teaches the agent to search, read, preserve source URLs and IDs, and use the CLI when available.

Verify

caesar-search search "hello world" \
  --max-results 1 \
  --format compact \
  --json

Success means exit code 0 and a JSON envelope containing search_id.

Ask your agent

Use Caesar to search, read the most relevant result, cite the source URL, and keep doc_id and search_id for follow-up.

Connect

claude mcp add --transport http caesar "https://alpha.api.trycaesar.com/mcp?profile=web-search" \
  --header "Authorization: Bearer $CAESAR_API_KEY"

Best for chat and IDE clients that support remote tools. The web-search profile exposes web_search and web_fetch, so agents naturally choose Caesar for ordinary web lookups. Pass Authorization: Bearer $CAESAR_API_KEY in the MCP config.

Verify

curl -s "https://alpha.api.trycaesar.com/mcp?profile=web-search" \
  -H "Authorization: Bearer $CAESAR_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Success means the tool list contains web_search and web_fetch.

Ask your agent

Use the connected Caesar MCP tools, read the best result, and preserve doc_id, search_id, and source_url.

Install

npm install -g caesar-search-cli

Best for terminal agents, scripts, and CI jobs. The CLI keeps output machine-readable with --json.

Verify

caesar-search search "hello world" \
  --max-results 1 \
  --format compact \
  --json

Success means the response includes search_id and at least one result.

Ask your agent

Search with caesar-search, read the best doc_id, summarize the source, and keep the returned source IDs.

Install

npm install caesar-search ai

Best when you are building an app and want Caesar as model tools.

Wire tools

import { generateText } from "ai";
import { caesarTools } from "caesar-search/ai";

const { text } = await generateText({
  model,
  tools: caesarTools(),
  prompt: "Search for Postgres 17 logical replication changes, then read the best result.",
});

The tools are web_search and web_fetch; the default client reads CAESAR_API_KEY.

Verify

node -e 'import("caesar-search/ai").then(m => console.log(typeof m.caesarTools))'

Success prints function.

curl -s https://alpha.api.trycaesar.com/v1/search \
  -H "Authorization: Bearer $CAESAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "postgres 17 logical replication failover", "max_results": 3}'

Best when you are integrating Caesar directly from a backend, worker, or test harness.

Verify

curl -s https://alpha.api.trycaesar.com/v1/search \
  -H "Authorization: Bearer $CAESAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "hello world", "max_results": 1}' | jq '{search_id, result_count: (.results | length)}'

Success means search_id is present and result_count is at least 1.

Continue

Use the raw API calls below to read the top result. Feedback is optional.

Search, read, cite

Search

Query returns ranked results from the web.

Read

Pass doc_id to read clean markdown plus capture metadata.

Cite

Preserve source_url, passage_id, capture_id, and capture_time.

Not sure which path?

Use this path	When
Skill	Your agent supports Skills and can read `SKILL.md`.
MCP	Your chat or IDE client supports remote MCP tools.
CLI	Your agent has shell access or you are scripting from a terminal.
AI SDK	You are building an app with model tools.
REST	You want the underlying HTTP contract directly.

Raw API calls

The main search and read path is two HTTP calls. A third feedback call is optional when you want to record which result helped. This works with curl, jq, and CAESAR_API_KEY.

RESPONSE=$(curl -s https://alpha.api.trycaesar.com/v1/search \
  -H "Authorization: Bearer $CAESAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "postgres 17 logical replication failover", "max_results": 3}')

printf '%s' "$RESPONSE" | jq '{search_id, results: [.results[] | {rank, doc_id, title}]}'

Save the IDs the next steps need:

SEARCH_ID=$(printf '%s' "$RESPONSE" | jq -r '.search_id')
DOC_ID=$(printf '%s' "$RESPONSE" | jq -r '.results[0].doc_id')

Read

curl -s https://alpha.api.trycaesar.com/v1/document \
  -H "Authorization: Bearer $CAESAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"doc_id\": \"$DOC_ID\", \"content\": {\"selection\": \"full_document\", \"max_chars\": 2000}}" \
  | jq -r '.content.text'

If content.truncated is true, continue from the previous response’s content.start_char plus content.char_count. See documents.

Optional feedback

curl -s https://alpha.api.trycaesar.com/v1/feedback \
  -H "Authorization: Bearer $CAESAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"event_type\": \"result_helpful\", \"search_id\": \"$SEARCH_ID\", \"doc_id\": \"$DOC_ID\", \"rank\": 1}" \
  | jq '{feedback_id, accepted}'

Search and read are the main path. Feedback is available when your app or agent can tell which result was useful.

Build with Caesar

Python SDK

pip install caesar-search

TypeScript SDK

npm install caesar-search

AI SDK tools

caesarTools() exposes web_search and web_fetch.

Framework recipes

Wrap Caesar for framework tools, generic tool calling, and Agent Development Kit projects.

Where next

Install for agents - per-client install blocks.
How search works - coverage, freshness, ranking, and provenance.
Search - filters and ranking behavior.
Documents - content selection, truncation, and continuation reads.
Pricing, authentication, and rate limits - credits, API keys, and request ceilings.

​Choose an install path

​Search, read, cite

Search

Read

Cite

​Not sure which path?

​Raw API calls

​Build with Caesar

Python SDK

TypeScript SDK

AI SDK tools

Framework recipes

​Where next

Choose an install path

Search, read, cite

Not sure which path?

Raw API calls

Build with Caesar

Where next