Parse

1 min read

post/parse

Request example

curl --request POST \
  --url https://api.firecrawl.dev/v2/parse \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=<file>' \
  --form 'options={"formats":["markdown"],"onlyMainContent":true,"includeTags":["<string>"],"excludeTags":["<string>"],"headers":{},"timeout":30000,"parsers":["pdf"],"skipTlsVerification":true,"removeBase64Images":true,"blockAds":true,"redactPII":false,"proxy":"basic","origin":"api","integration":"<string>","auditMetadata":{"username":"<string>"},"zeroDataRetention":false}'

Response

{
  "success": true,
  "data": {
    "markdown": "<string>",
    "pages": [
      {
        "pageNumber": 1,
        "markdown": "<string>"
      }
    ],
    "blocks": [
      {
        "pageNumber": 1,
        "width": 1,
        "height": 1,
        "status": "<string>",
        "items": [
          {
            "id": "<string>",
            "type": "<string>",
            "label": "<string>",
            "bbox": [
              1
            ],
            "content": "<string>",
            "markdownSpan": [
              1
            ],
            "readingOrder": 1,
            "source": "<string>",
            "confidence": {
              "layout": 1,
              "ocr": 1
            }
          }
        ]
      }
    ],
    "summary": "<string>",
    "html": "<string>",
    "rawHtml": "<string>",
    "rawBase64": "<string>",
    "screenshot": "<string>",
    "audio": "<string>",
    "video": "<string>",
    "answer": "<string>",
    "highlights": "<string>",
    "links": [
      "<string>"
    ],
    "actions": {
      "screenshots": [
        "<string>"
      ],
      "scrapes": [
        {
          "url": "<string>",
          "html": "<string>"
        }
      ],
      "javascriptReturns": [
        {
          "type": "<string>",
          "value": null
        }
      ],
      "pdfs": [
        "<string>"
      ]
    },
    "metadata": {
      "title": "<string>",
      "description": "<string>",
      "language": "<string>",
      "sourceURL": "<string>",
      "url": "<string>",
      "keywords": "<string>",
      "ogLocaleAlternate": [
        "<string>"
      ],
      "<any other metadata> ": "<string>",
      "statusCode": 1,
      "numPages": 1,
      "totalPages": 1,
      "contentType": "<string>",
      "error": "<string>",
      "concurrencyLimited": true,
      "concurrencyQueueDurationMs": 1
    },
    "warning": "<string>",
    "changeTracking": {
      "previousScrapeAt": "2026-08-10T12:00:00Z",
      "changeStatus": "new",
      "visibility": "visible",
      "diff": "<string>",
      "json": {}
    },
    "branding": {
      "colorScheme": "light",
      "logo": "<string>",
      "colors": {
        "primary": "<string>",
        "secondary": "<string>",
        "accent": "<string>",
        "background": "<string>",
        "textPrimary": "<string>",
        "textSecondary": "<string>",
        "link": "<string>",
        "success": "<string>",
        "warning": "<string>",
        "error": "<string>"
      },
      "fonts": [
        {
          "family": "<string>"
        }
      ],
      "typography": {
        "fontFamilies": {
          "primary": "<string>",
          "heading": "<string>",
          "code": "<string>"
        },
        "fontSizes": {
          "h1": "<string>",
          "h2": "<string>",
          "h3": "<string>",
          "body": "<string>"
        },
        "fontWeights": {
          "light": 1,
          "regular": 1,
          "medium": 1,
          "bold": 1
        },
        "lineHeights": {
          "heading": "<string>",
          "body": "<string>"
        }
      },
      "spacing": {
        "baseUnit": 1,
        "borderRadius": "<string>",
        "padding": {},
        "margins": {}
      },
      "components": {
        "buttonPrimary": {
          "background": "<string>",
          "textColor": "<string>",
          "borderRadius": "<string>"
        },
        "buttonSecondary": {
          "background": "<string>",
          "textColor": "<string>",
          "borderColor": "<string>",
          "borderRadius": "<string>"
        },
        "input": {}
      },
      "icons": {},
      "images": {
        "logo": "<string>",
        "favicon": "<string>",
        "ogImage": "<string>"
      },
      "animations": {},
      "layout": {},
      "personality": {}
    },
    "product": {
      "title": "<string>",
      "brand": "<string>",
      "category": "<string>",
      "url": "<string>",
      "description": "<string>",
      "variants": [
        {
          "id": "<string>",
          "sku": "<string>",
          "title": "<string>",
          "values": {},
          "price": {
            "amount": 1,
            "currency": "<string>",
            "formatted": "<string>"
          },
          "sale": {
            "originalPrice": {
              "amount": 1,
              "currency": "<string>",
              "formatted": "<string>"
            }
          },
          "availability": {
            "inStock": true,
            "text": "<string>"
          },
          "images": [
            {
              "url": "<string>",
              "alt": "<string>"
            }
          ]
        }
      ]
    },
    "menu": {
      "isMenu": true,
      "confidence": 1,
      "merchant": {
        "name": "<string>",
        "type": "<string>"
      },
      "currency": "<string>",
      "sections": [
        {
          "id": "<string>",
          "name": "<string>",
          "description": "<string>",
          "items": [
            {
              "id": "<string>",
              "name": "<string>",
              "description": "<string>",
              "images": [
                {
                  "url": "<string>",
                  "alt": "<string>"
                }
              ],
              "price": {
                "amount": 1,
                "currency": "<string>",
                "formatted": "<string>"
              },
              "availability": {
                "inStock": true,
                "text": "<string>"
              },
              "dietary": [
                "<string>"
              ],
              "calories": 1,
              "optionGroups": [
                {}
              ],
              "identifiers": {
                "merchantItemId": "<string>"
              },
              "url": "<string>",
              "sourceUrl": "<string>"
            }
          ]
        }
      ],
      "sourceUrl": "<string>"
    }
  }
}

