Calypso Calypso

Elephant · Fuentes

PDF, capturas, páginas y notas. Leídos, no solo guardados.

Guarda un PDF y Elephant lee su texto y sus páginas, así que tablas, gráficos y escaneos cuentan. Las capturas se leen por lo que muestran y las páginas web quedan como fuentes vivas. Si un archivo no se puede leer, te enteras al guardarlo, no al preguntar.

El ejemplo

Una llamada para entrar. Un bit que esperar.

Sube un archivo con una petición multipart, o pásale una URL a Elephant. 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.

FamiliaTiposModalidadLa cita apunta a
PDF.pdfMultimodal: texto e imágenes de páginaLa página
Imágenes.png .jpg .jpegImagen, leída por su contenido, no por el nombreLa imagen
Documentos.docxTextoEl documento
Texto.md .txt y otros text/*TextoEl documento
Datos.csv .jsonTextoEl documento
Código.py .ts .tsx .js .jsx .java .go .rs .sql .html .css .scss .yml .yaml .toml .ini .env .shTextoEl 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 Elephant, y son promesas diferentes.

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.

Añadir una página web

Estás pidiendo
Haz que Elephant conozca esta página.
Endpoint
POST /v1/buckets//pages
Identidad
La URL normalizada es la identidad: una por cuenta.
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.

  1. 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.

  2. 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.

  3. 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. 1 / 4

    Aceptado

    Los bytes están guardados y la petición es duradera. Un 202 aquí no es disponibilidad de recuperación.

  2. 2 / 4

    Indexado

    La fuente se ha leído según su modalidad: texto extraído, páginas renderizadas, imágenes descritas.

  3. 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 / 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 archivo25 MB
Archivos por loteDe 1 a 100, sesiones directas a almacenamiento, una sola finalización
Límite de tasa5 solicitudes de creación por segundo por cuenta
Metadatos8 KB por fuente, hasta 20 etiquetas
Comprobación de disponibilidadGET /v1/sources/{id} → ready: true
Identidad de una página webLa URL normalizada, una por cuenta; un duplicado devuelve 409 con el id de la fuente existente
ExcelNo se acepta. Exporta a CSV primero.

Preguntas y respuestas

Antes de subir.

Sigue leyendo

Empieza hoy

Guarda tu primer PDF hoy.

Adjúntalo en ChatGPT o Claude, o súbelo en la consola, y haz una pregunta que cite la página.