---
title: "Search API: retrieval without generation | Calypso Context"
canonical_url: "https://www.calypso.so/es/context/search"
last_updated: "2026-09-18T05:10:44.327Z"
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"
---
Consigue tu API key
**Calypso Context · Búsqueda**
# Solo recuperación, cuando la generación la haces tú.
POST /v1/search ejecuta la misma canalización de recuperación que alimenta las respuestas con fuentes, con el mismo alcance de agente y los mismos almacenes de buckets, y devuelve la evidencia en sí: pasajes ordenados con sus atributos de fuente. No se sintetiza ninguna respuesta.
[**Leer la documentación de la Search API**](https://docs.calypso.so/context/search) [**Prueba gratis 14 días**](https://context.calypso.so/join)
## **Tu propio modelo razona**
Un agente que reúne evidencia de tu conocimiento y sintetiza con su propio modelo y prompt.
## **Una interfaz de fuentes relacionadas**
Búsqueda semántica sobre tus buckets: una barra lateral de pasajes, un panel de documentos relacionados, un selector de citas.
## **Evalúa la recuperación primero**
Mira qué encontraría la recuperación antes de pedir una respuesta. Ajusta buckets y consultas contra resultados reales.
**El ejemplo**
## Una consulta entra. Evidencia ordenada sale.
Por defecto busca en el alcance del agente por defecto. Pasa buckets para buscar en almacenes concretos, o agent para usar el alcance de un agente con nombre. Nunca ambos.
**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.
```
**Parámetros**
## Seis campos. Dos son excluyentes.
Formula las consultas como preguntas naturales y no como palabras sueltas; la búsqueda semántica subyacente recupera notablemente mejor con preguntas.
| Parámetro | Por defecto | Qué hace |
| --- | --- | --- |
| **query** | obligatorio | La consulta, de 1 a 4000 caracteres. |
| **agent** | calypso-agent | Busca en el alcance de un agente concreto: el de por defecto o uno con nombre. Excluyente con buckets. |
| **buckets** | — | Busca directamente en buckets concretos, por id o slug, hasta 5. Excluyente con agent. |
| **max_results** | 10 | De 1 a 20. La recuperación siempre busca en un conjunto de candidatos mayor, al menos 10 y hasta el doble del valor, antes de truncar. |
| **depth** | fast | fast ejecuta una única llamada acotada. standard ejecuta de 2 a 3 en paralelo y las fusiona por mejor posición sin duplicados, lo que eleva la cobertura en consultas cortas con la misma latencia. |
| **additional_queries** | — | Hasta 2 reformulaciones extra buscadas en paralelo con depth standard. Las aportas tú; no se gasta ninguna llamada a modelo en generarlas. |
**El campo strategy**
## Sabe cómo se mapeó el alcance a los almacenes.
Cada respuesta dice cómo buscó. Un valor significa cobertura parcial y conviene manejarlo.
- **bucket_stores**
- Buscó en los almacenes de buckets del alcance. El caso normal.
- **bucket_stores_degraded**
- Al menos un bucket no pudo leerse y se descartó. Trata los resultados como parciales.
- **explicit_selected_files**
- La política del agente nombra fuentes explícitas en lugar de buckets.
- **all_team_files**
- El agente busca en todos los archivos recuperables del espacio de trabajo.
- **scope_disabled · scope_empty**
- Nada que buscar. Los resultados están vacíos por diseño, no por fallo.
**Cómo funciona**
## Alcance, consulta, razonamiento.
1. 01 ### **Elige el alcance**
Agente por defecto, un agente con nombre o hasta cinco buckets por slug. Las mismas reglas que una respuesta con fuentes.
2. 02 ### **Pregunta como pregunta**
Envía una consulta en lenguaje natural; añade dos reformulaciones y depth standard cuando la cobertura importe más que los tokens.
3. 03 ### **Razona sobre los pasajes**
Pasa results[].text a tu propio modelo o interfaz. Cada resultado lleva el mismo source_index y label que llevaría una cita.
**De la documentación**
## El contrato en una tabla.
| **Endpoint** | POST https://api.calypso.so/v1/search |
| --- | --- |
| **Alcance** | agent (por defecto o con nombre) o buckets (ids o slugs, hasta 5), nunca ambos |
| **Resultados** | De 1 a 20, ordenados; source_index es estable y empieza en 1 |
| **Profundidad** | fast: una llamada; standard: de 2 a 3 búsquedas paralelas fusionadas por mejor posición |
| **Contrato de fuentes** | Los mismos atributos que file_search_call.results[] de una respuesta: label, page_number, locator_label, source_type, knowledge_id |
| **Cobro** | Una búsqueda servida se mide como una respuesta servida; un espacio sin cuota recibe 429 |
| **Herramienta MCP** | calypso-search |
**Preguntas y respuestas**
## Antes de tu primera búsqueda.
**Sigue leyendo**
[**Fuentes **
PDFs, imágenes, páginas y datos. Qué lee y cómo entra.](https://www.calypso.so/context/sources) [**Buckets **
Memoria de fuentes acotada y duradera. Provisiona por slug, vincula a agentes.](https://www.calypso.so/context/buckets) [**Agentes **
Uno por defecto y los agentes con nombre que quieras, cada uno con su alcance y política.](https://www.calypso.so/context/agents) [**Citas **
Una fuente en cada respuesta: anotaciones por posición, lista estructurada de fuentes, modo nativo.](https://www.calypso.so/context/citations) [**Privacidad **
Tuyo, aislado: sin entrenar con tus datos, exporta o borra cuando quieras, claves con permisos explícitos.](https://www.calypso.so/context/privacy) [**Search API en la documentación **
La referencia desde la que está escrita esta página, con cada endpoint y campo.](https://docs.calypso.so/context/search)
**Empieza hoy**
## **Busca en el conocimiento que buscan tus agentes.**
Misma recuperación, mismo alcance, mismo contrato de fuentes, sin la respuesta generada.
[**Prueba gratis 14 días**](https://context.calypso.so/join) [**Leer la documentación para desarrolladores**](https://docs.calypso.so/context/search)