post/parse

Upload a local or non-public document and convert it into clean, LLM-ready data. /parse accepts file bytes via multipart/form-data and returns Markdown, JSON, HTML, links, images, or a summary — with reading order and tables preserved.

Turn PDF, Word, Excel, PowerPoint, OpenDocument, EPUB, CSV, HTML, and more into Markdown or structured JSON
Up to 5x faster parsing via a Rust-based engine
Files up to 50 MB per request
Zero Data Retention support

When to use `/parse`#

Use /parse when the source document is a local file or not publicly accessible by URL. If you have a public URL that points to a document, prefer /scrape — it auto-detects the file type from the extension or content type and parses it the same way.

Source	Endpoint
Public URL to a document (e.g. `https://example.com/report.pdf`)	`POST /scrape`
Local file or non-public bytes (PDF, DOCX, XLSX, HTML, …)	`POST /parse` (this endpoint)

Tip

Using Firecrawl through MCP? Use firecrawl_parse for local files. Local MCP can read the file directly when configured with FIRECRAWL_API_URL. Remote hosted MCP returns a short-lived upload command first, then parses the returned uploadRef. Public document URLs should still use /scrape.

Authorization

Authorizationstringheaderrequired#

Bearer authentication header of the form Bearer <token>, where <token> is your API key.

Body

multipart/form-data

filefilerequired#

The file bytes to parse. Supported extensions: .html, .htm, .xhtml, .pdf, .docx, .doc, .docm, .odt, .ods, .odp, .rtf, .xlsx, .xls, .xlsm, .xlsb, .pptx, .ppt, .pptm, .epub, .csv.

optionsobject#

Optional parse options sent as JSON in the multipart options field.

Show child attributes

formatsobject[]#

Output formats supported for /parse uploads. Browser-rendering formats and change tracking are not supported.

Default: ["markdown"]

Show child attributes

One of

typeenum<string>required#

Options:markdown

typeenum<string>required#

Options:summary

typeenum<string>required#

Options:html

typeenum<string>required#

Options:rawHtml

typeenum<string>required#

Options:links

typeenum<string>required#

Options:images

typeenum<string>required#

Options:json

schemaobject#

The schema to use for the JSON output. Must conform to JSON Schema.

promptstring#

The prompt to use for the JSON output

onlyMainContentboolean#

Only return the main content of the page excluding headers, navs, footers, etc.

Default: true

includeTagsstring[]#

Tags to include in the output.

excludeTagsstring[]#

Tags to exclude from the output.

headersobject#

Headers to send when additional network requests are required.

timeoutinteger#

Timeout in milliseconds for the request. Default is 30000 (30 seconds). Maximum is 300000 (300 seconds).

Default: 30000

Range: <= 300000

parsersobject[]#

Controls file parser behavior when relevant (for example PDF parser mode).

Default: ["pdf"]

Show child attributes

One of

typeenum<string>required#

Options:pdf

