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

# Base de connaissance (API)

> Gérer les documents de la base de connaissance via l'API : URL d'upload, processing, liste, suppression et recherche.

## Cycle de vie d'un document

### 1. Obtenir une URL d'upload

`POST /api/v1/api/knowledge-base/upload-url`

| Champ | Type | Requis | Description |
| - | - | -: | - |
| `filename` | string | oui | Nom du fichier à uploader. |
| `mime_type` | string | oui | Type MIME du fichier. |
| `custom_metadata` | object \| null | non | Métadonnées libres attachées au document. |

Réponse :

```json theme={null}
{ "upload_url": "https://...", "document_uuid": "..." }
```

> [!NOTE]
>
> `upload_url` est une URL **présignée** pointant directement vers le storage :
> faites-y un `PUT` du fichier. Conservez l'`upload_url` pour l'étape suivante.

### 2. Uploader le fichier

`PUT` vers `upload_url` avec le `Content-Type` du fichier.

### 3. Lancer le processing

`POST /api/v1/api/knowledge-base/process-document`

| Champ | Type | Requis | Description |
| - | - | -: | - |
| `document_uuid` | string | oui | UUID renvoyé à l'étape 1. |
| `upload_url` | string | oui | URL d'upload renvoyée à l'étape 1. |
| `retrieval_mode` | string | non | `chunked` (défaut, recherche vectorielle) ou `full_document` (texte intégral). |

Le processing est **asynchrone** : interrogez la liste des documents pour suivre
l'avancement.

## Lister et supprimer

| Méthode | Endpoint |
| - | - |
| `GET` | `/api/v1/api/knowledge-base/documents` |
| `DELETE` | `/api/v1/api/knowledge-base/documents/{document_uuid}` |

## Rechercher dans la base

`POST /api/v1/api/knowledge-base/search`

| Champ | Type | Requis | Défaut | Contraintes | Description |
| - | - | -: | - | - | - |
| `query` | string | oui | — | | Texte de la recherche. |
| `limit` | int | non | `5` | 1..50 | Nombre maximum de résultats. |
| `document_uuids` | string\[] | non | `null` | | Restreint la recherche à ces documents. |
| `min_similarity` | float | non | `null` | 0.0..1.0 | Seuil minimal de similarité. |

```json theme={null}
{
  "query": "Quels sont les horaires d'ouverture ?",
  "limit": 5,
  "min_similarity": 0.7
}
```

Réponse :

```json theme={null}
{
  "chunks": [
    {
      "chunk_text": "...",
      "contextualized_text": "...",
      "chunk_index": 3,
      "chunk_metadata": {},
      "filename": "guide.pdf",
      "document_uuid": "...",
      "similarity": 0.82
    }
  ],
  "query": "Quels sont les horaires d'ouverture ?",
  "total_results": 1
}
```

> [!WARNING]
>
> Les noms de paramètres sont **`limit`** et **`min_similarity`** (et non `top_k`
> ni `threshold`).

## Erreurs

Certaines erreurs du catalogue renvoient un `detail` objet avec
`localized_messages` FR/EN, par exemple :

```json theme={null}
{
  "detail": {
    "code": "knowledge_base_upload_url_failed",
    "localized_messages": {
      "fr": "Impossible de générer l'URL d'upload.",
      "en": "Failed to generate upload URL."
    }
  }
}
```

## Voir aussi

* Guide produit : [Connaissance du nœud](https://docs.bookivox.com/workflow/node-knowledge.md)
* Espace Fichiers : [Fichiers de connaissance](https://docs.bookivox.com/files/overview.md)
* [Erreurs](https://docs.bookivox.com/api-reference/errors)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.