Parse Documents

Context.dev’s Parse API converts raw file bytes into clean, LLM-ready Markdown. Use it for files your users upload, files in your storage bucket, or anything else your application can read into memory. Unlike web scraping, the file doesn’t need a public URL. Context.dev detects the file type from its contents. You can also send the file’s media type and extension as hints. The response reports the type that was actually detected, which may differ from the hint.

Category	Supported formats	Markdown output
Documents	PDF, Word (`.docx`, `.doc`), and rich text (`.rtf`)	Structured sections for PDFs and DOCX files; paragraph text for legacy DOC and RTF files
Spreadsheets	Excel (`.xlsx`, `.xlsm`, `.xlsb`, `.xltx`, `.xltm`, `.xls`), CSV, and TSV	One Markdown table per sheet, or a fenced block when delimited data can’t be read as a table
Presentations	PowerPoint (`.pptx`, `.pptm`, `.ppsx`, `.ppsm`, `.potx`, `.potm`, `.ppt`, `.pps`, `.pot`)	Slide-by-slide sections with body text, tables, and speaker notes
Web and data	HTML, XHTML, XML, RSS, Atom, sitemaps, JSON, JSON Lines, NDJSON, YAML, and SVG	Structured Markdown for HTML and XML; fenced blocks for JSON, YAML, and SVG markup
Text and code	Plain text, Markdown, SRT, Python, JavaScript, TypeScript, Java, PHP, Ruby, shell, CSS, SCSS, Less, Stylus, and Sass	Text is preserved; source code is returned in a language-tagged fenced block
Images	JPEG, PNG, GIF, BMP, TIFF, WebP, PBM, PGM, PPM, and PNM	Format and dimensions by default; extracted text when `ocr=true`

Integrate Context.dev's Parse API in your app

Open in Cursor

Prerequisites

A Context.dev API key. Sign up at context.dev/signup, copy the key from the dashboard (prefix ctxt_secret_), and export it:
export CONTEXT_DEV_API_KEY="ctxt_secret_..."

The endpoint accepts raw bytes over HTTPS, so you can call it from any language. The examples below use curl.

Convert a file to Markdown

Send the file itself as the request body. --data-binary keeps curl from changing the bytes:

cURL

curl -X POST "https://api.context.dev/v1/parse?extension=pdf" \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

1 credit per successful conversion without OCR output The request stays open while the file is converted; there is nothing to poll.

Request parameters

The request body is required and can contain up to 25 MiB. Send the file’s actual Content-Type header when you know it, especially for text that uses a character encoding other than UTF-8. All parsing options are query parameters:

Parameter	Type	Default	Description
`extension`	string	none	File-type hint such as `pdf`, `.docx`, `xlsx`, or `csv`. It is case-insensitive and may include a leading dot.
`includeLinks`	boolean	`true`	Preserve hyperlinks in HTML, XML feeds and sitemaps, and Office content.
`includeImages`	boolean	`false`	Include image references when converting HTML and Office content.
`shortenBase64Images`	boolean	`true`	Shorten inline base64 image data so it doesn’t dominate the Markdown.
`useMainContentOnly`	boolean	`false`	Remove navigation, headers, footers, and sidebars from HTML and Office content when present.
`ocr`	boolean	`false`	Read scanned or embedded images in PDFs. For raster images, extract visible text into an `## Extracted text` section.
`pdf`	object	full document	PDF-only page range with optional `start` and `end` values. Pages are 1-based and the range is inclusive; `end` must be greater than or equal to `start`.

Query parameters are validated strictly. Unrecognized parameters and repeated scalar parameters return a 400 response.

Because a parsed file has no source URL, relative links and image paths remain relative in the output.

Response

{
  "success": true,
  "markdown": "# Quarterly Report\n\n## Summary\n\nRevenue grew 24% quarter over quarter…",
  "type": "pdf",
  "key_metadata": {
    "credits_consumed": 1,
    "credits_remaining": 499
  }
}

Field	Type	Description
`success`	boolean	`true` when the file was converted.
`markdown`	string	The converted Markdown.
`type`	string	The detected file type, such as `pdf`, `docx`, `xlsx`, `html`, `csv`, or `png`.
`key_metadata.credits_consumed`	integer	Credits charged for this request.
`key_metadata.credits_remaining`	integer	Credits left after the request.

Some extensions share a normalized response type. For example, .xlsm reports xlsx, .ppsx reports pptx, and .jpeg reports jpg.

