Connect Caesar to your agent

No key, no signup. Caesar is free to use and the anonymous tier serves the full search, read, and feedback loop. Pick the rail 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.

Install console

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 handles, 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://search-api-staging-779189860552.europe-west1.run.app/mcp

Best for chat and IDE clients that support remote tools. Omit auth for anonymous access; add Authorization: Bearer $CAESAR_API_KEY only if you have a partner key.

Verify

curl -s https://search-api-staging-779189860552.europe-west1.run.app/mcp \
  -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 caesar_search and caesar_read.

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 raw handles.

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 caesar_search and caesar_read; anonymous access works unless CAESAR_API_KEY is set.

Verify

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

Success prints function.

curl -s https://search-api-staging-779189860552.europe-west1.run.app/v1/search \
  -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://search-api-staging-779189860552.europe-west1.run.app/v1/search \
  -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 loop below to read the top result and send feedback.

Product loop

Search

Query returns ranked results with search_id and stable doc_id handles.

Read

Pass doc_id to read clean markdown plus capture metadata.

Cite

Preserve source_url, passage_id, capture_id, and capture_time.

Feedback

Send search_id and doc_id when a result helped.

Not sure which rail?

Use this rail	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 loop

The underlying API is three HTTP calls. This works with only curl and jq.

RESPONSE=$(curl -s https://search-api-staging-779189860552.europe-west1.run.app/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "postgres 17 logical replication failover", "max_results": 3}')

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

Save the two handles 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://search-api-staging-779189860552.europe-west1.run.app/v1/document \
  -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 with content.range.start_char set to the previous response’s content.start_char plus content.char_count. See documents.

Feedback

curl -s https://search-api-staging-779189860552.europe-west1.run.app/v1/feedback \
  -H "Content-Type: application/json" \
  -d "{\"event_type\": \"result_helpful\", \"search_id\": \"$SEARCH_ID\", \"doc_id\": \"$DOC_ID\", \"rank\": 1}" \
  | jq '{feedback_id, accepted}'

That is the whole contract: search, read, feedback. Every Caesar surface uses the same loop.

Build with Caesar

Python SDK

pip install caesar-search

TypeScript SDK

npm install caesar-search

AI SDK tools

caesarTools() exposes caesar_search and caesar_read.

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 - modes, filters, and ranking behavior.
Documents - content selection, truncation, and continuation reads.
Pricing, authentication, and rate limits - free access, partner keys, and request ceilings.

​Install console

​Product loop

Search

Read

Cite

Feedback

​Not sure which rail?

​Raw API loop

​Build with Caesar

Python SDK

TypeScript SDK

AI SDK tools

Framework recipes

​Where next

Install console

Product loop

Not sure which rail?

Raw API loop

Build with Caesar

Where next