> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trycaesar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Caesar to your agent

> Sign up for Caesar, install search into an agent, verify search and read, then see the raw API loop.

Sign up in the [Caesar app](https://app.trycaesar.com), 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.

<img src="https://mintcdn.com/caesar-6aebfafe/QJlA46vuJOUwD1Oh/images/editorial/quickstart-terminal-collage.png?fit=max&auto=format&n=QJlA46vuJOUwD1Oh&q=85&s=a6d2b7a0e50c6bbeb7a33c26a5f9353a" alt="A surreal retro-computing collage with a hand, glass orb, terminal, botanical forms, and celestial diagrams." width="1344" height="752" data-path="images/editorial/quickstart-terminal-collage.png" />

<Tip>
  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.
</Tip>

## Choose an install path

```bash theme={"system"}
export CAESAR_API_KEY="..."
```

<Tabs>
  <Tab title="Skill">
    <Steps>
      <Step title="Install">
        ```bash theme={"system"}
        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.
      </Step>

      <Step title="Verify">
        ```bash theme={"system"}
        caesar-search search "hello world" \
          --max-results 1 \
          --format compact \
          --json
        ```

        <Check>
          Success means exit code 0 and a JSON envelope containing `search_id`.
        </Check>
      </Step>

      <Step title="Ask your agent">
        <Prompt description="Use Caesar to search, read the most relevant result, cite the source URL, and keep doc_id and search_id for follow-up." actions={["copy"]}>
          {`Use Caesar to search for "postgres 17 logical replication failover".
                    Read the most relevant result, cite the source URL, and keep the doc_id and search_id for follow-up.`}
        </Prompt>
      </Step>
    </Steps>
  </Tab>

  <Tab title="MCP">
    <Steps>
      <Step title="Connect">
        ```bash theme={"system"}
        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.
      </Step>

      <Step title="Verify">
        ```bash theme={"system"}
        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"}'
        ```

        <Check>
          Success means the tool list contains `web_search` and `web_fetch`.
        </Check>
      </Step>

      <Step title="Ask your agent">
        <Prompt description="Use the connected Caesar MCP tools, read the best result, and preserve doc_id, search_id, and source_url." actions={["copy"]}>
          {`Use web_search to search for "postgres 17 logical replication failover".
                    Read the best result with web_fetch and preserve doc_id, search_id, and source_url.`}
        </Prompt>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI">
    <Steps>
      <Step title="Install">
        ```bash theme={"system"}
        npm install -g caesar-search-cli
        ```

        Best for terminal agents, scripts, and CI jobs. The CLI keeps output machine-readable with `--json`.
      </Step>

      <Step title="Verify">
        ```bash theme={"system"}
        caesar-search search "hello world" \
          --max-results 1 \
          --format compact \
          --json
        ```

        <Check>
          Success means the response includes `search_id` and at least one result.
        </Check>
      </Step>

      <Step title="Ask your agent">
        <Prompt description="Search with caesar-search, read the best doc_id, summarize the source, and keep the returned source IDs." actions={["copy"]}>
          {`Search with caesar-search, read the best doc_id, then summarize the source.
                    Keep the raw search_id and doc_id in your final answer.`}
        </Prompt>
      </Step>
    </Steps>
  </Tab>

  <Tab title="AI SDK">
    <Steps>
      <Step title="Install">
        ```bash theme={"system"}
        npm install caesar-search ai
        ```

        Best when you are building an app and want Caesar as model tools.
      </Step>

      <Step title="Wire tools">
        ```ts theme={"system"}
        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`.
      </Step>

      <Step title="Verify">
        ```bash theme={"system"}
        node -e 'import("caesar-search/ai").then(m => console.log(typeof m.caesarTools))'
        ```

        <Check>
          Success prints `function`.
        </Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="REST">
    <Steps>
      <Step title="Search">
        ```bash theme={"system"}
        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.
      </Step>

      <Step title="Verify">
        ```bash theme={"system"}
        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)}'
        ```

        <Check>
          Success means `search_id` is present and `result_count` is at least 1.
        </Check>
      </Step>

      <Step title="Continue">
        Use the raw API calls below to read the top result. Feedback is optional.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Search, read, cite

<CardGroup cols={3}>
  <Card title="Search" icon="search" href="/concepts/search">
    Query returns ranked results from the web.
  </Card>

  <Card title="Read" icon="file-text" href="/concepts/documents">
    Pass `doc_id` to read clean markdown plus capture metadata.
  </Card>

  <Card title="Cite" icon="quote" href="/concepts/provenance">
    Preserve `source_url`, `passage_id`, `capture_id`, and `capture_time`.
  </Card>
</CardGroup>

## 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`.

<Steps>
  <Step title="Search">
    ```bash theme={"system"}
    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:

    ```bash theme={"system"}
    SEARCH_ID=$(printf '%s' "$RESPONSE" | jq -r '.search_id')
    DOC_ID=$(printf '%s' "$RESPONSE" | jq -r '.results[0].doc_id')
    ```
  </Step>

  <Step title="Read">
    ```bash theme={"system"}
    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](/concepts/documents).
  </Step>

  <Step title="Optional feedback">
    ```bash theme={"system"}
    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}'
    ```

    <Check>
      Search and read are the main path. Feedback is available when your app or agent can tell which result was useful.
    </Check>
  </Step>
</Steps>

## Build with Caesar

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="/clients/sdks/python">
    `pip install caesar-search`
  </Card>

  <Card title="TypeScript SDK" icon="node-js" href="/clients/sdks/typescript">
    `npm install caesar-search`
  </Card>

  <Card title="AI SDK tools" icon="wand-magic-sparkles" href="/clients/sdks/ai-sdk">
    `caesarTools()` exposes `web_search` and `web_fetch`.
  </Card>

  <Card title="Framework recipes" icon="boxes" href="/clients/integrations/langchain">
    Wrap Caesar for framework tools, generic tool calling, and Agent Development Kit projects.
  </Card>
</CardGroup>

## Where next

* [Install for agents](/agents/install) - per-client install blocks.
* [How search works](/concepts/how-search-works) - coverage, freshness, ranking, and provenance.
* [Search](/concepts/search) - filters and ranking behavior.
* [Documents](/concepts/documents) - content selection, truncation, and continuation reads.
* [Pricing](/pricing), [authentication](/authentication), and [rate limits](/rate-limits) - credits, API keys, and request ceilings.