Thalius Thalius
En esta páginaRecursos para IA
  1. Recursos para IA
  2. El token de un usuario con sesión iniciada
  3. Qué cubre la API
  4. La forma de una petición
  5. Endpoints
  6. Importa documentos
  7. POST /ingest
  8. GET /jobs/{job_id}
  9. Busca y pregunta
  10. POST /search
  11. POST /ask
  12. Las carpetas y lo que contienen
  13. GET /folders/summary
  14. GET /folders
  15. GET /folders/{id}
  16. GET /documents
  17. Lee documentos
  18. GET /documents/{id}
  19. POST /documents/batch
  20. GET /documents/{id}/content
  21. GET /documents/{id}/tags
  22. Cuando una llamada falla
  23. ¿Quieres acceso anticipado a la API?

Referencia de la API

Todos los endpoints públicos, en un solo lugar

Los endpoints que usa la aplicación web de Hippocampus para importar, buscar, responder y leer, con sus campos, streaming, trabajos y errores.

Beta: los campos aún pueden cambiar antes de la disponibilidad general.

Acceso a la APIVer un ejemplo

Recursos para IA

  • Agente de código

    Tu agente de programación (Claude, Cursor, Codex u otro) lee nuestro archivo de skill y configura Hippocampus en tu proyecto por sí solo.

  • Clientes de API

    Tu cliente de API (Postman, Insomnia o Bruno) importa todas las peticiones con respuestas de ejemplo; ejecuta primero Sign in y el token se configura solo.

  • OpenAPI 3.1

    Los generadores de clientes, Swagger UI y otras herramientas de API leen todos los endpoints de este archivo, en el formato estándar.

  • Asistentes de chat

    Tu asistente de chat (ChatGPT, Claude o Gemini) responde preguntas sobre la API a partir de nuestra documentación, toda en un solo archivo.

Autenticación

El token de un usuario con sesión iniciada

Cada petición lleva una cabecera Authorization: Bearer <token>. El token es el ID token de un usuario de Hippocampus con sesión iniciada y dura alrededor de una hora, así que un script lo renueva como lo hace cualquier inicio de sesión. Una llamada solo accede a lo que ese usuario puede leer.

No hay claves de API: hoy te conectas mediante MCP, que inicia tu sesión en el navegador (consulta la página de MCP). Mientras la API REST está en acceso anticipado, un script inicia sesión como su propio usuario, con las carpetas que necesita compartidas con él.

Alcance

Qué cubre la API

Búsqueda y respuestas — search devuelve los pasajes que coinciden con una pregunta, con páginas y un enlace al original; ask devuelve una respuesta breve.

Documentos — importa una fuente y sigue cómo se ha dividido en secciones.

Explorar y leer — lista carpetas, lee el texto de un documento o descarga el original.

Trabajos — consulta el estado de una importación.

Errores — la forma de un fallo en cada servicio.

Ilustrativo

La forma de una petición

Un documento importado y una pregunta respondida a partir de lo importado. Los endpoints y los campos no son definitivos.

curl -X POST /ingest \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" \
  -F "[email protected]"

Solo ilustrativo: todavía no es un contrato en vigor.

Referencia

Endpoints

La API tiene dos servicios y ambos aceptan el mismo token. El core importa, busca y responde; el vault guarda carpetas y documentos. El core y el vault que sirven a tu espacio de trabajo dependen de su canal de publicación. Los ejemplos siguientes usan https://hippocampuscore.thalius.ai para el core y https://hippocampusvault.thalius.ai para el vault; si una llamada responde 409 con code: wrong_channel, a tu espacio de trabajo lo sirve otro canal, y el core_url de la respuesta indica el core al que enviarla.

Cada endpoint de abajo tiene una petición en cURL, Python y JavaScript y una respuesta recortada.

Los ids de los ejemplos están abreviados.

Importar

Importa documentos

Sube archivos al core. Cada archivo se lee, se divide en secciones y se resume, y después se archiva en la carpeta que indiques. Un trabajo hace el seguimiento.

Core

POST /ingest

Sube uno o varios archivos para importarlos a una carpeta.

Query

  • stream — true transmite el progreso como eventos enviados por el servidor; false (predeterminado) devuelve un trabajo de inmediato.

Campos del formulario (multipart)

  • files — uno o varios archivos: .pdf, .docx, .pptx, .xlsx, .md, .markdown, .txt, .text. Obligatorio.
  • file_metadata — array JSON con un objeto por archivo, en el mismo orden: folder_name (ruta de la carpeta) y tags.

Devuelve un trabajo: job_id, status (processing, complete o error), total_files, done. Un archivo ya importado vuelve con duplicate: true.