modeenum<string>#

PDF parsing mode. "fast": text-only extraction. "auto": text-first with OCR fallback. "ocr": OCR on every page.

Default: "auto"

Options:fastautoocr

maxPagesinteger#

Maximum number of pages to parse from the PDF.

Range: 1–10000

pagesboolean#

Include physical per-page markdown alongside the document markdown. Populates the pages field on the document as an array of { pageNumber, markdown }. No additional cost.

Default: false

blocksboolean#

Include per-page typed layout blocks alongside the document markdown. Populates the blocks field on the document: typed blocks (title, section_header, text, table, formula, figure, caption, ...) with normalized bounding boxes, reading order, character-span links into the markdown, and per-block confidence. No additional cost.

Default: false

pageMarkersboolean#

Annotate page breaks in the document markdown: pages are joined with \n\n---\n\n\n\n, where N is the 1-based physical page of the content that follows. Markers appear between pages only (no leading marker for page 1), and numbering may skip pages merged across a page break — use pages: true when every physical page is needed. No new response field; no additional cost.

Default: false

skipTlsVerificationboolean#

Skip TLS certificate verification when making requests.

Default: true

removeBase64Imagesboolean#

Remove base64-encoded images from output and keep alt text placeholders.

Default: true

blockAdsboolean#

Enable ad and cookie popup blocking.

Default: true

redactPIIboolean · object#

Redact personally identifiable information from returned markdown. Pass true to use defaults, or an object to tune mode, entities, and replacement style.

Default: false

Show child attributes

One of

modeenum<string>#

Redaction strategy. accurate is model-only and optimized for precision, aggressive increases recall with additional heuristics, and fast uses heuristics without the model call.

Default: "accurate"

Options:accurateaggressivefast

entitiesenum<string>[]#

Restrict redaction to these entity buckets. If omitted, all supported entities are redacted.

replaceStyleenum<string>#

tag replaces spans with placeholders like <EMAIL>, mask replaces characters with *, and remove deletes the span text.

Default: "tag"

Options:tagmaskremove

proxyenum<string>#

Proxy mode for parse uploads. /parse supports only basic and auto.

Options:basicauto

originstring#

Origin identifier for analytics and logging.

Default: "api"

integrationstring#

Optional integration identifier.

auditMetadataobject#

User attribution included with SIEM logging events when SIEM Logging is enabled for the organization.

Show child attributes

usernamestringrequired#

The username associated with the request.

Length: max 1024

zeroDataRetentionboolean#

If true, this will enable zero data retention for this parse. To enable this feature, please contact help@firecrawl.dev

Default: false

Responses

application/json

Successful response

successboolean#

dataobject#

Show child attributes

markdownstring#

pagesobject[]#

Physical per-page markdown for PDFs. Present only when the request set the pages PDF parser option.

Show child attributes

pageNumberinteger#

1-based physical PDF page number.

markdownstring#

blocksobject[]#

Per-page typed layout blocks for PDFs. Present only when the request set the blocks PDF parser option.

Show child attributes

pageNumberinteger#

1-based physical PDF page number.

widthnumber#

Page render width in px — the anchor for denormalizing bbox coordinates. Null for pages that never rendered.

heightnumber#

Page render height in px. Null for pages that never rendered.

statusstring#

Page-level rollup: ok | partial | failed.

itemsobject[]#

Show child attributes

idstring#

Stable within a response: p<page>.b<index in reading order>.

typestring#

Block type: title, section_header, text, table, formula, figure, caption, page_number, page_header, page_footer. New types may appear over time.

labelstring#

Raw layout-model label, passthrough for forward compatibility.

bboxnumber[]#

[x0, y0, x1, y1] normalized 0-1 relative to the page width/height. Multiply by the page width/height to get pixel coordinates. Null when the page has no known dimensions.

Items: 4–4

contentstring#

Markdown fragment this block contributed to the document markdown.

markdownSpaninteger[]#

[start, end) character offsets into the document markdown covering this block's fragment. Null when a post-processing transform rewrote the fragment.

Items: 2–2

readingOrderinteger#

sourcestring#

Pipeline path that produced the block (for example native_text, layout_ocr, tsr, formula_model, full_page).

confidenceobject#

Show child attributes

layoutnumber#

Layout-model detection score (0-1). Null when the page bypassed layout analysis.

ocrnumber#

Text confidence when the source path provides one; null otherwise.

summarystring#

