---
title: "Search your PDFs and notes for the exact passage | Elephant"
canonical_url: "https://www.calypso.so/elephant/search"
last_updated: 2026-11-21
meta:
  description: "Search every file you saved and get the matching passages with file and page, no written answer. In ChatGPT and Claude, or with POST /v1/search."
  keywords: "search inside PDFs with AI, semantic search for notes, find a passage in documents, RAG search API, retrieval API"
  "og:description": "Search every file you saved and get the matching passages with file and page, no written answer. In ChatGPT and Claude, or with POST /v1/search."
  "og:title": "Search your PDFs and notes for the exact passage | Elephant"
  "twitter:description": "Search every file you saved and get the matching passages with file and page, no written answer. In ChatGPT and Claude, or with POST /v1/search."
  "twitter:title": "Search your PDFs and notes for the exact passage | Elephant"
---

Connect your AI

**Elephant · Search**

# The exact passage, not a summary.

Sometimes you want the evidence, not an answer. Search returns the passages that match, ranked, with file and page, from the same buckets an answer would read. Ask for it in ChatGPT or Claude, or call POST /v1/search from your own code.

[**Read the Search API docs**](https://docs.calypso.so/context/search) [**Start 14-day free trial**](https://elephant.calypso.so/join?targetAppKey=elephant)

## **Your own model does the reasoning**

An agent that gathers evidence from your knowledge and synthesizes with its own model and prompt.

## **A related-sources UI**

Semantic search over your buckets: a sidebar of passages, a related-documents panel, a citation picker.

## **Evaluate retrieval first**

See what retrieval would find before asking for an answer. Tune buckets and queries against real results.

**The example**

## One query in. Ranked evidence out.

The default searches the default agent’s scope. Pass buckets to search specific stores, or agent to use a named agent’s scope. Never both.

**CALYPSO_API_KEY**

```
curl -X POST "https://api.calypso.so/v1/search" \
  -H "Authorization: Bearer $CALYPSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the refund policy for international orders?"
  }'

# Searches the default agent's scope: the same buckets elephant-agent answers from.
```

**Parameters**

## Six fields. Two are mutually exclusive.

Phrase queries as natural questions rather than bare keywords; the underlying semantic search retrieves noticeably better on questions.

| Parameter | Default | What it does |
| --- | --- | --- |
| **query** | required | The search query, 1 to 4000 characters. |
| **agent** | elephant-agent | Search a specific agent’s scope: the default or a named agent. Mutually exclusive with buckets. |
| **buckets** | — | Search specific buckets directly, ids or slugs, up to 5. Mutually exclusive with agent. |
| **max_results** | 10 | 1 to 20. Retrieval always searches a larger candidate pool, at least 10 and up to twice the value, before truncating. |
| **depth** | fast | fast runs one bounded retrieval call. standard runs 2 to 3 in parallel and merges by deduped best rank, raising recall on short queries at the same latency. |
| **additional_queries** | — | Up to 2 extra phrasings searched in parallel on depth standard. You supply them; no model call is spent generating them. |

**The strategy field**

## Know how the scope mapped to stores.

Every response says how it searched. One value means partial coverage and is worth handling.

<dl>

<dt>**bucket_stores**</dt>
<dd>Searched the bucket stores in scope. The normal case.</dd>

<dt>**bucket_stores_degraded**</dt>
<dd>At least one bucket could not be read and was dropped. Treat the results as partial.</dd>

<dt>**explicit_selected_files**</dt>
<dd>The agent’s policy names explicit sources instead of buckets.</dd>

<dt>**all_team_files**</dt>
<dd>The agent searches every retrievable file in your account.</dd>

<dt>**scope_disabled · scope_empty**</dt>
<dd>Nothing to search. The results are empty by design, not by failure.</dd></dl>

**How it works**

## Scope, query, reason.

1. 01 ### **Pick the scope**

   Default agent, a named agent, or up to five buckets by slug. The same rules as a grounded answer.
2. 02 ### **Ask as a question**

   Send a natural-language query; add two rephrasings and depth standard when recall matters more than tokens.
3. 03 ### **Reason on the passages**

   Feed results[].text into your own model or UI. Each result carries the same source_index and label a citation would.

**From the docs**

## The contract in one table.

| **Endpoint** | POST https://api.calypso.so/v1/search |
| --- | --- |
| **Scope** | agent (default or named) or buckets (ids or slugs, up to 5), never both |
| **Results** | 1 to 20, ranked; source_index is stable and 1-based |
| **Depth** | fast: one call; standard: 2 to 3 parallel searches merged by best rank |
| **Source contract** | The same attributes as an answer’s file_search_call.results[]: label, page_number, locator_label, source_type, knowledge_id |
| **Billing** | A served search is metered like a served answer; an account over its quota receives 429 |
| **MCP tool** | calypso-search |

**Questions and answers**

## Before your first search.

**Keep reading**

[<h3>**Sources **</h3>PDFs, screenshots, pages and notes. What it reads and how you save it.](https://www.calypso.so/elephant/sources) [<h3>**Buckets **</h3>Folders your AI remembers. Ask one, or all of them.](https://www.calypso.so/elephant/buckets) [<h3>**Agents **</h3>Named assistants with their own buckets and instructions.](https://www.calypso.so/elephant/agents) [<h3>**Citations **</h3>A source on every answer: file, page and passage, with a link to open it.](https://www.calypso.so/elephant/citations) [<h3>**Privacy **</h3>Private by default: no training on your files, never deletes, you choose what each AI may do.](https://www.calypso.so/elephant/privacy) [<h3>**Search API in the docs **</h3>The reference this page is written from, with every endpoint and field.](https://docs.calypso.so/context/search)

**Start today**

## **Find the line you half remember.**

Same retrieval, same buckets, same sources, without the written answer.

[**Start 14-day free trial**](https://elephant.calypso.so/join?targetAppKey=elephant) [**Read the docs**](https://docs.calypso.so/context/search)