Read PDFs and images with OCR

OCR is off by default. Without OCR, PDFs are converted from their selectable text layer. A scanned PDF with no selectable text returns a 400 response unless you set ocr=true. With ocr=true, Context.dev can read scanned PDF pages and text inside embedded images such as charts, screenshots, and stamps. Use the nested pdf page range to convert only the pages you need:

cURL

curl -X POST "https://api.context.dev/v1/parse?extension=pdf&ocr=true&pdf%5Bstart%5D=1&pdf%5Bend%5D=5" \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @scanned-contract.pdf

In the URL above, pdf%5Bstart%5D and pdf%5Bend%5D are the URL-encoded forms of pdf[start] and pdf[end]. You can also send pdf as a URL-encoded JSON object such as {"start":1,"end":5}. The same ocr=true parameter works for raster images. Without it, an image returns Markdown containing its format and dimensions. With it, the response adds an ## Extracted text section containing text transcribed from the image. Image OCR is text-only — visual content that isn’t text is not described.

Requests with ocr=true require at least 5 available credits. A successful request costs 5 credits only when OCR contributes text; otherwise it costs 1 credit. Failed parsing and validation requests consume 0 credits. Check key_metadata.credits_consumed for the actual charge.

Convert a spreadsheet or document

Point --data-binary at any supported file and pass its extension when useful. Excel workbooks become one Markdown table per non-empty sheet. DOCX files preserve headings, lists, and tables, while legacy DOC files return paragraph text.

cURL

curl -X POST "https://api.context.dev/v1/parse?extension=xlsx" \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  -H "Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" \
  --data-binary @Q3-forecast.xlsx

1 credit per successful conversion

Handle errors

Error responses include an error_code that distinguishes invalid input from files with no extractable content.

Status	`error_code`	Meaning	What to do
400	`INPUT_VALIDATION_ERROR`	The body is empty or a query parameter is invalid.	Attach the raw file bytes and use only the documented query parameters.
400	`WEBSITE_ACCESS_ERROR`	The file type was detected, but no content could be extracted.	Check that the file isn’t blank or corrupt. For scanned PDFs, retry with `ocr=true`; for a page range, confirm the pages exist.
401	Authentication or usage error	The API key is missing or invalid, or the account can’t cover the required credits.	Check the environment variable and available balance. OCR-enabled requests require at least 5 available credits.
403	`FORBIDDEN`	The authenticated account isn’t allowed to complete the request.	Confirm that the key belongs to an active workspace with access to the API.
413	`INPUT_VALIDATION_ERROR`	The body is larger than 25 MiB.	Reduce or split the file before uploading it. A PDF page range doesn’t reduce the uploaded file size.
415	`UNSUPPORTED_CONTENT`	The bytes couldn’t be identified as a supported file type.	Check that the file is valid and supported, then provide its `extension` and `Content-Type` as hints.
429	`RATE_LIMITED`	The API-key rate limit was exceeded.	Wait for the rate-limit window to reset, then retry with backoff.

Use cases

Let users upload a PDF, Word document, or spreadsheet and send the resulting Markdown to an LLM.
Normalize a folder of mixed documents, decks, spreadsheets, and images before adding them to a RAG index.
Extract text from scanned contracts and invoices without operating a separate OCR service.
Turn uploaded images and screenshots into searchable text and descriptions.

Next steps

Scrape Websites

Have a URL instead of a file? Turn any page into clean Markdown.

Extract Structured Data

Pull schema-shaped data out of websites and linked documents.

Best Practices

Caching, error handling, and key hygiene.

Handle Rate Limits

Backoff strategies and pacing for high-volume jobs.

Get Started

Give it to your Agent

What can Context.dev do

Optimizations

No-code Integrations

Prerequisites

Convert a file to Markdown

Request parameters

Response

Read PDFs and images with OCR

Convert a spreadsheet or document

Handle errors

Use cases

Next steps

Scrape Websites

Extract Structured Data

Best Practices

Handle Rate Limits

​Prerequisites

​Convert a file to Markdown

​Request parameters

​Response

​Read PDFs and images with OCR

​Convert a spreadsheet or document

​Handle errors

​Use cases

​Next steps

Scrape Websites

Extract Structured Data

Best Practices

Handle Rate Limits

Prerequisites

Convert a file to Markdown

Request parameters

Response

Read PDFs and images with OCR

Convert a spreadsheet or document

Handle errors

Use cases

Next steps