Summary of the page if summary is in formats

htmlstring#

Cleaned HTML of the page if html is in formats. Removes <script>, <style>, <noscript>, <meta>, and <head> tags; converts relative URLs to absolute; resolves responsive image srcset to the largest version. Respects onlyMainContent, includeTags, and excludeTags filters.

rawHtmlstring#

The exact, unmodified HTML as received from the page if rawHtml is in formats. No cleaning or filtering is applied.

rawBase64string#

The Base64-encoded original HTTP response body if rawBase64 is in formats. A bare Base64 string, not a data URI. The MIME type is in metadata.contentType.

screenshotstring#

Screenshot of the page if screenshot is in formats. Screenshots expire after 24 hours and can no longer be downloaded.

audiostring#

Signed URL to the extracted MP3 audio file if audio is in formats. The signed URL expires after 1 hour.

videostring#

Signed URL to the extracted video file if video is in formats. The signed URL expires after 1 hour.

answerstring#

Natural-language answer to the question supplied via the question format. Only present if a question format object was included in formats.

highlightsstring#

Relevant source text selected by the highlights format. Only present if a highlights format object was included in formats.

linksstring[]#

List of links on the page if links is in formats

actionsobject#

Results of the actions specified in the actions parameter. Only present if the actions parameter was provided in the request

Show child attributes

screenshotsstring[]#

Screenshot URLs, in the same order as the screenshot actions provided.

scrapesobject[]#

Scrape contents, in the same order as the scrape actions provided.

Show child attributes

urlstring#

htmlstring#

javascriptReturnsobject[]#

JavaScript return values, in the same order as the executeJavascript actions provided.

Show child attributes

typestring#

valueany#

pdfsstring[]#

PDFs generated, in the same order as the pdf actions provided.

metadataobject#

Show child attributes

titlestring · string[]#

Title extracted from the page, can be a string or array of strings

Show child attributes

One of

descriptionstring · string[]#

Description extracted from the page, can be a string or array of strings

Show child attributes

One of

languagestring · string[]#

Language extracted from the page, can be a string or array of strings

Show child attributes

One of

sourceURLstring#

The original URL that was requested. May differ from the page's final URL if redirects occurred.

urlstring#

The final URL of the page after all redirects have been followed.

keywordsstring · string[]#

Keywords extracted from the page, can be a string or array of strings

Show child attributes

One of

ogLocaleAlternatestring[]#

Alternative locales for the page

<any other metadata> string · string[]#

Other metadata extracted from HTML, can be a string or array of strings

Show child attributes

One of

statusCodeinteger#

The status code of the page

numPagesinteger#

For PDF inputs, the number of pages parsed (capped by the parsers maxPages option).

totalPagesinteger#

For PDF inputs, the document's true page count before any maxPages capping. Omitted when it cannot be determined; a totalPages greater than numPages indicates the result was truncated.

contentTypestring#

The content type (MIME type) of the page, e.g. text/html, application/pdf

errorstring#

The error message of the page

concurrencyLimitedboolean#

Whether this scrape was throttled due to team concurrency limits

concurrencyQueueDurationMsnumber#

Time in milliseconds the request waited in the concurrency queue. Only present when concurrencyLimited is true.

warningstring#

Can be displayed when using LLM Extraction. Warning message will let you know any issues with the extraction.

changeTrackingobject#

Change tracking information if changeTracking is in formats. Only present when the changeTracking format is requested.

Show child attributes

previousScrapeAtstring#

The timestamp of the previous scrape that the current page is being compared against. Null if no previous scrape exists.

changeStatusenum<string>#

The result of the comparison between the two page versions. 'new' means this page did not exist before, 'same' means content has not changed, 'changed' means content has changed, 'removed' means the page was removed.

Options:newsamechangedremoved

visibilityenum<string>#

The visibility of the current page/URL. 'visible' means the URL was discovered through an organic route (links or sitemap), 'hidden' means the URL was discovered through memory from previous crawls.

Options:visiblehidden

diffstring#

Git-style diff of changes when using 'git-diff' mode. Only present when the mode is set to 'git-diff'.

jsonobject#

JSON comparison results when using 'json' mode. Only present when the mode is set to 'json'. This will emit a list of all the keys and their values from the previous and current scrapes based on the type defined in the schema. Example here

brandingobject#

Branding information extracted from the page if branding is in formats. Includes colors, fonts, typography, spacing, components, and more.

