---
title: "Knowledge API"
description: "Añade knowledge a tus minds mediante archivos, palabras clave o links."
---

# 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/minds/{mindId}/knowledge`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

**Ejemplo:**

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

**Response:**

```json
{
  "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
  }
}
```

<table>
<thead>
  <tr>
    <th>
      Campo
    </th>
    
    <th>
      Tipo
    </th>
    
    <th>
      Descripción
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        data.items
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Array de objetos de elemento de knowledge
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.total
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      Número total de elementos de knowledge de este mind
    </td>
  </tr>
</tbody>
</table>

---

## Subida de archivos

Sube documentos o imágenes directamente a un mind.

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

**Content-Type:** `multipart/form-data`

<table>
<thead>
  <tr>
    <th>
      Campo
    </th>
    
    <th>
      Tipo
    </th>
    
    <th>
      Requerido
    </th>
    
    <th>
      Descripción
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        file
      </code>
    </td>
    
    <td>
      file
    </td>
    
    <td>
      Sí
    </td>
    
    <td>
      Archivo a subir (máx. 50 MB)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Sí
    </td>
    
    <td>
      Descripción del contenido
    </td>
  </tr>
</tbody>
</table>

**Formatos soportados:**

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

**Ejemplo:**

```bash
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"
```

**Response:** `201 Created`

```json
{
  "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.

<table>
<thead>
  <tr>
    <th>
      Parámetro
    </th>
    
    <th>
      Tipo
    </th>
    
    <th>
      Requerido
    </th>
    
    <th>
      Descripción
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        keywords
      </code>
    </td>
    
    <td>
      string<span>
        
      </span>
    </td>
    
    <td>
      Sí
    </td>
    
    <td>
      Palabras clave a buscar (máx. 35)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        regeneratePrompt
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Regenerar el system prompt después (por defecto: true)
    </td>
  </tr>
</tbody>
</table>

**Ejemplo:**

```bash
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`

```json
{
  "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`

<table>
<thead>
  <tr>
    <th>
      Parámetro
    </th>
    
    <th>
      Tipo
    </th>
    
    <th>
      Requerido
    </th>
    
    <th>
      Descripción
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        link
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Sí
    </td>
    
    <td>
      URL al contenido web
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Sí
    </td>
    
    <td>
      Descripción del contenido
    </td>
  </tr>
</tbody>
</table>

**Ejemplo:**

```bash
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`

```json
{
  "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:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

**Request Body:**

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

<table>
<thead>
  <tr>
    <th>
      Parámetro
    </th>
    
    <th>
      Tipo
    </th>
    
    <th>
      Requerido
    </th>
    
    <th>
      Descripción
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Sí
    </td>
    
    <td>
      Descripción actualizada (no puede estar vacía)
    </td>
  </tr>
</tbody>
</table>

**Ejemplo:**

```bash
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:**

```json
{
  "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](#b%C3%BAsqueda-por-palabras-clave) para todos los detalles.

**Ejemplo:**

```bash
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:**

```text
Authorization: Bearer minds_your_api_key
```

**Ejemplo:**

```bash
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

<table>
<thead>
  <tr>
    <th>
      Código
    </th>
    
    <th>
      Mensaje
    </th>
    
    <th>
      Causa
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        Link and description are required
      </code>
    </td>
    
    <td>
      Faltan campos requeridos
    </td>
  </tr>
  
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        Keywords array is required
      </code>
    </td>
    
    <td>
      Palabras clave vacías o ausentes
    </td>
  </tr>
  
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        File too large
      </code>
    </td>
    
    <td>
      El archivo supera el límite de 50 MB
    </td>
  </tr>
  
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        Can only watch link-based knowledge
      </code>
    </td>
    
    <td>
      Se intentó watchear un archivo
    </td>
  </tr>
  
  <tr>
    <td>
      404
    </td>
    
    <td>
      <code>
        Mind not found or access denied
      </code>
    </td>
    
    <td>
      ID de Mind no válido o sin acceso
    </td>
  </tr>
  
  <tr>
    <td>
      415
    </td>
    
    <td>
      <code>
        Unsupported Content-Type
      </code>
    </td>
    
    <td>
      Header Content-Type incorrecto
    </td>
  </tr>
</tbody>
</table>

---

## Siguientes pasos

- [Chatea con tu mind](/docs/api/chat)
- [Crea minds](/docs/api/minds)
- [Errores y límites de la API](/docs/api/errors)