---
title: "Search API: retrieval without generation | Calypso Context"
canonical_url: "https://www.calypso.so/context/search"
last_updated: "2026-09-16T00:41:15.093Z"
meta:
description: "POST /v1/search runs the same retrieval that powers grounded answers and returns the evidence itself: ranked passages with source_index, label, and page, no synthesized answer. Same agent scope, same buckets, same source contract."
keywords: "RAG search API, retrieval API, semantic search API for agents, retrieval-only RAG, hybrid search API"
"og:description": "POST /v1/search runs the same retrieval that powers grounded answers and returns the evidence itself: ranked passages with source_index, label, and page, no synthesized answer. Same agent scope, same buckets, same source contract."
"og:title": "Search API: retrieval without generation | Calypso Context"
"twitter:description": "POST /v1/search runs the same retrieval that powers grounded answers and returns the evidence itself: ranked passages with source_index, label, and page, no synthesized answer. Same agent scope, same buckets, same source contract."
"twitter:title": "Search API: retrieval without generation | Calypso Context"
---
Calypso home
**Calypso Context · Search**
# Retrieval only, when you want to do the generating.
POST /v1/search runs the same retrieval pipeline that powers grounded answers, with the same agent scope and the same bucket stores, and returns the evidence itself: ranked passages with their source attributes. No answer is synthesized.
[**Read the Search API docs**](https://docs.calypso.so/context/search) [**Start 14-day free trial**](https://context.calypso.so/join)
## **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 calypso-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** | calypso-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.
- **bucket_stores**
- Searched the bucket stores in scope. The normal case.
- **bucket_stores_degraded**
- At least one bucket could not be read and was dropped. Treat the results as partial.
- **explicit_selected_files**
- The agent’s policy names explicit sources instead of buckets.
- **all_team_files**
- The agent searches every retrievable file in the workspace.
- **scope_disabled · scope_empty**
- Nothing to search. The results are empty by design, not by failure.
**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; a quota-exhausted workspace receives 429 |
| **MCP tool** | calypso-search |
**Questions and answers**
## Before your first search.
**Keep reading**
[**Sources **
PDFs, images, pages, and data. What it reads and how it gets in.](https://www.calypso.so/context/sources) [**Buckets **
Scoped, durable source memory. Provision by slug, bind to agents.](https://www.calypso.so/context/buckets) [**Agents **
One default, any number of named agents with their own scope and policy.](https://www.calypso.so/context/agents) [**Citations **
A source on every answer: annotations by offset, a structured source list, native mode.](https://www.calypso.so/context/citations) [**Privacy **
Yours, isolated: no training on your data, export or delete any time, keys with explicit scopes.](https://www.calypso.so/context/privacy) [**Search API in the docs **
The reference this page is written from, with every endpoint and field.](https://docs.calypso.so/context/search)
**Start today**
## **Search the knowledge your agents search.**
Same retrieval, same scope, same source contract, without the generated answer.
[**Start 14-day free trial**](https://context.calypso.so/join) [**Read the developer docs**](https://docs.calypso.so/context/search)