Knowledge API

Añade knowledge a tus minds mediante tres métodos: archivo, palabra clave o link. El knowledge se procesa, se convierte en embeddings y se recupera automáticamente durante las conversaciones.

Nota: listar, añadir y eliminar están disponibles vía la API v1. El enriquecimiento de knowledge por búsqueda de palabras clave también está soportado a través del mismo endpoint de añadir.

Las respuestas de lista y estado de Knowledge son privadas (Cache-Control: private, no-store). GET /api/v1/minds/{mindId}/knowledge/{itemId}/status devuelve los identificadores autorizados mindId e itemId, campos públicos de procesamiento, recuentos de embeddings y patrones, y readyForRetrieval. Se omiten los diagnósticos del worker y los metadatos arbitrarios; los fallos usan el mensaje genérico Knowledge processing failed. Los estados almacenados inválidos pasan a unknown. En elementos antiguos sin metadatos de procesamiento, los embeddings existentes implican completed; en otro caso, unknown. Las credenciales ausentes o bloqueadas devuelven 401, los Minds o elementos inaccesibles 404 y los fallos inesperados de almacenamiento un 500 genérico.

Listar elementos de knowledge

Recupera una página de elementos de conocimiento de un Mind.

Usa limit (1–100, por defecto 100) y offset (entero no negativo, por defecto 0). Los elementos se ordenan por createdAt descendente y después por ID descendente. data.total cuenta todos los elementos; data.pagination contiene limit, offset y hasMore. Mientras hasMore sea verdadero, solicita la siguiente página con offset + items.length. Las páginas no son una instantánea: las altas o eliminaciones entre solicitudes pueden desplazar los resultados. Los valores de paginación no válidos o repetidos devuelven 400.

Endpoint: GET /api/v1/minds/{mindId}/knowledge

Headers:

Authorization: Bearer minds_your_api_key

Ejemplo:

curl -X GET "https://getminds.ai/api/v1/minds/{mindId}/knowledge?limit=100&offset=0" \
  -H "Authorization: Bearer minds_your_api_key"

Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "description": "Company Employee Handbook 2025",
        "link": null,
        "filePath": "portfolio/user-id/1234567890_handbook.pdf",
        "isWatched": false,
        "createdAt": "2025-12-10T12:00:00.000Z",
        "updatedAt": "2025-12-10T12:00:00.000Z"
      }
    ],
    "total": 1,
    "pagination": { "limit": 100, "offset": 0, "hasMore": false }
  }
}

Subida de archivos

Sube documentos o imágenes directamente a un mind.

Endpoint: POST /api/v1/minds/{mindId}/knowledge

Content-Type: multipart/form-data

Formatos soportados:

• Documentos: PDF, DOCX, DOC, TXT, MD, RTF, CSV, JSON, XML
• Imágenes: JPG, JPEG, PNG, GIF, WEBP

Ejemplo:

curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -F "file=@./handbook.pdf" \
  -F "description=Company Employee Handbook 2025"

El acceso a una URL de archivo del espacio de trabajo es independiente del permiso para editar el Mind: usa un archivo propio, una URL de archivo de chat con firma válida o un archivo de contexto compartido mediante la Study de quien lo subió. De lo contrario, la solicitud devuelve 403 Upload access denied. Conocer la ruta del objeto no concede acceso.

Response: 201 Created

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "description": "Company Employee Handbook 2025",
    "filePath": "portfolio/user-id/1234567890_handbook.pdf",
    "createdAt": "2025-12-10T12:00:00.000Z"
  }
}

Búsqueda por palabras clave

Añade knowledge buscando palabras clave en la web. Busca en Exa y YouTube, extrae el contenido y lo añade al knowledge base del mind.

Endpoint: POST /api/v1/minds/{mindId}/knowledge

Content-Type: application/json

Envía un body JSON con un array keywords (en lugar de link/file) para disparar el enriquecimiento por web search.

Ejemplo:

curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["solar panel efficiency", "photovoltaic trends"]}'

Response: 202 Accepted

