> ## Documentation Index
> Fetch the complete documentation index at: https://docs.context.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Parse Documents
> Convert uploaded documents, spreadsheets, presentations, images, code, and data files into clean, LLM-ready Markdown.
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; visible content when `ocr=true` |
I'm integrating Context.dev's Parse API (`POST /parse`) into my app. Help me:
1. Read the API key from the `CONTEXT_DEV_API_KEY` environment variable. Never hardcode it. Authenticate every request with a bearer token.
2. Send the raw file bytes in the request body to `https://api.context.dev/v1/parse`. Don't use multipart or JSON. Reject files larger than 25 MiB before sending them.
3. Send the file's `Content-Type` header when known, and optionally pass `extension` as a query hint. Don't send a filename in place of the extension.
4. Use the optional `includeLinks`, `includeImages`, `shortenBase64Images`, and `useMainContentOnly` query parameters to control Markdown output.
5. For PDFs, pass a 1-based inclusive page range as `pdf[start]` and `pdf[end]`. Set `ocr=true` when scanned pages or embedded images need to be read. For raster images, set `ocr=true` to transcribe visible text and describe the image.
6. Read `success`, `markdown`, `type`, and `key_metadata` from the JSON response. Use `key_metadata.credits_consumed` as the actual cost of the request.
7. Branch error handling on both HTTP status and `error_code`, including invalid input or no readable content (400), oversized files (413), unsupported content (415), and rate limits (429).
Docs: [https://docs.context.dev/guides/parse-documents](https://docs.context.dev/guides/parse-documents)
## Prerequisites
* **A Context.dev API key.** Sign up at [context.dev/signup](https://context.dev/signup), copy the key from the [dashboard](https://context.dev/dashboard) (prefix `ctxt_secret_`), and export it:
```bash theme={null}
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:
```bash cURL theme={null}
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, transcribe visible content and describe the image. |
| `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
```json theme={null}
{
"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:
```bash cURL theme={null}
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 also transcribes visible text, tables, lists, and labels in reading order and briefly describes relevant visual details.
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.
```bash cURL theme={null}
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
Have a URL instead of a file? Turn any page into clean Markdown.
Pull schema-shaped data out of websites and linked documents.
Caching, error handling, and key hygiene.
Backoff strategies and pacing for high-volume jobs.