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.

Listar elementos de knowledge

Recupera todos los elementos de knowledge de un mind.

Endpoint: GET /api/v1/sparks/{sparkId}/knowledge

Headers:

Authorization: Bearer minds_your_api_key

Ejemplo:

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}/knowledge" \
  -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
  }
}

Subida de archivos

Sube documentos o imágenes directamente a un mind.

Endpoint: POST /api/v1/sparks/{sparkId}/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/sparks/{sparkId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -F "file=@./handbook.pdf" \
  -F "description=Company Employee Handbook 2025"

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/sparks/{sparkId}/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/sparks/{sparkId}/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/sparks/{sparkId}/knowledge

Content-Type: application/json

Ejemplo:

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/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/sparks/{sparkId}/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/sparks/{sparkId}/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/sparks/{sparkId}/knowledge/enrich

Esto es equivalente a POST /api/v1/sparks/{sparkId}/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/sparks/{sparkId}/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/sparks/{sparkId}/knowledge/{itemId}

Headers:

Authorization: Bearer minds_your_api_key

Ejemplo:

curl -X DELETE "https://getminds.ai/api/v1/sparks/{sparkId}/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