Your own model does the reasoning
An agent that gathers evidence from your knowledge and synthesizes with its own model and prompt.
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.
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.
- 01
Pick the scope
Default agent, a named agent, or up to five buckets by slug. The same rules as a grounded answer.
- 02
Ask as a question
Send a natural-language query; add two rephrasings and depth standard when recall matters more than tokens.
- 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.
Buckets
Scoped, durable source memory. Provision by slug, bind to agents.
Agents
One default, any number of named agents with their own scope and policy.
Citations
A source on every answer: annotations by offset, a structured source list, native mode.
Privacy
Yours, isolated: no training on your data, export or delete any time, keys with explicit scopes.
Search API in the docs
The reference this page is written from, with every endpoint and field.
Start today
Search the knowledge your agents search.
Same retrieval, same scope, same source contract, without the generated answer.