> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge Bases

> Sincroniza documentos desde un sistema externo en una Knowledge Base de Profound y busca en ella a través de la API

Esta guía muestra cómo sincronizar documentos desde un sistema externo, como Guru, en una knowledge base de Profound. Todos los ejemplos requieren autenticación con una clave de API.

<Note>
  Las knowledge bases deben crearse en la app de Profound. La API no puede crear una knowledge base. Reemplaza `your_api_key`, `your_knowledge_base_id` y `your_organization_id` con tus valores reales.
</Note>

## Guía paso a paso para sincronizar documentos

Usa este flujo para replicar documentos y carpetas de un sistema externo:

1. Usa [**List Knowledge Bases**](/api-reference/knowledge-bases/list-knowledge-bases) para encontrar el ID de la knowledge base.
2. Usa [**Add Folder**](/api-reference/knowledge-bases/add-folder) para replicar las carpetas de origen cuando sea necesario.
3. Usa [**Add Document**](/api-reference/knowledge-bases/add-document) para subir cada documento de origen.
4. Usa [**Update Document**](/api-reference/knowledge-bases/update-document) para resincronizaciones idempotentes.
5. Usa [**Delete Document**](/api-reference/knowledge-bases/delete-document) o [**Delete Folder**](/api-reference/knowledge-bases/delete-folder) cuando se elimine contenido del sistema de origen.

### 1. Listar las knowledge bases

Primero, obtén el ID de la knowledge base que quieres sincronizar. El `id` devuelto aquí es obligatorio como parámetro de ruta `knowledge_base_id` en todas las demás solicitudes de Knowledge Base.

```http theme={null}
GET /v1/knowledge-bases HTTP/1.1
X-API-Key: your_api_key
```

```json theme={null}
{
  "data": [
    {
      "id": "your_knowledge_base_id",
      "name": "Product Documentation",
      "slug": "product-documentation",
      "description": "Product guides and reference material",
      "created_at": "2026-04-24T19:03:15.459951Z"
    }
  ],
  "pagination": {}
}
```

Si tu clave de API puede acceder a varias organizaciones, pasa `organization_id` en la solicitud:

```http theme={null}
GET /v1/knowledge-bases?organization_id=your_organization_id HTTP/1.1
X-API-Key: your_api_key
```

Usa el mismo parámetro de consulta en las solicitudes posteriores cuando la clave de API abarque varias organizaciones.

### 2. Añadir una carpeta

Las carpetas están vacías al crearse. La carpeta de un documento ya debe existir, así que crea la jerarquía de origen antes de subir documentos y usa rutas de carpeta como `Engineering/API` para replicar la jerarquía de Guru. Crea las carpetas principales antes que sus carpetas anidadas. Crear una carpeta que ya existe devuelve `409 Conflict`.

```http theme={null}
POST /v1/knowledge-bases/your_knowledge_base_id/folders HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "path": "Engineering"
}
```

```json theme={null}
{
  "message": "Folder added.",
  "path": "Engineering"
}
```

### 3. Añadir un documento

Añade un documento como JSON enviando su texto en el campo `text`. `folder` es opcional; cuando se proporciona, es la ruta de la carpeta que contiene el documento.

```http theme={null}
POST /v1/knowledge-bases/your_knowledge_base_id/documents HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "name": "authentication.md",
  "folder": "Engineering",
  "text": "# Authentication\n\nUse an API key to authenticate requests."
}
```

También puedes subir un archivo como datos de formulario multipart. Esto es útil cuando tu sistema de origen proporciona los archivos de documento directamente:

```bash theme={null}
curl -X POST "https://api.tryprofound.com/v1/knowledge-bases/your_knowledge_base_id/documents" \
  -H "X-API-Key: your_api_key" \
  -F "name=authentication.md" \
  -F "folder=Engineering" \
  -F "file=@./authentication.md"
```

Ambas formas devuelven el nombre, la ruta y la carpeta del documento:

```json theme={null}
{
  "message": "Document added.",
  "name": "authentication.md",
  "path": "Engineering/authentication.md",
  "folder": "Engineering"
}
```

Añadir un documento no sobrescribe un documento existente: si la ruta del documento ya existe, la solicitud devuelve `409 Conflict`. Usa la actualización en su lugar cuando la ruta ya exista.

### 4. Actualizar un documento

La actualización sobrescribe un documento existente en la ruta de destino. La solicitud JSON tiene los mismos campos `name`, `text` y `folder` opcional que la de añadir:

```http theme={null}
PUT /v1/knowledge-bases/your_knowledge_base_id/documents HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "name": "authentication.md",
  "folder": "Engineering",
  "text": "# Authentication\n\nUse the latest API key instructions."
}
```

Las subidas multipart usan los mismos campos `name` y `folder` opcional, con `file` en lugar de `text`:

```bash theme={null}
curl -X PUT "https://api.tryprofound.com/v1/knowledge-bases/your_knowledge_base_id/documents" \
  -H "X-API-Key: your_api_key" \
  -F "name=authentication.md" \
  -F "folder=Engineering" \
  -F "file=@./authentication.md"
```

La actualización apunta a una ruta de documento existente en una carpeta existente; una carpeta inexistente devuelve `404 Not Found`.

### 5. Eliminar un documento

Elimina un documento enviando su nombre en el cuerpo de una solicitud JSON. Incluye `folder` en el nombre cuando elimines un documento anidado:

```http theme={null}
DELETE /v1/knowledge-bases/your_knowledge_base_id/documents HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "name": "Engineering/authentication.md"
}
```

### 6. Eliminar una carpeta

Elimina una carpeta vacía estableciendo `recursive` en `false` (el valor predeterminado):

```http theme={null}
DELETE /v1/knowledge-bases/your_knowledge_base_id/folders HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "path": "Engineering",
  "recursive": false
}
```

Si la carpeta no está vacía, la solicitud devuelve `409 Conflict` y no se elimina nada. Para eliminar la carpeta y todo su contenido, establece `recursive` en `true`:

```json theme={null}
{
  "path": "Engineering",
  "recursive": true
}
```

### 7. Buscar en una knowledge base

Busca con un `query` obligatorio y un `top_k` entre 1 y 100. Establece `return_full_page` en `true` para solicitar el contenido completo de la página en lugar de fragmentos.

```http theme={null}
POST /v1/knowledge-bases/your_knowledge_base_id/search HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "query": "How do I authenticate?",
  "top_k": 5,
  "return_full_page": false,
  "filters": {
    "tags": ["api"],
    "folders": ["Engineering"]
  }
}
```

`filters.tags` coincide con los documentos que tengan cualquiera de las etiquetas proporcionadas. `filters.folders` limita la búsqueda a rutas de carpeta y actualmente acepta exactamente una carpeta.

Cada resultado incluye un `id`, una puntuación de relevancia `score`, `metadata` y el contenido coincidente `content`:

```json theme={null}
{
  "data": [
    {
      "id": "Engineering/authentication.md",
      "score": 0.94,
      "metadata": {
        "folder_path": "Engineering",
        "source_filename": "authentication.md"
      },
      "content": "Use an API key to authenticate requests."
    }
  ],
  "pagination": {}
}
```

<Tip>
  Para sincronizar un sistema externo, recorre los documentos de origen, usa sus rutas de carpeta para replicar la jerarquía de origen, usa `PUT` para resincronizaciones idempotentes y usa `DELETE` para los documentos eliminados del origen.
</Tip>