curl -sS -X POST "https://hippocampuscore.thalius.ai/ingest" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" \
  -F "[email protected]" \
  -F 'file_metadata=[{"folder_name":"contracts/master-agreements","tags":["msa"]}]'
{
  "job_id": "c0a9f6d2-…",
  "status": "processing",
  "message": "Queued 1 file",
  "total_files": 1,
  "done": false
}

Core

GET /jobs/{job_id}

Consulta una importación iniciada sin streaming. Sondea hasta que done sea true.

Ruta

  • job_id — de la respuesta de POST /ingest.

Devuelve status, successful, failed y una entrada en results por archivo, con su document_id.

curl -sS "https://hippocampuscore.thalius.ai/jobs/c0a9f6d2-…" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
{
  "job_id": "c0a9f6d2-…",
  "status": "complete",
  "successful": 1,
  "failed": 0,
  "results": [
    {
      "filename": "MSA-2025.pdf",
      "success": true,
      "document_id": "8c1f0e4a-…",
      "folder_name": "contracts/master-agreements",
      "duplicate": false
    }
  ],
  "done": true
}

Búsqueda y respuestas

Busca y pregunta

Search devuelve los pasajes que coinciden con una pregunta, cada uno con sus páginas y un enlace al original. Ask devuelve una respuesta breve escrita por el modelo.

Core

POST /search

Encuentra los pasajes que responden a una pregunta, clasificados.

Cuerpo (JSON)

  • query — la pregunta. Obligatorio.
  • folder_name — limita la búsqueda a una ruta de carpeta.
  • tags — la limita a los documentos con estas etiquetas.

Devuelve sources: para cada pasaje, doc_id, document_title, leaf_title (la sección), start_page, end_page, text, score y deep_link al original en esa página.

curl -sS -X POST "https://hippocampuscore.thalius.ai/search" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"What is the notice period for termination?","folder_name":"contracts/master-agreements"}'
{
  "sources": [
    {
      "doc_id": "8c1f0e4a-…",
      "document_title": "Master Services Agreement 2025",
      "leaf_title": "12. Term and Termination",
      "start_page": 14,
      "end_page": 15,
      "score": 0.91,
      "text": "Either party may terminate this Agreement on ninety (90) days' written notice…",
      "deep_link": "/documents/5b7d2c90-….pdf#page=14"
    }
  ]
}

Core

POST /ask

Obtén una respuesta breve a una pregunta, redactada a partir de los pasajes que coinciden.

Cuerpo (JSON)

  • query — la pregunta. Obligatorio.
  • folder_name, tags — como en search.

Devuelve answer, reasoning y confidence. Los pasajes no se devuelven; llama a search para obtenerlos.

curl -sS -X POST "https://hippocampuscore.thalius.ai/ask" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"What is the notice period for termination?","folder_name":"contracts/master-agreements"}'
{
  "answer": "Either party may terminate on 90 days' written notice (section 12.2).",
  "reasoning": "Section 12.2 of the Master Services Agreement states…",
  "confidence": 0.86
}

Explorar

Las carpetas y lo que contienen

Los resúmenes de carpeta vienen del core; las carpetas y las listas de documentos vienen del vault.

Core

GET /folders/summary

Lee lo que contiene una carpeta, tal como se escribió en la importación, sin ejecutar una búsqueda.

Query

  • folder_name — la ruta de la carpeta. Obligatorio.

Devuelve status (ok, none o unavailable) y folder_summary con title, description y content.

curl -sS "https://hippocampuscore.thalius.ai/folders/summary?folder_name=contracts/master-agreements" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
{
  "status": "ok",
  "folder_summary": {
    "folder": "contracts/master-agreements",
    "title": "Master agreements",
    "description": "Signed MSAs with customers and suppliers, 2019–2025.",
    "content": "- Master Services Agreement 2025: term, termination, liability caps…",
    "truncated": false
  }
}

Vault

GET /folders

Lista las carpetas de nivel superior, o las carpetas dentro de una carpeta.

Query

  • parentFolderId — la carpeta que se lista. Omítelo para el nivel superior.

Devuelve un array de carpetas: id, name, parentFolderId, createdAt, updatedAt.

curl -sS "https://hippocampusvault.thalius.ai/folders?parentFolderId=0c25a285-…" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
[
  {
    "id": "0144f7ed-…",
    "name": "Onboarding notes",
    "parentFolderId": "0c25a285-…",
    "createdAt": "2026-09-08T09:15:16.000Z",
    "updatedAt": "2026-09-08T09:15:16.000Z"
  }
]

