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

# Formats

> List the file types Parse reads with GET /v1/parse/formats, and choose how PDFs, HTML files and pictures are read. Listing formats is free.

Parse reads PDF, Word, OpenDocument, Excel, PowerPoint and HTML files, and pictures of text. `GET /v1/parse/formats` lists them, and `parsers` and a few other fields change how a file is read.

## List the formats

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). The call is free.

```bash cURL theme={null}
curl https://api.stophy.dev/v1/parse/formats \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/parse/formats", {
  headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}` },
});
const { data } = await response.json();
console.log(data.formats.map((format) => format.name));
```

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

import requests

response = requests.get(
    "https://api.stophy.dev/v1/parse/formats",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
)
print([format["name"] for format in response.json()["data"]["formats"]])
```

## Read the response

`data.formats` has one entry for each kind of file. This real response is cut to two of its seven entries.

```json theme={null}
{
  "success": true,
  "data": {
    "formats": [
      {
        "format": "pdf",
        "kind": "document",
        "extensions": [".pdf"],
        "mimeTypes": ["application/pdf"],
        "available": true,
        "name": "pdf",
        "types": [".pdf", "application/pdf"],
        "options": ["formats", "zeroDataRetention", "parsers"],
        "note": "Up to 100 pages; pages with no text layer are read from their picture, up to 20."
      },
      {
        "format": "html",
        "kind": "document",
        "extensions": [".html", ".htm"],
        "mimeTypes": ["text/html"],
        "available": true,
        "name": "html",
        "types": [".html", ".htm", "text/html"],
        "options": ["formats", "zeroDataRetention", "onlyMainContent", "includeTags", "excludeTags", "removeBase64Images"],
        "note": "html and rawHtml formats and the tag options apply to HTML files only."
      }
    ]
  }
}
```

`options` names the request fields that apply to that kind of file. `kind` is `document` or `image`. Parse finds the type from the bytes of the file, so `filename` is only a hint.

| Format | Extensions | What you get |
| - | - | - |
| `pdf` | `.pdf` | The text of up to 100 pages. A page with no text layer is read from its picture, up to 20 pages. |
| `docx` | `.docx` | The text of the document. The older `.doc` format is not read. |
| `odt` | `.odt` | The text of an OpenDocument text file. `.ods` and `.odp` are not read. |
| `xlsx` | `.xlsx` | Each sheet. The older `.xls` format is not read. |
| `pptx` | `.pptx` | Each slide. The older `.ppt` format is not read. |
| `html` | `.html`, `.htm` | The page as Markdown. The `html` and `rawHtml` formats and the tag options apply to HTML files only. |
| `image` | `.png`, `.jpg`, `.jpeg`, `.webp` | The text in the picture, read with OCR. |

## Read a PDF

`parsers` takes one entry for a PDF. Other files ignore it.

| Field | Type | Default | Effect |
| - | - | - | - |
| `parsers[].type` | `string` | none | `"pdf"`. Required. |
| `parsers[].mode` | `string` | `auto` | `fast` reads the text layer only. `auto` reads the text layer and the picture of any page that has none. `ocr` reads the picture of every page, up to 20 pages, and needs an API key. |
| `parsers[].maxPages` | `number` | 100 | Read at most this many pages, 1 to 100. |
| `parsers[].pages` | `boolean` | `false` | Also return each page's Markdown in `data.pages`, as `{ pageNumber, markdown }`. No extra charge. |
| `parsers[].blocks` | `boolean` | `false` | Also return the layout in `data.blocks`: each title, section header or run of text, with its page, reading order and position (`bbox` as left, top, right and bottom, from 0 to 1). Tables, figures and formulas are not told apart. A page read from its picture is one block. No extra charge. |
| `parsers[].pageMarkers` | `boolean` | `false` | Mark page breaks in the Markdown: pages are joined with `---` and a `<!-- page N -->` line, where N is the page that follows. No extra charge. |

`mode: "fast"` on a picture returns `400 invalidRequest`, because a picture has no text layer. See a PDF read page by page in [Large files](https://docs.stophy.dev/parse/large-files.md#read-the-response).

## Read an HTML file

| Field | Type | Default | Effect |
| - | - | - | - |
| `onlyMainContent` | `boolean` | `true` | Send `false` to keep navigation and footers. |
| `includeTags` | `array of string` | none | Keep only what these CSS selectors match, up to 50. |
| `excludeTags` | `array of string` | none | Drop what these CSS selectors match, up to 50. |
| `removeBase64Images` | `boolean` | `true` | Send `false` to keep images that carry their data in the address. |

`includeTags`, `excludeTags`, `html` and `rawHtml` on a file that is not HTML return `400 invalidRequest` with `includeTags, excludeTags, html and rawHtml apply to HTML files, and this file is not one`.

## Limits and errors

* Up to 36 MB for a file, and 2 MB without an API key. A password-protected file and a file that cannot be opened return `400 invalidRequest`.
* A PDF is read up to 100 pages. `isTruncated` says when the file had more.
* Without an API key, scanned pages and pictures of text are not read, and `mode: "ocr"`, `summary` and `json` return `400 invalidRequest`.
* A file with no readable text comes back as a `notFound` error and costs nothing.

## Related

* [Parse documents](https://docs.stophy.dev/parse/overview) sends a file and lists every field.
* [Large files](https://docs.stophy.dev/parse/large-files.md) sends a file up to 36 MB.
* [PDFs and documents](https://docs.stophy.dev/scrape/pdfs-and-documents.md) reads a file by its address.
* [HTML](https://docs.stophy.dev/scrape/html.md) covers the HTML formats.


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