Skip to main content
Parse turns a file you hold into Markdown. Send the file’s bytes as base64 in a JSON body.

Make a request

Get an API key in the Quickstart. This request parses a tiny HTML file. To send a file from disk, encode it first, for example with base64 -w0 report.pdf.
You can try Parse without an API key, up to 10 calls a minute and 50 calls a day per IP address, with files up to 2 MB. Summaries, json and reading every page’s picture need an API key. See Rate limits.

Read the response

data.markdown holds the text of the file. data.metadata describes the file.
metadata.contentType is the type Stophy found in the file, whatever its name says. A PDF also has numPages and pagesRead, and ocrPages counts the pages read from their picture. isTruncated is true when the file had more pages than maxPages.

Formats

markdown is always returned. Ask for more with formats, a list of up to 8. PDF page options, such as pages, blocks and the reading mode, are in Formats.

Request fields

The same fields can sit inside an options object. The full field list is in the API reference.

Limits and errors

  • A file can be up to 36 MB with an API key, and up to 2 MB without one. A larger file returns 400 invalidRequest. Send a large file with Large files.
  • A body that is not base64 returns 400 invalidRequest with file: this is not base64. Send the file's bytes encoded as base64.
  • A file type that cannot be read returns 400 invalidRequest with file: this type of file cannot be read. and the list of types. The older .doc, .xls and .ppt formats return 400 invalidRequest: save them as .docx, .xlsx, .pptx or PDF.
  • A password-protected file returns 400 invalidRequest with file: this file is password-protected. Remove the password, then send it again.
  • A call with neither file nor uploadRef returns 400 invalidRequest with Send file, or uploadRef from POST /v1/parse/upload-url.
  • A file with no readable text comes back as a notFound error, and costs nothing.
  • Pages of a PDF with no text layer are read from their picture, up to 20 pages, with no extra charge and only with an API key.

Price

$0.50 per 1,000 pages or files whose text comes from a text layer, and $2.50 per 1,000 pages or pictures read from their picture, up to maxPages. summary and json with a schema or a prompt add $3 per 1,000 files each when they return something. Zero data retention adds $2 per 1,000 calls. costUsd shows what the call cost. See Pricing.

Choose another API

  • Scrape reads a page or a document that is online, by its address.
  • Extract pulls the fields you name from pages, each checked against the page.
  • Search finds pages from a query.
  • Agent searches and reads for you until your fields are filled.