Vault

GET /folders/{id}

Una carpeta. Con include=true la misma llamada devuelve también las carpetas superiores, sus documentos y sus subcarpetas.

Ruta

  • id — el id de la carpeta.

Query

  • include — true para añadir ancestors, documents y subfolders.
curl -sS "https://hippocampusvault.thalius.ai/folders/0144f7ed-…?include=true" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
{
  "id": "0144f7ed-…",
  "name": "Onboarding notes",
  "parentFolderId": "0c25a285-…",
  "ancestors": [
    {
      "id": "0c25a285-…",
      "name": "HR"
    }
  ],
  "documents": [
    {
      "id": "3c76ff09-…",
      "name": "comments.md",
      "contentType": "text/markdown",
      "folderId": "0144f7ed-…",
      "version": 1
    }
  ],
  "subfolders": [
    {
      "id": "9e2a…",
      "name": "_hippocampus"
    }
  ]
}

Vault

GET /documents

Lista los documentos de una carpeta, sin su contenido.

Query

  • folderId — la carpeta. Omítelo para el nivel superior.
  • tag — solo los documentos con esta etiqueta.

Devuelve un array: id, name, contentType, folderId, version, createdAt, updatedAt.

curl -sS "https://hippocampusvault.thalius.ai/documents?folderId=0144f7ed-…" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
[
  {
    "id": "0001b85f-…",
    "name": "Onboarding notes.md",
    "contentType": "text/markdown",
    "folderId": "0144f7ed-…",
    "version": 1,
    "createdAt": "2026-09-08T09:15:17.000Z"
  }
]

Leer

Lee documentos

El vault devuelve el texto de un documento, sus etiquetas y el archivo original.

Vault

GET /documents/{id}

Los detalles de un documento. Un documento de texto también lleva su content en Markdown.

Ruta

  • id — el id del documento.

Devuelve id, name, contentType, size, version, folderId, createdAt y, para texto, content.

curl -sS "https://hippocampusvault.thalius.ai/documents/0001b85f-…" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
{
  "id": "0001b85f-…",
  "name": "Onboarding notes.md",
  "contentType": "text/markdown",
  "size": 510,
  "version": 1,
  "folderId": "d3f3ed56-…",
  "createdAt": "2026-09-08T09:15:17.000Z",
  "content": "---
type: document
title: Onboarding notes
---
…"
}

Vault

POST /documents/batch

Hasta 100 documentos, con contenido, en una sola llamada.

Cuerpo (JSON)

  • ids — hasta 100 ids de documento. Obligatorio.

Devuelve un array de documentos. Los ids que no existen o que no puedes leer se omiten.

curl -sS -X POST "https://hippocampusvault.thalius.ai/documents/batch" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids":["0001b85f-…","3c76ff09-…"]}'
[
  {
    "id": "0001b85f-…",
    "name": "Onboarding notes.md",
    "contentType": "text/markdown",
    "content": "---
type: document
…"
  },
  {
    "id": "3c76ff09-…",
    "name": "comments.md",
    "contentType": "text/markdown",
    "content": "…"
  }
]

Vault

GET /documents/{id}/content

El archivo almacenado en sí: el PDF original, una imagen o Markdown, con su propio tipo de contenido.

Ruta

  • id — el id del documento, por ejemplo el del deep_link de un resultado de búsqueda.
curl -sS -o original.pdf "https://hippocampusvault.thalius.ai/documents/5b7d2c90-…/content" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"

Vault

GET /documents/{id}/tags

Las etiquetas de un documento.

Ruta

  • id — el id del documento.

Devuelve tags.

curl -sS "https://hippocampusvault.thalius.ai/documents/0001b85f-…/tags" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
{
  "tags": [
    "onboarding",
    "hr"
  ]
}

Errores

Cuando una llamada falla

El core responde con detail. El vault responde con message, o con error cuando el token falta o no es válido.

  • 401 — el token falta, ha caducado o no es válido. Inicia sesión de nuevo.
  • 403 — el usuario no puede leer ni modificar esa carpeta.
  • 404 — no se encuentra, o este usuario no puede leerlo.
  • 409 — el documento cambió desde que lo leíste.
  • 422 — falta un campo o tiene un tipo incorrecto.
{
  "detail": "Not authenticated"
}

Clientes

Por ahora

curl y nuestro servidor MCP funcionan hoy. Los SDK oficiales de Python y TypeScript están previstos antes de la disponibilidad general.

MCPEspacio de trabajo

¿Quieres acceso anticipado a la API?

Estamos incorporando ahora a los primeros clientes colaboradores (design partners).

Acceso a la API