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

# File Downloads

> Build APIs that hand back downloadable files — list documents, download PDFs, and more

<Note>
  File downloads are in **closed beta**. The feature is off by default and enabled per account. Want in? [Submit your interest here](https://forms.gle/FKZx2i41Fj8YM7qL9) and we'll reach out.
</Note>

Parse endpoints normally return JSON. **File-download endpoints** let an API hand back an actual file — a PDF, spreadsheet, image, or ZIP — from sites that expose documents. A common shape is one endpoint that **lists** the documents on a portal and another that **downloads** a specific one.

## How it works

File downloads are **passthrough** — Parse never stores your files. When a file endpoint runs, it doesn't pull the bytes into Parse. It returns the document's metadata plus a **one-time, short-lived download URL**. When you fetch that URL, Parse streams the file straight through to you and keeps nothing.

* **One-time.** Each link works once.
* **Short-lived.** It expires about 8 minutes after it's created.
* **Any file type, up to 50 MB.**
* **Nothing at rest.** No file bytes are ever stored by Parse.

## Building a file API

Once your account is enabled for the beta, just ask for it in plain language when you create or revise an API — for example:

> *"List the statements on my account and let me download each one as a PDF."*

The build agent will add the file endpoints automatically. Over the API and MCP you can also set `allow_downloads: true` on a build to request it explicitly, but on an enabled account it isn't required.

## Calling a file endpoint

A file endpoint returns a `file` object in its result — either at the top level for a single document, or one per item in a list.

Single document:

```json theme={null}
{
  "status": "success",
  "data": {
    "title": "March 2026 Statement",
    "file": {
      "download_url": "https://api.parse.bot/files/AbC123...",
      "filename": "statement-2026-03.pdf",
      "content_type": "application/pdf",
      "size_bytes": 248310,
      "expires_at": "2026-08-14T21:08:00Z",
      "single_use": true
    }
  }
}
```

A list of documents, one `file` per item:

```json theme={null}
{
  "status": "success",
  "data": [
    { "title": "Invoice A", "file": { "download_url": "https://api.parse.bot/files/...", "filename": "invoice-a.pdf" } },
    { "title": "Invoice B", "file": { "download_url": "https://api.parse.bot/files/...", "filename": "invoice-b.pdf" } }
  ]
}
```

## Downloading the file

Fetch the `download_url` with your **API key** — the same `X-API-Key` you call endpoints with:

```bash theme={null}
curl -L "https://api.parse.bot/files/AbC123..." \
  -H "X-API-Key: YOUR_API_KEY" \
  -o statement.pdf
```

In the [dashboard](https://parse.bot), a file result renders a **Download** button — click it and the file downloads in your browser.

<Note>
  Don't paste the download URL into a browser tab directly — it needs your API key. The dashboard's Download button and an authenticated request both send it; a plain browser navigation doesn't, and will return a 404.
</Note>

The link is single-use and expires, so treat it as a fresh handle each time:

* Download it once, promptly.
* If you get an expired or `404` response, **call the endpoint again** for a new link. Re-fetching a spent URL won't work.

## Documents behind a login

File endpoints work for public documents and for documents behind a login. When the documents require an account, the file endpoint rides the same authenticated session as an [Authenticated API](/authenticated-apis): the download replays through the same logged-in, IP-consistent session, and that session's credentials are only ever sent to the site they were earned on — never to a different host.

## Privacy

Like authenticated APIs, **an API with file endpoints is always private to your account.** It's never contributed to the public marketplace and never shared — a file endpoint hands back your documents, so the API that produces it stays yours.

## During the beta

* **Free.** File downloads don't incur additional charges during the beta.
* **Off by default.** The feature is enabled per account — [submit your interest](https://forms.gle/FKZx2i41Fj8YM7qL9) to join.