{
  "success": true,
  "data": {
    "sparkId": "660e8400-e29b-41d4-a716-446655440000",
    "keywords": ["solar panel efficiency", "photovoltaic trends"],
    "queued": true,
    "regeneratePrompt": true,
    "message": "Knowledge enrichment queued with 2 keyword(s)."
  }
}

Nota: esto es asíncrono. El procesamiento se ejecuta en segundo plano y puede tardar varios minutos.

Link

Añade knowledge desde una URL. Soporta páginas web, videos de YouTube y papers de investigación.

Endpoint: POST /api/v1/minds/{mindId}/knowledge

Content-Type: application/json

Ejemplo:

curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"link": "https://example.com/article", "description": "Industry trends article"}'

Response: 201 Created

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "link": "https://example.com/article",
    "description": "Industry trends article",
    "createdAt": "2025-12-10T12:00:00.000Z"
  }
}

Tipos de link soportados:

• Páginas web (contenido extraído mediante scraping)
• Videos de YouTube (transcripciones extraídas automáticamente)
• Papers de investigación (arxiv, etc.)

Watch (auto-update)

Los elementos de knowledge basados en link pueden "watchearse" para comprobar automáticamente actualizaciones de contenido en un ciclo semanal. Cuando se detectan cambios, el knowledge se reprocesa y se vuelve a embedder.

Watch se gestiona desde la UI del producto. El estado de watch es visible al listar elementos de knowledge vía la API (campo isWatched).

Nota: watch solo está disponible para knowledge basado en link, no para archivos ni búsquedas por palabras clave.

Actualizar elemento de knowledge

Actualiza la descripción de un elemento de knowledge existente.

Endpoint: PUT /api/v1/minds/{mindId}/knowledge/{itemId}

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body:

{
  "description": "Updated description for this knowledge item"
}

Ejemplo:

curl -X PUT "https://getminds.ai/api/v1/minds/{mindId}/knowledge/{itemId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated handbook description"}'

Response:

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "description": "Updated handbook description",
    "link": null,
    "filePath": "portfolio/user-id/1234567890_handbook.pdf",
    "isWatched": false,
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-15T08:30:00.000Z"
  }
}

Respuestas de error

400 Bad Request - No hay campos válidos para actualizar o descripción vacía

401 Unauthorized - API key no válida o ausente

404 Not Found - Elemento de knowledge o mind no encontrado

Enriquecer vía palabras clave (conveniencia)

Alias de conveniencia para el enriquecimiento de knowledge basado en palabras clave.

Endpoint: POST /api/v1/minds/{mindId}/knowledge/enrich

Esto es equivalente a POST /api/v1/minds/{mindId}/knowledge con un body de keywords. Consulta Búsqueda por palabras clave para todos los detalles.

Ejemplo:

curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge/enrich" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["solar panel efficiency", "photovoltaic trends"]}'

Eliminar elemento de knowledge

Elimina permanentemente un elemento de knowledge y todos los datos asociados (embeddings, patterns, archivos).

Endpoint: DELETE /api/v1/minds/{mindId}/knowledge/{itemId}

Headers:

Authorization: Bearer minds_your_api_key

Ejemplo:

curl -X DELETE "https://getminds.ai/api/v1/minds/{mindId}/knowledge/{itemId}" \
  -H "Authorization: Bearer minds_your_api_key"

Response: 204 No Content (body vacío en caso de éxito)

Qué se elimina

• El registro del elemento de knowledge
• Todos los vector embeddings asociados
• Todos los patterns asociados
• El archivo subido al storage (si es basado en archivo)

Advertencia: esta acción no se puede deshacer.

Cómo funciona el procesamiento

1. Upload - El contenido se almacena y la API devuelve éxito
2. Extracción - El procesamiento en background extrae el texto (scraping, transcripciones, OCR, visión)
3. Embedding - El contenido se convierte a vector embeddings
4. Recuperación - Durante el chat, el knowledge relevante se recupera automáticamente por búsqueda semántica

Errores

Siguientes pasos

• Chatea con tu mind
• Crea minds
• Errores y límites de la API