> ## 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
> Transforme documentos — PDFs, Word, Excel, PowerPoint e muito mais — em markdown limpo, conteúdo por página, blocos de layout e JSON estruturado
O Parse converte documentos em dados limpos e prontos para LLMs. Envie um arquivo para
[`/parse`](/pt-BR/api-reference/endpoint/parse) — ou use [`/scrape`](/pt-BR/features/scrape)
em uma URL pública de documento — e receba markdown, conteúdo por página, blocos
de layout tipados ou JSON estruturado.
* **Preserva o layout**: títulos, parágrafos, tabelas e fórmulas organizados na ordem de leitura
* **Inclui documentos digitalizados**: extração de texto nativo com OCR como alternativa para páginas que contêm apenas imagens
* **Estrutura fundamentada**: blocos de layout tipados com caixas delimitadoras e links para intervalos de caracteres no markdown (PDFs)
* **Compatível com formatos comuns**: PDF, Word, Excel, PowerPoint, OpenDocument, EPUB, CSV, HTML
* Suporte a **Zero Data Retention**
## Guia de início rápido
```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'
```
Tem uma **URL pública de documento** em vez de um arquivo? [`/scrape`](/pt-BR/features/scrape)
detecta o tipo de arquivo e faz o parsing da mesma forma — com as mesmas opções e o mesmo resultado:
`firecrawl.scrape("https://example.com/report.pdf")`.
## Resposta
Os SDKs retornam diretamente o objeto de documento. O cURL retorna o 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` é o número de páginas efetivamente analisadas; `totalPages` é a
contagem real de páginas do documento. Os valores coincidem, a menos que `maxPages` tenha truncado o resultado — por exemplo, analisar
um PDF de 100 páginas com `maxPages: 10` retorna `numPages: 10` e `totalPages: 100`, então
`totalPages > numPages` indica que o resultado foi truncado. `totalPages` é omitido
quando não é possível determinar a contagem de páginas.
Além do markdown do documento, três resultados abrangem os casos em que uma única
string de markdown não é suficiente: [markdown por página](#per-page-markdown-pdf) e
[blocos de layout](#layout-blocks-pdf) para documentos PDF, e
[JSON estruturado](#structured-json-output) para todos os formatos.
## Markdown por página (PDF)
Defina `pages: true` no [parser de PDF](#pdf-options), e o documento também
inclui um array `pages` com o markdown físico de cada página — útil quando você
precisa saber de qual página veio o conteúdo ou processar as páginas de forma independente.
Sem custo adicional.
```python Python theme={null}
from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions
firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
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-YOUR-API-KEY" });
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 YOUR_API_KEY' \
-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": "..." }
]
```
## Blocos de layout (PDF)
Defina `blocks: true` no [parser de PDF](#pdf-options), e o documento também
passará a incluir um array `blocks`: para cada página, os blocos de layout tipados que o mecanismo de
análise detectou, com geometria e origem. Este é o equivalente estruturado do
markdown — use-o para fundamentação de citações, criar sobreposições de destaque
ou auditar o conteúdo de um documento. Sem custo adicional.
```python Python theme={null}
from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions
firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
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 YOUR_API_KEY' \
-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 }
}
]
}
]
```
### Campos do bloco
| Campo | Descrição |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Estável dentro de uma resposta: `p.b`. |
| `type` | Tipo de bloco: `title`, `section_header`, `text`, `table`, `formula`, `figure`, `caption`, `page_number`, `page_header`, `page_footer`. Novos tipos podem surgir ao longo do tempo. |
| `label` | Rótulo bruto do modelo de layout, repassado para compatibilidade futura. |
| `bbox` | `[x0, y0, x1, y1]` normalizado de 0 a 1 em relação à página. Multiplique por `width`/`height` para obter coordenadas em pixels. `null` quando a página não tiver dimensões conhecidas. |
| `content` | O fragmento Markdown para o qual este bloco contribuiu. |
| `markdownSpan` | Deslocamentos de caracteres `[start, end)` no `markdown` do documento que abrangem o fragmento deste bloco. `null` quando o pós-processamento reescreveu o fragmento. |
| `readingOrder` | Posição na ordem de leitura detectada. |
| `source` | Caminho do pipeline que produziu o bloco (por exemplo, `native_text`, `layout_ocr`, `tsr`, `formula_model`). |
| `confidence` | Pontuação de detecção de `layout` (0–1) e confiança do texto de `ocr` quando a fonte fornecer uma; `null` caso contrário — nunca um agregado inventado. |
### Fundamentação: de uma resposta à página
`markdownSpan` vincula cada bloco ao trecho exato do markdown que ele
produziu. Isso torna a fundamentação de citações uma consulta, não uma inferência: encontre o
texto citado no markdown, localize o bloco cujo intervalo abrange esse deslocamento
e você terá o número da página e a caixa delimitadora — sem jamais precisar pedir
coordenadas a um modelo de linguagem.
```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 };
}
}
}
}
```
## Resultado JSON estruturado
Passe um schema JSON ou um prompt para extrair dados estruturados diretamente do documento:
```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-YOUR-API-KEY" });
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 YOUR_API_KEY' \
-F 'file=@./invoice.pdf' \
-F 'options={"formats":[{"type":"json","schema":{"type":"object","properties":{"total":{"type":"number"},"vendor":{"type":"string"}}}}]};type=application/json'
```
## Opções de PDF
Todo o comportamento relacionado a PDFs é controlado pela opção `parsers`, tanto em `/parse` quanto em
`/scrape`:
```json theme={null}
{
"parsers": [
{
"type": "pdf",
"mode": "auto",
"maxPages": 100,
"pages": true,
"blocks": true
}
]
}
```
| Propriedade | Tipo | Padrão | Descrição |
| ----------- | --------------------------- | --------------- | ---------------------------------------------------------------------------------------------------- |
| `type` | `"pdf"` | *(obrigatório)* | Tipo de parser. |
| `mode` | `"fast" \| "auto" \| "ocr"` | `"auto"` | Estratégia de análise — veja abaixo. |
| `maxPages` | `integer` | — | Limita o número de páginas a analisar. |
| `pages` | `boolean` | `false` | Também retorna [Markdown por página](#per-page-markdown-pdf). Sem custo adicional. |
| `blocks` | `boolean` | `false` | Também retorna [blocos de layout](#layout-blocks-pdf) com caixas delimitadoras. Sem custo adicional. |
Passar `parsers: []` ignora completamente a análise e retorna o PDF em base64
(1 crédito fixo).
### Modos de análise
| Modo | Descrição |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto` | Primeiro tenta a extração rápida baseada em texto e recorre ao OCR quando necessário. Este é o padrão. |
| `fast` | Somente extração baseada em texto (texto incorporado). É a opção mais rápida, mas falha em páginas digitalizadas ou que contêm apenas imagens, em vez de retornar silenciosamente um resultado vazio. |
| `ocr` | Força o OCR em todas as páginas. Use para documentos digitalizados ou quando `auto` classificar uma página incorretamente. |
## Formatos compatíveis
**Extensões compatíveis:** `.html`, `.htm`, `.xhtml`, `.pdf`, `.docx`, `.doc`, `.docm`, `.odt`, `.ods`, `.odp`, `.rtf`, `.xlsx`, `.xls`, `.xlsm`, `.xlsb`, `.pptx`, `.ppt`, `.pptm`, `.epub`, `.csv`.
Consulte [análise de documentos](/pt-BR/features/document-parsing) para saber como cada formato é
convertido.
## Referência da requisição
A requisição é `multipart/form-data`, com uma parte `file` obrigatória e uma
parte JSON `options` opcional. `options` aceita um subconjunto das opções de scraping:
* `formats`: Array de formatos de resultado. O padrão é `["markdown"]`. Compatíveis: `markdown`, `html`, `rawHtml`, `links`, `images`, `summary` e `json` (com um schema ou prompt).
* `onlyMainContent`: Retorna apenas o conteúdo principal do documento. O padrão é `true`.
* `includeTags` / `excludeTags`: Inclusão ou exclusão em nível de tag (entradas HTML).
* `redactPII`: Redige informações de identificação pessoal do markdown retornado.
* `timeout`: Tempo limite da requisição em milissegundos. O padrão é `30000`, máximo de `300000`.
* `parsers`: Controles do parser de arquivos — consulte as [opções de PDF](#pdf-options).
`/parse` não oferece suporte a opções exclusivas do navegador, como `actions`, `waitFor`, `location`, `mobile` ou rastreamento de alterações.
**Usando o Firecrawl via MCP?** Use `firecrawl_parse` para arquivos locais. O MCP local pode ler o arquivo diretamente quando configurado com `FIRECRAWL_API_URL`. O MCP remoto hospedado primeiro retorna um comando de upload temporário e, em seguida, processa o `uploadRef` retornado. URLs públicas de documentos ainda devem usar `/scrape`.
## Considerações
* O tamanho máximo do arquivo é de **50 MB** por requisição.
* A análise de PDFs é cobrada a **1 crédito por página**; as opções `pages` e `blocks` não geram custo adicional.
* A análise de PDFs muito grandes ou digitalizados no modo `ocr` pode demorar mais — aumente o valor de `timeout` ou use `maxPages` para limitar o processamento.
* Para lotes de arquivos, chame `/parse` para cada arquivo em paralelo; não há opção de upload em lote.
> É um agente de IA que precisa de uma chave de API do Firecrawl? Consulte [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para ver instruções de onboarding automatizado.