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

> ## Agent Instructions
> Conare's API is at https://api.conare.ai. Authenticate with `Authorization: Bearer $CONARE_API_KEY`.
> The full OpenAPI spec is at https://api.conare.ai/openapi.yaml; each endpoint has a page under /api-reference, and appending .md to any page URL returns its Markdown.
> Embed with model conare-embed-1; send input_type "query" for search queries. Rerank with conare-rerank-1.
> Prefer the TypeScript SDK (`npm install conare`) or plain HTTP in examples.
> Install the Conare skill with `npx skills add https://docs.conare.ai`; search these docs over MCP at https://docs.conare.ai/mcp; the whole site is at https://docs.conare.ai/llms-full.txt.

# Fichiers

> Importez un fichier PDF, Word, PowerPoint, Excel, CSV, texte ou image comme un document consultable, ou convertissez-le en Markdown sans rien stocker.

Deux routes lisent les fichiers avec un même parseur, les mêmes options et le même résultat :

| Route | Action | Taille |
| - | - | - |
| [`POST /namespaces/:namespace/files`](#importer-un-fichier) | Stocke le fichier sous forme d'un seul document consultable ; une recherche indique la page, la diapositive ou les lignes qui répondent | Jusqu'à 512 Mio et 5 000 pages |
| [`POST /parse`](#convertir-un-fichier) | Renvoie le fichier en Markdown ; ne stocke rien | Jusqu'à 20 Mio |

Les numérisations et les images sont lues par OCR, quel que soit le nombre de pages. Formats pris en charge : [Types de fichiers](https://docs.conare.ai/fr/file-types.md).

## Importer un fichier

`POST /namespaces/:namespace/files`

Envoyez les octets du fichier comme corps, comme partie fichier d'un formulaire multipart, ou en JSON `{"url": "https://..."}` pour que Conare le récupère.

```bash curl theme={null}
curl "https://api.conare.ai/namespaces/reports/files?name=report.pdf" \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf
```

```bash curl (form) theme={null}
curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -F file=@report.pdf
```

```bash curl (URL) theme={null}
curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'
```

```ts TypeScript theme={null}
import { readFile } from "node:fs/promises";

const reports = conare.namespace("reports");
const file = await reports.uploadFile(await readFile("report.pdf"), "report.pdf", {
  metadata: { site: "north-pit" },
});
```

```json Response theme={null}
{
  "file_id": "report.pdf",
  "name": "report.pdf",
  "type": "pdf",
  "state": "ready",
  "source_id": "src_01139ca8ca59f2556f65b60e",
  "uploaded_at": 1792618822534,
  "pages": 2,
  "ids": ["src_01139ca8ca59f2556f65b60e:report.pdf"],
  "ocr_failed": [],
  "ocr_pending": [],
  "markdown": "<!-- page 1 -->\n\n# Q3 report\n\nRevenue grew 12 percent in EMEA.\n\n<!-- page 2 -->\n\n# Outlook\n\nWe expect Q4 revenue to grow again.",
  "parts": [
    { "locator": { "page": 1 }, "markdown": "# Q3 report\n\nRevenue grew 12 percent in EMEA.", "ocr": true, "confidence": null },
    { "locator": { "page": 2 }, "markdown": "# Outlook\n\nWe expect Q4 revenue to grow again.", "ocr": true, "confidence": null }
  ],
  "without_text": { "pages": [], "slides": [], "images": [] }
}
```

La réponse attend jusqu'à `wait` secondes que le fichier soit lu : `200` lorsqu'il est `ready` ou `failed`, sinon `202` pendant la lecture.

### Options

Paramètres de requête, valables sur les deux routes sauf mention contraire.

| Option | Type | Ce qu'elle fait |
| - | - | - |
| `name` | chaîne | Le nom du fichier, jusqu'à 4 096 caractères ; son extension distingue `.csv`, `.tsv` et `.md` du texte |
| `id` | chaîne | Import uniquement. L'id du fichier, la fin de l'id de son document ; par défaut `name`, les autres caractères étant remplacés par `-` |
| `type` | chaîne | `pdf`, `docx`, `pptx`, `xlsx`, `csv`, `png`, ... ([tous](https://docs.conare.ai/fr/file-types.md)) ; sinon déduit des octets, puis du nom |
| `user` | chaîne | Import uniquement. À qui appartient le fichier ; supprimer l'utilisateur le supprime |
| `metadata` | chaîne | Import uniquement. Un objet JSON copié dans les métadonnées du document |
| `pages` | chaîne | Pages, diapositives ou images à lire, comme `1-20,25` ou `5-` |
| `password` | chaîne | Ouvre un fichier PDF, Word, PowerPoint ou Excel protégé, jusqu'à 20 Mio |
| `layout` | booléen, `false` par défaut | Chaque partie passée par l'OCR porte aussi des `blocks` : les zones de sa page ([champs](https://docs.conare.ai/fr/file-types.md#blocs-de-mise-en-page)) |
| `wait` | secondes, 60 par défaut | Durée d'attente de la lecture avant `202`, jusqu'à 300 ; `0` répond immédiatement |

* Un `Content-Type` comme `application/pdf` déclare aussi le type.
* `wait` : `true` vaut 60 ; la réponse arrive toujours en moins de 105 secondes. Pour les imports, `false` répond dès que le texte est stocké, avec `ocr_pending`.
* Une page hors de `pages` n'est ni lue ni passée par l'OCR ; `pages` sur un fichier sans pages renvoie `400`.

Schéma complet : [Upload a file](https://docs.conare.ai/fr/api-reference/files/upload-a-file.md).

### Réponse

| Champ | Signification |
| - | - |
| `file_id`, `name`, `type` | L'id utilisé, le nom, et le type détecté (`image` pour tous les formats d'image) |
| `state` | `queued`, `parsing`, `ocr` (l'OCR lit encore `ocr_pending`), `ready` ou `failed` avec `error` |
| `source_id` | La source de fichiers du namespace ; l'id du document commence par elle |
| `ids` | L'unique document du fichier, `["<source_id>:<file_id>"]`, une fois `ready` |
| `uploaded_at` | Millisecondes Unix |
| `result` | `unchanged` lorsque le même fichier, nom, métadonnées et options ont déjà été importés ; rien n'est relu |
| `pages` | Les pages d'un PDF ou les images d'une image animée |
| `ocr_failed` | Pages que l'OCR n'a pas pu lire après plusieurs essais ; réimportez pour les retenter |
| `markdown`, `parts`, `without_text` | Le [résultat](#résultat) |

`images_without_text`, `pages_without_text`, `pages_ocr`, `images_ocr`, `sheets`, `slides` et `slides_without_text` sont obsolètes : `parts` et `without_text` donnent les mêmes informations.

## Vérifier un fichier

`GET /namespaces/:namespace/files/:id`

Renvoie le dernier import du fichier, avec les mêmes champs ; interrogez-le après un `202`.

```bash curl theme={null}
curl https://api.conare.ai/namespaces/reports/files/report.pdf \
  -H "Authorization: Bearer $CONARE_API_KEY"
```

```ts TypeScript theme={null}
const file = await reports.getFile("report.pdf");
```

| Option | Type | Ce qu'elle fait |
| - | - | - |
| `user` | chaîne | L'utilisateur, pour un fichier importé avec `user` |

Schéma complet : [Read a file](https://docs.conare.ai/fr/api-reference/files/read-a-file.md).

## Documents stockés

Un fichier est un document, `<source_id>:<file_id>` ; ses pages, diapositives, lignes de feuille, sections et images en sont les parties.

| Où | Ce que vous obtenez |
| - | - |
| [Recherche](https://docs.conare.ai/fr/query.md) | Une page d'un PDF ou d'une image, une diapositive ou une plage de lignes d'une feuille est un résultat à part, id `<source_id>:<file_id>$<part>` : `$page-3`, `$slide-4`, `$<sheet>-1` |
| Recherche dans un fichier texte, Markdown ou Word | Un seul résultat, le fichier `<source_id>:<file_id>`, avec ses passages pris n'importe où dans le fichier |
| Les `metadata` d'un résultat | Où se trouve sa partie, ou son premier passage, selon les clés ci-dessous |
| [`GET /namespaces/:namespace/documents/:id`](https://docs.conare.ai/fr/documents#obtenir-un-document) | Avec l'id du fichier, le texte du fichier entier, une ligne vide entre les pages ; avec l'id d'une partie, cette partie seule |

### Où se trouve une partie

| Fichier | Emplacement dans les métadonnées |
| - | - |
| PDF | `page` |
| Word, texte, Markdown | `part`, `heading`, et `lines` pour le texte |
| PowerPoint | `slide` |
| Excel, CSV, TSV | `sheet`, `rows` |
| Image | `page`, et `frame` |
| Une illustration dans Word | `image`, `heading` |
| Une illustration sur une diapositive | `slide`, `image` |
| Un graphique dans une feuille | `sheet` |

Le document a aussi `file`, `file_id`, `file_type`, `uploaded_at`, les `metadata` de l'import, et `ocr: true` lorsque l'OCR l'a lu. Un fichier importé plus tôt peut encore être un document par partie, comme `<source_id>:<file_id>:page-1`, jusqu'à ce qu'il soit réimporté.

| Pour | Faites |
| - | - |
| Remplacer un fichier | Réimportez-le avec le même id |
| Réessayer sans risque | Le même fichier, nom, métadonnées et options renvoie `unchanged`, sans `Idempotency-Key` |
| Rechercher dans un fichier | [Filtrez](https://docs.conare.ai/fr/filters.md) sur `{ "file_id": "report.pdf" }` |
| Rechercher dans une page | Filtrez sur `{ "file_id": "report.pdf", "page": 3 }` |
| Séparer les utilisateurs | Importez avec `user`, [recherchez](https://docs.conare.ai/fr/query.md) avec `user` |
| Supprimer l'original | Il est conservé jusqu'à la suppression du namespace ou de son utilisateur |

## Convertir un fichier

`POST /parse`

Renvoie le fichier en Markdown et ne stocke rien ; toute clé peut convertir, y compris une clé Models only.

```bash curl theme={null}
curl "https://api.conare.ai/parse?name=report.pdf" \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf
```

```bash curl (URL) theme={null}
curl https://api.conare.ai/parse \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'
```

```ts TypeScript theme={null}
import { readFile } from "node:fs/promises";

const out = await conare.parse(await readFile("report.pdf"), { name: "report.pdf" });
if (out.state === "parsing") console.log(await conare.getParse(out.id));
```

```json Response theme={null}
{
  "id": "prs_76149e8db2be257fa8a0ac01",
  "state": "done",
  "type": "pdf",
  "name": "report.pdf",
  "pages": 2,
  "markdown": "<!-- page 1 -->\n\n# Q3 report\n\nRevenue grew 12 percent in EMEA.\n\n<!-- page 2 -->\n\n# Outlook\n\nWe expect Q4 revenue to grow again.",
  "parts": [
    { "locator": { "page": 1 }, "markdown": "# Q3 report\n\nRevenue grew 12 percent in EMEA.", "ocr": true, "confidence": null },
    { "locator": { "page": 2 }, "markdown": "# Outlook\n\nWe expect Q4 revenue to grow again.", "ocr": true, "confidence": null }
  ],
  "without_text": { "pages": [], "slides": [], "images": [] }
}
```

| Option | Type | Ce qu'elle fait |
| - | - | - |
| `url` | chaîne | Dans un corps JSON : une URL `https` sur une adresse publique, récupérée en 60 secondes maximum, jusqu'à 20 Mio |
| `name`, `type`, `pages`, `password`, `layout`, `wait` | | Comme pour l'[import](#options) |

* Le corps fait jusqu'à 20 Mio, et l'OCR lit jusqu'à 100 pages ; les pages suivantes conservent leur couche texte.
* Pour convertir un fichier JSON, envoyez-le en `text/plain`.

Schéma complet : [Parse a file](https://docs.conare.ai/fr/api-reference/parse/parse-a-file-to-markdown.md).

### Récupérer une conversion

`GET /parse/:id`

Une conversion ayant répondu `202` (`state: "parsing"`) est conservée 24 heures : récupérez-la jusqu'à ce que `state` soit `done`, ou `failed` avec son `error`.

```bash curl theme={null}
curl https://api.conare.ai/parse/prs_0e631c59528ac4f7424dc776 \
  -H "Authorization: Bearer $CONARE_API_KEY"
```

Schéma complet : [Read a parse](https://docs.conare.ai/fr/api-reference/parse/get-a-parse-result.md).

## Résultat

| Champ | Signification |
| - | - |
| `markdown` | Le fichier entier ; chaque page, diapositive et feuille commence par `<!-- page 3 -->`, `<!-- slide 4 -->` ou `<!-- sheet "Q3" -->` |
| `parts` | Dans l'ordre de lecture, chacune avec son `locator`, `markdown`, `ocr` et `confidence` |
| `parts[].locator` | `{"page": 3}`, `{"slide": 4, "image": 1}`, `{"sheet": "Q3", "rows": "2-41"}` ou `{"part": 2, "heading": "..."}` |
| `parts[].ocr` | Lu par OCR depuis l'image de la page, et non depuis sa couche texte |
| `parts[].confidence` | La certitude de l'OCR, de 0 à 1 ; `null` quand l'OCR n'en donne pas (la plupart des pages nativement numériques) |
| `without_text` | Les `pages`, `slides` et `images` sans texte, chaque illustration avec sa [`reason`](https://docs.conare.ai/fr/file-types#images-dans-word-et-powerpoint) |

Les règles du Markdown figurent dans [Types de fichiers](https://docs.conare.ai/fr/file-types.md#markdown).

## Erreurs

| Erreur | Quand |
| - | - |
| `400 invalid_request` | Une option n'est pas valide : `pages` sur un fichier sans pages, `wait` au-delà de 300, `metadata` qui n'est pas un objet JSON, une URL qui n'est pas en `https` sur une adresse publique |
| `400 fetch_failed` | L'URL n'a pas répondu `200` avec le fichier |
| `404 parse_not_found` | Aucune conversion avec cet id n'a répondu `202` au cours des dernières 24 heures |
| `409 file_replaced` | Le fichier a été supprimé pendant l'attente de la réponse |
| `409 user_purging` | L'utilisateur est en cours de suppression |
| `413 payload_too_large` | Plus de 512 Mio (import) ou de 20 Mio (conversion, ou avec `password`) |
| `415 unsupported_file` | Type non pris en charge, ou différent du `type` déclaré ; le message indique sous quel format l'enregistrer |
| `422 password_protected` | Le fichier a un mot de passe : envoyez-le via `password` |
| `422 unreadable_file` | Le fichier est endommagé |
| `422 no_text` | Aucune page, feuille, diapositive, aucun paragraphe ni aucune illustration ne contient de texte |
| `503 files_unavailable` | Les fichiers ne peuvent pas être stockés pour le moment ; réessayez plus tard |

Un fichier de plus de 5 000 pages, feuilles ou diapositives se termine en `failed` avec `too_large`.


## Related topics

- [Types de fichiers et Markdown](https://docs.conare.ai/fr/file-types.md)
- [Google Cloud Storage](https://docs.conare.ai/fr/gcs.md)
- [Présentation de l'API](https://docs.conare.ai/fr/api.md)
- [Filtres](https://docs.conare.ai/fr/filters.md)
- [Read a file](https://docs.conare.ai/fr/api-reference/files/read-a-file.md)


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