> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Parse

> Turn a PDF, Word, Excel, PowerPoint or HTML file, or a picture of text, into Markdown. Send the file as base64, up to 36 MB, and get its text.

Parse turns a file you have into Markdown. For a file at a public URL, use [Scrape](https://docs.stophy.dev/scrape/pdfs-and-documents.md).

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/parse \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "PGgxPkhvdyB0aWRlcyB3b3JrPC9oMT4=",
    "filename": "tides.html"
  }'
```

```typescript TypeScript theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy();

const file = Buffer.from("<h1>How tides work</h1>").toString("base64");
const { data } = await stophy.parse({ file, filename: "tides.html" });
console.log(data?.markdown);
```

```python Python theme={null}
import base64

from stophy import Stophy

stophy = Stophy()

file = base64.b64encode(b"<h1>How tides work</h1>").decode()
data = stophy.parse(file=file, filename="tides.html")["data"]
print(data["markdown"])
```

Send the bytes as base64 in `file`, up to 36 MB. Encode a file from disk with `base64 -w0 report.pdf`, or send raw bytes with [Large files](https://docs.stophy.dev/parse/large-files.md). Small files also parse without a key, within the [keyless limits](https://docs.stophy.dev/production/rate-limits.md#without-a-key).

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "# How tides work",
    "metadata": { "contentType": "text/html" }
  }
}
```

The text is in `data.markdown`. `metadata.contentType` is the type read from the bytes, whatever the name says. For a PDF, `numPages` is the page count and `ocrPages` counts pages read from their picture. `data.warning` is `The file text was cut short.` when the file had more pages than `maxPages`.

## Fields

| Field | Default | What it does |
| - | - | - |
| `file` | none | The bytes as base64. A `data:` prefix is accepted. Send `file` or `uploadRef`. |
| `uploadRef` | none | The `uploadId` from [Large files](https://docs.stophy.dev/parse/large-files.md). |
| `filename` | none | A name such as `report.docx`. |
| `formats` | none | Up to 8 besides `markdown`: `summary`, `links`, `images`, `html` and `rawHtml` (HTML files only), and `json` with `schema` or `prompt`. See [Formats](https://docs.stophy.dev/scrape/formats.md) and [JSON](https://docs.stophy.dev/scrape/json.md). |
| `maxPages` | `100` | Most PDF pages, sheets or slides to read, 1 to 100. |
| `parsers` | none | One PDF entry. See [Read a PDF](#read-a-pdf). |
| `zeroDataRetention` | `false` | Keep nothing from the call. See [Zero data retention](https://docs.stophy.dev/production/zero-data-retention.md). |

These fields can also sit inside an `options` object. The full list is in the [API reference](https://docs.stophy.dev/api-reference/endpoint/parse.md).

## File types

`GET /v1/parse/formats` is free and lists each type with the `options` that apply.

| You have | You get |
| - | - |
| `.pdf` | Text of up to 100 pages. A page with no text layer is read from its picture, up to 20 pages. |
| `.docx`, `.odt` | The document text. |
| `.xlsx` | Each sheet. |
| `.pptx` | Each slide. |
| `.html`, `.htm` | The page as Markdown. |
| `.png`, `.jpg`, `.jpeg`, `.webp` | The text in the picture. |

`.doc`, `.xls`, `.ppt`, `.ods` and `.odp` are not read. Save them in a listed format.

## Read a PDF

`parsers` takes one entry: `[{ "type": "pdf", "pages": true }]`.

| Field | Default | What it does |
| - | - | - |
| `mode` | `auto` | `fast` reads the text layer only. `auto` also reads the picture of pages that have none. `ocr` reads every page's picture, up to 20 pages, and needs a key. |
| `maxPages` | `100` | Pages to read, 1 to 100. |
| `pages` | `false` | Also return `data.pages` as `{ pageNumber, markdown }`. |
| `blocks` | `false` | Also return `data.blocks`: each title, section header or run of text with its page, reading order and `bbox` (left, top, right, bottom, 0 to 1). Tables, figures and formulas are not told apart. A page read from its picture is one block. |
| `pageMarkers` | `false` | Join pages with `---` and a `<!-- page N -->` line, where N is the page that follows. |

## Read an HTML file

| Field | Default | What it does |
| - | - | - |
| `onlyMainContent` | `true` | `false` keeps navigation and footers. |
| `includeTags`, `excludeTags` | none | Keep or drop what these CSS selectors match, up to 50. |
| `removeBase64Images` | `true` | `false` keeps images that carry their data in the address. |

## Errors

| Code | Cause | Fix |
| - | - | - |
| `400 invalidRequest` | Over 36 MB, not base64, password-protected, a type that cannot be read, no `file` or `uploadRef`, an HTML option on another file, or `mode: "fast"` on a picture. | Fix what `error` names. |
| `400 invalidRequest` | `summary`, `json` or `mode: "ocr"` without a key. | Send your key. See [Get credentials](https://docs.stophy.dev/get-credentials.md). |
| `404 notFound` | No readable text. Without a key, scanned pages and pictures are not read. | Send your key, and don't use `mode: "fast"`. |

Other codes are on [Errors](https://docs.stophy.dev/api-reference/errors.md).

## Next

* [Large files](https://docs.stophy.dev/parse/large-files.md): upload raw bytes.
* [PDFs and documents](https://docs.stophy.dev/scrape/pdfs-and-documents.md): read a file at a URL.
* [JSON](https://docs.stophy.dev/scrape/json.md): get named fields from the text.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.