Show child attributes

colorSchemeenum<string>#

The detected color scheme of the page.

Options:lightdark

logostring#

URL of the primary logo.

colorsobject#

Brand colors extracted from the page.

Show child attributes

primarystring#

Primary brand color (hex).

secondarystring#

Secondary brand color (hex).

accentstring#

Accent color (hex).

backgroundstring#

Background color (hex).

textPrimarystring#

Primary text color (hex).

textSecondarystring#

Secondary text color (hex).

linkstring#

Link color (hex).

successstring#

Success/positive color (hex).

warningstring#

Warning color (hex).

errorstring#

Error/danger color (hex).

fontsobject[]#

Array of font families used on the page.

Show child attributes

familystring#

Font family name.

typographyobject#

Detailed typography information.

Show child attributes

fontFamiliesobject#

Font families by role.

Show child attributes

primarystring#

Primary font family.

headingstring#

Heading font family.

codestring#

Code/monospace font family.

fontSizesobject#

Font sizes for different text levels.

Show child attributes

h1string#

h2string#

h3string#

bodystring#

fontWeightsobject#

Font weight definitions.

Show child attributes

lightinteger#

regularinteger#

mediuminteger#

boldinteger#

lineHeightsobject#

Line height values for different text types.

Show child attributes

headingstring#

bodystring#

spacingobject#

Spacing and layout information.

Show child attributes

baseUnitinteger#

Base spacing unit in pixels.

borderRadiusstring#

Default border radius.

paddingobject#

Padding values.

marginsobject#

Margin values.

componentsobject#

UI component styles.

Show child attributes

buttonPrimaryobject#

Primary button styles.

Show child attributes

backgroundstring#

textColorstring#

borderRadiusstring#

buttonSecondaryobject#

Secondary button styles.

Show child attributes

backgroundstring#

textColorstring#

borderColorstring#

borderRadiusstring#

inputobject#

Input field styles.

iconsobject#

Icon style information.

imagesobject#

Brand images.

Show child attributes

logostring#

Logo image URL.

faviconstring#

Favicon URL.

ogImagestring#

Open Graph image URL.

animationsobject#

Animation and transition settings.

layoutobject#

Layout configuration (grid, header/footer heights).

personalityobject#

Brand personality traits (tone, energy, target audience).

productobject#

Product information extracted from the page if product is in formats. Includes title, brand, category, description, and variants. Pricing, availability, and images live on each variant.

Show child attributes

titlestringrequired#

The product title.

brandstring#

The product brand or manufacturer.

categorystring#

The product category, optionally as a breadcrumb path (e.g. 'Electronics > Audio > Headphones').

urlstringrequired#

The canonical URL of the product page.

descriptionstring#

The product description.

variantsobject[]required#

Product variants (e.g. different colors or sizes).

Show child attributes

idstring#

The variant identifier.

skustring#

The variant SKU.

titlestring#

The variant title.

valuesobject#

The variant option values (e.g. { "color": "Black" }).

Show child attributes

{key}string#

priceobject#

The current price of the variant.

Show child attributes

amountnumberrequired#

The numeric price amount.

currencystring#

The ISO 4217 currency code (e.g. 'USD').

formattedstring#

The price formatted for display (e.g. '$199.99').

saleobject#

Sale/discount information for the variant, present when the variant is discounted.

Show child attributes

originalPriceobjectrequired#

The original (pre-discount) price of the variant.

Show child attributes

amountnumberrequired#

The numeric price amount.

currencystring#

The ISO 4217 currency code (e.g. 'USD').

formattedstring#

The price formatted for display (e.g. '$249.99').

availabilityobjectrequired#

The availability of the variant. Always present on a variant.

Show child attributes

inStockbooleanrequired#

Whether the variant is in stock.

textstring#

Human-readable availability text (e.g. 'In Stock').

imagesobject[]#

Variant images.

Show child attributes

urlstringrequired#

Image URL.

altstring#

Alternative text for the image.

menuobject#

Menu information extracted from the page if menu is in formats. Includes the merchant, currency, and a list of sections, where each section carries items with description, images, price, availability, dietary tags, calories, and option groups.

Show child attributes

sectionsobject[]required#

Menu sections (e.g. 'Appetizers', 'Entrees').

Show child attributes

itemsobject[]required#

The items in the section.

Show child attributes

Map Crawl

When to use /parse#

Authorization

Body

Responses

When to use `/parse`#