> For the complete documentation index, see [llms.txt](https://guides.ia.numerique.gouv.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guides.ia.numerique.gouv.fr/albert-api/guides/collections-documents.md).

# Collections & documents

Les **collections** regroupent des **documents** découpés en **chunks** indexés. Cette structure est la base du RAG côté Albert API :

* recherche directe via `POST /v1/search` ;
* recherche native via **`SearchTool`** dans `POST /v1/chat/completions`.

## Hiérarchie

```
Collection
  └── Document
        └── Chunks (passages indexés, éventuellement enrichis de métadonnées)
```

## Collections (`/v1/collections`)

* **`GET /v1/collections`** — liste paginée ; filtres `name`, `visibility`, tri `order_by` / `order_direction`.
* **`POST /v1/collections`** — création avec corps JSON `CollectionRequest` :
  * `name` (requis) ;
  * `description` optionnelle ;
  * `visibility` : `private` (par défaut) ou `public`.
* **`GET /v1/collections/{collection_id}`** — détail.
* **`PATCH /v1/collections/{collection_id}`** — mise à jour des métadonnées.
* **`DELETE /v1/collections/{collection_id}`** — suppression.

### Visibilité `public` vs `private`

* **`private`** : vos documents restent dans votre périmètre ; la recherche et le RAG s’appliquent à votre compte/organisation.
* **`public`** : la collection est lisible par les autres utilisateurs (recherche et récupération de chunks selon les règles d’accès). Seul le propriétaire peut modifier/supprimer.

{% hint style="warning" %}
⚠️ À vérifier — La création de collections **publiques** peut être soumise à une permission spécifique côté plateforme. Confirmez auprès de votre gestionnaire accès.
{% endhint %}

## Documents (`/v1/documents`)

* **`GET /v1/documents`** — liste et filtres (collection, pagination).
* **`POST /v1/documents`** — création en **multipart/form-data** :
  * **`file`** : fichier source, typiquement **PDF**, **HTML**, **texte**, **Markdown** (formats et MIME acceptés selon le déploiement). Peut être omis si vous créez un document vide puis ajoutez des chunks ensuite ;
  * **`name`** : nom affiché (utile si vous n’envoyez pas `file`) ;
  * **`collection_id`** : collection cible (préféré) ;
  * **`collection`** : alias **déprécié** (préférez `collection_id`) ;
  * **Chunking** (découpage récursif type `RecursiveCharacterTextSplitter`) :
    * `disable_chunking` — désactive le découpage automatique (conceptuellement proche du “pas de splitter” de certains anciens tutoriels) ;
    * `chunk_size` — taille cible en **caractères** ;
    * `chunk_min_size` — taille minimale d’un chunk ;
    * `chunk_overlap` — chevauchement en caractères ;
    * `is_separator_regex` — traite `separators` comme des regex ;
    * `separators` — liste de délimiteurs (si non vide, `preset_separators` est ignoré) ;
    * `preset_separators` — presets de délimiteurs (ex. `markdown`, `python`, `html`).
  * **`metadata`** : chaîne JSON optionnelle, appliquée aux chunks lors de l’ingestion (à fournir sous forme stringifiée).
* **`DELETE /v1/documents/{document_id}`** — suppression.

{% hint style="warning" %}
⚠️ Métadonnées : `metadata` est attendu comme une **chaîne JSON** dans le multipart. Exemple : `-F 'metadata={"source":"rapport","year":2024}'`.
{% endhint %}

### Exemple minimal : créer une collection et uploader un document

{% tabs %}
{% tab title="curl" %}

```bash
# 1) Collection
curl -sS "https://albert.api.etalab.gouv.fr/v1/collections" \
  -H "Authorization: Bearer $ALBERT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "exemples",
    "visibility": "private"
  }'

# 2) Document
curl -sS "https://albert.api.etalab.gouv.fr/v1/documents" \
  -H "Authorization: Bearer $ALBERT_API_KEY" \
  -F "file=@mon-dossier.pdf" \
  -F "collection_id=REMPLACER_PAR_COLLECTION_ID" \
  -F "chunk_size=2048" \
  -F "chunk_overlap=200"
```

{% endtab %}

{% tab title="Python" %}

```python
import os
import requests

headers = {"Authorization": f"Bearer {os.environ['ALBERT_API_KEY']}"}

collection = requests.post(
    "https://albert.api.etalab.gouv.fr/v1/collections",
    headers={**headers, "Content-Type": "application/json"},
    json={"name": "exemples", "visibility": "private"},
)
collection.raise_for_status()
collection_id = collection.json()["id"]

with open("mon-dossier.pdf", "rb") as f:
    document = requests.post(
        "https://albert.api.etalab.gouv.fr/v1/documents",
        headers=headers,
        files={"file": ("mon-dossier.pdf", f, "application/pdf")},
        data={"collection_id": collection_id, "chunk_size": 2048, "chunk_overlap": 200},
    )
document.raise_for_status()
print(document.json())
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const createCollection = await fetch("https://albert.api.etalab.gouv.fr/v1/collections", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ALBERT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "exemples", visibility: "private" }),
});

if (!createCollection.ok) throw new Error(await createCollection.text());
const { id: collectionId } = await createCollection.json();

const form = new FormData();
form.append("file", new Blob(["REMPLACER_PAR_VOTRE_CONTENU_PDF"]), "mon-dossier.pdf");
form.append("collection_id", String(collectionId));
form.append("chunk_size", "2048");
form.append("chunk_overlap", "200");

const upload = await fetch("https://albert.api.etalab.gouv.fr/v1/documents", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ALBERT_API_KEY}` },
  body: form,
});

if (!upload.ok) throw new Error(await upload.text());
console.log(await upload.json());
```

{% endtab %}
{% endtabs %}

## Chunks

* **`GET /v1/documents/{document_id}/chunks`** — lecture des chunks.
* **`POST /v1/documents/{document_id}/chunks`** — ajout manuel si le document a été créé sans `file`.
* **`GET/DELETE /v1/documents/{document_id}/chunks/{chunk_id}`** — lecture / suppression unitaire.

### Route chunks dépréciée

Les routes **`GET /v1/chunks/{document}`** et apparentées sont **dépréciées**. Utilisez **`/v1/documents/{document_id}/chunks`**.

## Recherche directe sur corpus (`POST /v1/search`)

Hors chat, `CreateSearch` accepte une **`query`**, `collection_ids`, `document_ids`, des filtres de métadonnées, `limit` / `offset`, `method` (`semantic`, `lexical`, `hybrid`) et les paramètres `rff_k` / `score_threshold`.

Pour brancher cette même logique au modèle, voir la [Génération Augmentée par Récupération (RAG)](/albert-api/guides/rag.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://guides.ia.numerique.gouv.fr/albert-api/guides/collections-documents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.