> ## 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 documents

> Turn a PDF, Word, Excel, PowerPoint or HTML file, or a picture of text, into Markdown. Send the file as base64. From $0.50 per 1,000 pages.

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](https://docs.stophy.dev/quickstart). This request parses a tiny HTML file. To send a file from disk, encode it first, for example with `base64 -w0 report.pdf`.

```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}
const file = Buffer.from("<h1>How tides work</h1>").toString("base64");

const response = await fetch("https://api.stophy.dev/v1/parse", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ file, filename: "tides.html" }),
});
const { data } = await response.json();
console.log(data.markdown);
```

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

import requests

file = base64.b64encode(b"<h1>How tides work</h1>").decode()

response = requests.post(
    "https://api.stophy.dev/v1/parse",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={"file": file, "filename": "tides.html"},
)
data = response.json()["data"]
print(data["markdown"])
```

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](https://docs.stophy.dev/production/rate-limits.md).

## Read the response

`data.markdown` holds the text of the file. `data.metadata` describes the file.

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "# How tides work",
    "metadata": {
      "contentType": "text/html",
      "costUsd": 0.0005
    }
  },
  "costUsd": 0.0005,
  "requestId": "c8fb568b-22fb-4532-a7e7-165e22523c28"
}
```

`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.

| Format | What you get | Guide |
| - | - | - |
| `summary` | A short summary of the file | [Summary](https://docs.stophy.dev/scrape/summary.md) |
| `links`, `images` | Every link and every image address in the Markdown | [Links](https://docs.stophy.dev/scrape/links.md) |
| `html`, `rawHtml` | The cleaned HTML, or the HTML as sent. HTML files only | [HTML](https://docs.stophy.dev/scrape/html.md) |
| `json` with `schema` or `prompt` | An object in the shape you describe | [JSON](https://docs.stophy.dev/scrape/json.md) |

PDF page options, such as `pages`, `blocks` and the reading `mode`, are in [Formats](https://docs.stophy.dev/parse/formats.md).

## Request fields

| Field | Type | Default | Effect |
| - | - | - | - |
| `file` | `string` | none | The file's bytes as base64, up to 36 MB. A `data:` prefix is accepted. Send `file` or `uploadRef`. |
| `uploadRef` | `string` | none | The `uploadId` of a file you sent with [Large files](https://docs.stophy.dev/parse/large-files.md), instead of `file`. |
| `filename` | `string` | none | The file's name, such as `report.docx`. The type is read from the file itself. |
| `formats` | `array` | `[]` | What to send back besides `markdown`. |
| `maxPages` | `number` | 100 | Read at most this many PDF pages, sheets or slides, 1 to 100. |
| `parsers` | `array` | none | How to read a PDF. See [Formats](https://docs.stophy.dev/parse/formats.md). |
| `onlyMainContent`, `includeTags`, `excludeTags`, `removeBase64Images` | | | Shape the Markdown of an HTML file. See [Formats](https://docs.stophy.dev/parse/formats.md). |
| `zeroDataRetention` | `boolean` | `false` | Keep nothing from the call. Adds \$2 per 1,000 calls. See [Zero data retention](https://docs.stophy.dev/production/zero-data-retention.md). |

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

## 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](https://docs.stophy.dev/parse/large-files.md).
* 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](https://docs.stophy.dev/account/pricing.md).

## Choose another API

* [Scrape](https://docs.stophy.dev/scrape/pdfs-and-documents.md) reads a page or a document that is online, by its address.
* [Extract](https://docs.stophy.dev/extract/overview) pulls the fields you name from pages, each checked against the page.
* [Search](https://docs.stophy.dev/search/overview) finds pages from a query.
* [Agent](https://docs.stophy.dev/agent/overview) searches and reads for you until your fields are filled.


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