Importar un archivo por URL
- Estás pidiendo
- Copia este documento exacto.
- Endpoint
- POST /v1/buckets//files/import
- Identidad
- Cada importación crea una fuente nueva.
- Ciclo de vida
- Una instantánea, congelada al importar.
Calypso Context · Fuentes
PDFs, imágenes, páginas y datos. Leídos, no solo guardados.
Una fuente se acepta si Calypso puede leerla y se rechaza al subirla si no. Los PDFs se leen como texto y como imágenes de página, las imágenes por lo que muestran y las páginas web como fuentes vivas. Cada fuente cae en un bucket y reporta un único bit de listo cuando ya se puede buscar.
El ejemplo
Una llamada para entrar. Un bit que esperar.
Sube un archivo con una petición multipart, o pásale una URL a Calypso. En ambos casos el resultado es una fuente en un bucket, y ready te dice cuándo un agente puede citarla.
CALYPSO_API_KEY
curl -X POST "https://api.calypso.so/v1/buckets/support-handbook/files" \
-H "Authorization: Bearer $CALYPSO_API_KEY" \
-H "Idempotency-Key: crm-doc-123" \
-F "file=@refund_policy_2026.pdf" \
-F "title=Refund policy 2026" \
-F "tags=policy,returns"
# 202 → { "id": "src_…", "ready": false, "status": "queued", … }Qué lee
Los tipos aceptados y a qué apunta cada cita.
La modalidad decide cómo se lee una fuente. A dónde apunta la cita decide qué pueden comprobar tus usuarios.
| Familia | Tipos | Modalidad | La cita apunta a |
|---|---|---|---|
| Multimodal: texto e imágenes de página | La página | ||
| Imágenes | .png .jpg .jpeg | Imagen, leída por su contenido, no por el nombre | La imagen |
| Documentos | .docx | Texto | El documento |
| Texto | .md .txt y otros text/* | Texto | El documento |
| Datos | .csv .json | Texto | El documento |
| Código | .py .ts .tsx .js .jsx .java .go .rs .sql .html .css .scss .yml .yaml .toml .ini .env .sh | Texto | El documento |
El PDF es el único tipo de documento que se lee de forma visual además de textual, y por eso es el único que puede citar una página concreta. Los archivos de Excel no se aceptan: exporta la hoja a CSV antes de subirla.
Una URL
Dos puertas, una decisión.
Tienes una URL. Hay dos cosas distintas que puedes estar pidiéndole a Calypso, y son promesas diferentes.
Añadir una página web
- Estás pidiendo
- Haz que Calypso conozca esta página.
- Endpoint
- POST /v1/buckets//pages
- Identidad
- La URL normalizada es la identidad: una por equipo.
- Ciclo de vida
- Una fuente viva, rastreada y analizada.
Si eliges la puerta equivocada, la API te lo dice: una importación de archivo que recibe HTML devuelve url_is_web_page, y una ingesta de página que recibe un documento devuelve url_is_file. Ambos señalan la otra puerta; force: true lo anula.
Cómo funciona
Primero el bucket, luego enviar, luego esperar a ready.
- 01
Provisiona el bucket
PUT /v1/buckets/ es idempotente: crea el bucket o devuelve el que ya existe. Los scripts pueden llamarlo en cada ejecución.
- 02
Envía la fuente
Una llamada multipart para un archivo, una sesión directa a almacenamiento para lo grande, un cuerpo JSON para una URL o un lote de hasta 100 archivos.
- 03
Espera a ready
Finalizar significa aceptado de forma duradera, no buscable. Consulta GET /v1/sources/ hasta que ready sea true y entonces prueba la recuperación.
Disponibilidad
Listo significa buscable, no solo subido.
Una subida aceptada aún no es una fuente que responda. El bit ready cubre el indexado y la sincronización con el bucket, así que es el único estado que una prueba necesita.
1 / 4
Aceptado
Los bytes están guardados y la petición es duradera. Un 202 aquí no es disponibilidad de recuperación.
2 / 4
Indexado
La fuente se ha leído según su modalidad: texto extraído, páginas renderizadas, imágenes descritas.
3 / 4
Bucket activo
El almacén del bucket que buscan los agentes ya tiene la fuente. bucket_sync_status muestra la escalera si la necesitas.
4 / 4
Listo
ready: true. Un agente vinculado a este bucket puede recuperar y citar la fuente.
De la documentación
Los números que importan.
| Tamaño máximo de archivo | 25 MB |
|---|---|
| Archivos por lote | De 1 a 100, sesiones directas a almacenamiento, una sola finalización |
| Límite de tasa | 5 peticiones de creación por segundo por equipo |
| Metadatos | 8 KB por fuente, hasta 20 etiquetas |
| Comprobación de disponibilidad | GET /v1/sources/{id} → ready: true |
| Identidad de una página web | La URL normalizada, una por equipo; un duplicado devuelve 409 con el id de la fuente existente |
| Excel | No se acepta. Exporta a CSV primero. |
Preguntas y respuestas
Antes de subir.
Sigue leyendo
Buckets
Memoria de fuentes acotada y duradera. Provisiona por slug, vincula a agentes.
Agentes
Uno por defecto y los agentes con nombre que quieras, cada uno con su alcance y política.
Citas
Una fuente en cada respuesta: anotaciones por posición, lista estructurada de fuentes, modo nativo.
Búsqueda
Recuperación sin generación: los pasajes que una respuesta citaría, ordenados.
Privacidad
Tuyo, aislado: sin entrenar con tus datos, exporta o borra cuando quieras, claves con permisos explícitos.
Ingesta en la documentación
La referencia desde la que está escrita esta página, con cada endpoint y campo.
Empieza hoy
Carga tu primer bucket hoy.
Crea una clave de API del proyecto, sube un PDF y haz una pregunta que cite la página.