> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-fcql78.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Parse
> Convertissez des documents — PDF, Word, Excel, PowerPoint et bien d’autres — en markdown propre, contenu par page, blocs de mise en page et JSON structuré
Parse convertit les documents en données propres, prêtes pour les LLM. Importez un fichier via
[`/parse`](/fr/api-reference/endpoint/parse) — ou utilisez [`/scrape`](/fr/features/scrape)
avec l’URL d’un document public — et obtenez du markdown, du contenu par page, des
blocs de mise en page typés ou du JSON structuré.
* **Respect de la mise en page :** titres, paragraphes, tableaux et formules assemblés dans l’ordre de lecture
* **Documents numérisés pris en charge :** extraction de texte natif avec OCR comme solution de repli pour les pages ne contenant que des images
* **Structure ancrée dans le document :** blocs de mise en page typés avec boîtes englobantes et liens vers des plages de caractères du markdown (PDF)
* **Tous les formats courants :** PDF, Word, Excel, PowerPoint, OpenDocument, EPUB, CSV, HTML
* Prise en charge de **Zero Data Retention**
## Démarrage rapide
```python Python theme={null}
from firecrawl import Firecrawl
firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
doc = firecrawl.parse("./report.pdf")
print(doc.markdown)
```
```javascript Node theme={null}
import { Firecrawl } from "firecrawl";
import fs from "node:fs";
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const doc = await firecrawl.parse({
data: fs.readFileSync("./report.pdf"),
filename: "report.pdf",
});
console.log(doc.markdown);
```
```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/parse \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'file=@./report.pdf' \
-F 'options={"formats":["markdown"]};type=application/json'
```
Vous avez une **URL publique vers un document** plutôt qu’un fichier ? [`/scrape`](/fr/features/scrape)
détecte le type de fichier et l’analyse de la même façon — mêmes options, même résultat :
`firecrawl.scrape("https://example.com/report.pdf")`.
## Réponse
Les SDK renvoient directement l’objet document. cURL renvoie le payload JSON.
```json theme={null}
{
"success": true,
"data": {
"markdown": "# Annual Report\n\n...",
"metadata": {
"title": "Annual Report",
"numPages": 42,
"totalPages": 42,
"sourceFile": "report.pdf"
}
}
}
```
`numPages` est le nombre de pages réellement analysées ; `totalPages` correspond au nombre
réel de pages du document. Ils correspondent sauf si `maxPages` a tronqué le résultat — p. ex. l’analyse
d’un PDF de 100 pages avec `maxPages: 10` renvoie `numPages: 10` et `totalPages: 100`, donc
`totalPages > numPages` indique que la sortie a été tronquée. `totalPages` est omis
lorsque le nombre de pages ne peut pas être déterminé.
Au-delà du markdown du document, trois sorties couvrent les cas où une seule
chaîne markdown ne suffit pas : le [markdown par page](#per-page-markdown-pdf) et les
[blocs de mise en page](#layout-blocks-pdf) pour les documents PDF, et le
[JSON structuré](#structured-json-output) pour tous les formats.
## Markdown par page (PDF)
Activez `pages: true` dans l'[analyseur PDF](#pdf-options) pour que le document contienne également
un tableau `pages` avec le markdown de chaque page — utile pour savoir de quelle page provient le contenu
ou pour traiter les pages indépendamment. Sans coût supplémentaire.
```python Python theme={null}
from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions
firecrawl = Firecrawl(api_key="fc-VOTRE-CLÉ-API")
doc = firecrawl.parse(
"./report.pdf",
options=ScrapeOptions(parsers=[{"type": "pdf", "pages": True}]),
)
for page in doc.pages:
print(page.page_number, page.markdown[:80])
```
```js Node theme={null}
import { Firecrawl } from "firecrawl";
import fs from "node:fs";
const firecrawl = new Firecrawl({ apiKey: "fc-VOTRE-CLÉ-API" });
const doc = await firecrawl.parse(
{ data: fs.readFileSync("./report.pdf"), filename: "report.pdf" },
{ parsers: [{ type: "pdf", pages: true }] },
);
for (const page of doc.pages) {
console.log(page.pageNumber, page.markdown.slice(0, 80));
}
```
```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/parse \
-H 'Authorization: Bearer VOTRE_CLÉ_API' \
-F 'file=@./report.pdf' \
-F 'options={"parsers":[{"type":"pdf","pages":true}]};type=application/json'
```
```json theme={null}
"pages": [
{ "pageNumber": 1, "markdown": "# Annual Report\n\n..." },
{ "pageNumber": 2, "markdown": "..." }
]
```
## Blocs de mise en page (PDF)
Définissez `blocks: true` dans l’[analyseur PDF](#pdf-options) ; le document contient alors également
un tableau `blocks` : pour chaque page, les blocs de mise en page typés détectés par le moteur d’analyse,
avec leur géométrie et leur provenance. Il s’agit du pendant structuré
du markdown : utilisez-le pour l’ancrage des citations, superposer des surlignages
ou auditer le contenu d’un document. Sans coût supplémentaire.
```python Python theme={null}
from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions
firecrawl = Firecrawl(api_key="fc-VOTRE-CLÉ-API")
doc = firecrawl.parse(
"./report.pdf",
options=ScrapeOptions(parsers=[{"type": "pdf", "blocks": True}]),
)
for page in doc.blocks:
for block in page.items:
print(page.page_number, block.type, block.bbox)
```
```js Node theme={null}
import { Firecrawl } from "firecrawl";
import fs from "node:fs";
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const doc = await firecrawl.parse(
{ data: fs.readFileSync("./report.pdf"), filename: "report.pdf" },
{ parsers: [{ type: "pdf", blocks: true }] },
);
for (const page of doc.blocks) {
for (const block of page.items) {
console.log(page.pageNumber, block.type, block.bbox);
}
}
```
```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/parse \
-H 'Authorization: Bearer VOTRE_CLÉ_API' \
-F 'file=@./report.pdf' \
-F 'options={"parsers":[{"type":"pdf","blocks":true}]};type=application/json'
```
```json theme={null}
"blocks": [
{
"pageNumber": 1,
"width": 1700,
"height": 2200,
"status": "ok",
"items": [
{
"id": "p1.b0",
"type": "title",
"label": "doc_title",
"bbox": [0.118, 0.054, 0.882, 0.092],
"content": "# Annual Report",
"markdownSpan": [0, 15],
"readingOrder": 0,
"source": "native_text",
"confidence": { "layout": 0.97, "ocr": null }
}
]
}
]
```
### Champs de bloc
| Champ | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Stable au sein d'une réponse : `p.b`. |
| `type` | Type de bloc : `title`, `section_header`, `text`, `table`, `formula`, `figure`, `caption`, `page_number`, `page_header`, `page_footer`. De nouveaux types peuvent apparaître au fil du temps. |
| `label` | Étiquette brute du modèle de mise en page, transmise telle quelle pour assurer la compatibilité ascendante. |
| `bbox` | `[x0, y0, x1, y1]` normalisé entre 0 et 1 par rapport à la page. Multipliez par `width`/`height` pour obtenir les coordonnées en pixels. `null` lorsque les dimensions de la page sont inconnues. |
| `content` | Fragment Markdown apporté par ce bloc. |
| `markdownSpan` | Décalages de caractères `[start, end)` dans le `markdown` du document correspondant au fragment de ce bloc. `null` lorsque le post-traitement a réécrit le fragment. |
| `readingOrder` | Position dans l'ordre de lecture détecté. |
| `source` | Chemin du pipeline ayant produit le bloc (p. ex. `native_text`, `layout_ocr`, `tsr`, `formula_model`). |
| `confidence` | Score de détection `layout` (0–1) et niveau de confiance du texte `ocr` lorsque la source en fournit un ; `null` sinon — jamais une agrégation inventée. |
### Ancrage : d’une réponse à la page
`markdownSpan` lie chaque bloc à la sous-chaîne exacte du markdown qu’il a
produit. L’ancrage des citations relève donc d’une recherche, et non d’une inférence : trouvez le
texte cité dans le markdown, puis le bloc dont la plage couvre ce décalage,
et vous obtenez le numéro de page et la boîte englobante — sans jamais demander de
coordonnées à un modèle de langage.
```python Python theme={null}
def ground(doc, quote: str):
start = doc["markdown"].find(quote)
for page in doc["blocks"]:
for block in page["items"]:
span = block["markdownSpan"]
if span and span[0] <= start < span[1]:
return page["pageNumber"], block["bbox"]
```
```js Node theme={null}
function ground(doc, quote) {
const start = doc.markdown.indexOf(quote);
for (const page of doc.blocks) {
for (const block of page.items) {
const span = block.markdownSpan;
if (span && span[0] <= start && start < span[1]) {
return { pageNumber: page.pageNumber, bbox: block.bbox };
}
}
}
}
```
## Sortie JSON structurée
Fournissez un schéma JSON ou un prompt pour extraire des données structurées directement du document :
```python Python theme={null}
from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions
from pydantic import BaseModel
firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
class Invoice(BaseModel):
vendor: str
total: float
doc = firecrawl.parse(
"./invoice.pdf",
options=ScrapeOptions(formats=[{
"type": "json",
"schema": Invoice.model_json_schema(),
}]),
)
print(doc.json)
```
```js Node theme={null}
import { Firecrawl } from "firecrawl";
import fs from "node:fs";
import { z } from "zod";
const firecrawl = new Firecrawl({ apiKey: "fc-VOTRE-CLÉ-API" });
const schema = z.object({
vendor: z.string(),
total: z.number(),
});
const doc = await firecrawl.parse(
{ data: fs.readFileSync("./invoice.pdf"), filename: "invoice.pdf" },
{ formats: [{ type: "json", schema }] },
);
console.log(doc.json);
```
```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/parse \
-H 'Authorization: Bearer VOTRE_CLÉ_API' \
-F 'file=@./invoice.pdf' \
-F 'options={"formats":[{"type":"json","schema":{"type":"object","properties":{"total":{"type":"number"},"vendor":{"type":"string"}}}}]};type=application/json'
```
## Options pour les PDF
Le comportement des PDF est entièrement contrôlé par l’option `parsers`, aussi bien pour `/parse` que pour
`/scrape` :
```json theme={null}
{
"parsers": [
{
"type": "pdf",
"mode": "auto",
"maxPages": 100,
"pages": true,
"blocks": true
}
]
}
```
| Propriété | Type | Par défaut | Description |
| ---------- | --------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `type` | `"pdf"` | *(obligatoire)* | Type d’analyseur. |
| `mode` | `"fast" \| "auto" \| "ocr"` | `"auto"` | Stratégie d’analyse — voir ci-dessous. |
| `maxPages` | `integer` | — | Limite le nombre de pages à analyser. |
| `pages` | `boolean` | `false` | Renvoie également le [Markdown par page](#per-page-markdown-pdf). Aucun coût supplémentaire. |
| `blocks` | `boolean` | `false` | Renvoie également les [blocs de mise en page](#layout-blocks-pdf) avec leurs boîtes englobantes. Aucun coût supplémentaire. |
Passer `parsers: []` désactive entièrement l’analyse et renvoie le PDF en base64
(1 crédit forfaitaire).
### Modes d’analyse
| Mode | Description |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto` | Tente d’abord une extraction rapide basée sur le texte, puis bascule vers l’OCR lorsqu’une page le nécessite. C’est le mode par défaut. |
| `fast` | Extraction basée uniquement sur le texte (texte intégré). Option la plus rapide, mais échoue sur les pages numérisées ou ne contenant que des images, plutôt que de ne rien renvoyer silencieusement. |
| `ocr` | Force l’OCR sur chaque page. À utiliser pour les documents numérisés ou lorsque `auto` classe mal une page. |
## Formats pris en charge
**Extensions :** `.html`, `.htm`, `.xhtml`, `.pdf`, `.docx`, `.doc`, `.docm`, `.odt`, `.ods`, `.odp`, `.rtf`, `.xlsx`, `.xls`, `.xlsm`, `.xlsb`, `.pptx`, `.ppt`, `.pptm`, `.epub`, `.csv`.
Voir [Document Parsing](/fr/features/document-parsing) pour savoir comment chaque format est
converti.
## Référence de la requête
La requête est au format `multipart/form-data` avec une partie `file` obligatoire et une
partie JSON `options` facultative. `options` accepte un sous-ensemble des options de scrape :
* `formats` : tableau de formats de sortie. Valeur par défaut : `["markdown"]`. Pris en charge : `markdown`, `html`, `rawHtml`, `links`, `images`, `summary` et `json` (avec un schéma ou un prompt).
* `onlyMainContent` : renvoie uniquement le contenu principal du document. Valeur par défaut : `true`.
* `includeTags` / `excludeTags` : inclusion ou exclusion au niveau des balises (éléments HTML).
* `redactPII` : masque les informations personnelles identifiables dans le markdown renvoyé.
* `timeout` : délai d’expiration de la requête en millisecondes. Valeur par défaut : `30000`, maximum `300000`.
* `parsers` : paramètres du parseur de fichiers — consultez les [options PDF](#pdf-options).
`/parse` ne prend pas en charge les options réservées au navigateur comme `actions`, `waitFor`, `location`, `mobile` ou le suivi des modifications.
**Vous utilisez Firecrawl via MCP ?** Utilisez `firecrawl_parse` pour les fichiers locaux. Le MCP local peut lire directement le fichier lorsqu’il est configuré avec `FIRECRAWL_API_URL`. Le MCP hébergé à distance renvoie d’abord une commande de téléversement à durée de vie limitée, puis analyse l’`uploadRef` renvoyé. Les URL de documents publics doivent toujours utiliser `/scrape`.
## Considérations
* La taille maximale de fichier est de **50 MB** par requête.
* L’analyse de PDF est facturée à **1 crédit par page** ; les options `pages` et `blocks` n’entraînent aucun coût supplémentaire.
* L’analyse de PDF très volumineux ou numérisés en mode `ocr` peut prendre plus de temps — augmentez `timeout` ou utilisez `maxPages` pour limiter le traitement.
* Pour des lots de fichiers, appelez `/parse` pour chaque fichier en parallèle ; il n’existe pas d’option de téléversement par lot.
> Êtes-vous un agent IA qui a besoin d’une clé API Firecrawl ? Consultez [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) pour obtenir des instructions d’intégration automatisée.