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

# Large files

> Upload a file of up to 36 MB to a one-time address, then parse it with its upload id. Use it when a base64 body is too big. Needs an API key.

Use an upload when you do not want a large file inside the JSON body. Get an address, `PUT` the raw bytes to it (no base64), then pass the `uploadId` to [Parse](https://docs.stophy.dev/parse/overview) as `uploadRef`. Needs an API key. Get one in the [Quickstart](https://docs.stophy.dev/quickstart.md).

```bash cURL theme={null}
UPLOAD=$(curl -s -X POST https://api.stophy.dev/v1/parse/upload-url \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "report.pdf",
    "contentType": "application/pdf",
    "declaredSizeBytes": '"$(wc -c < report.pdf)"'
  }')
UPLOAD_URL=$(echo "$UPLOAD" | jq -r .uploadUrl)
UPLOAD_ID=$(echo "$UPLOAD" | jq -r .uploadId)

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

curl -X POST https://api.stophy.dev/v1/parse \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadRef": "'"$UPLOAD_ID"'",
    "parsers": [{ "type": "pdf", "pages": true }]
  }'
```

The first call returns `uploadUrl`, `uploadId`, `expiresAt` and `maxBytes`. Keep the URL private. The `PUT` answers an empty `200`. The parse answer is the one in [Parse](https://docs.stophy.dev/parse/overview), here with `data.pages`.

| Field of the first call | Effect |
| - | - |
| `filename` | The file's name, up to 255 characters. Used when the parse call sends none. |
| `contentType` | The file type, such as `application/pdf`. Send the same `Content-Type` in the `PUT`. |
| `declaredSizeBytes` | The size in bytes, 1 to 37,748,736 (36 MB). |

`POST /v1/parse` takes `uploadRef` in place of `file`, and every other field works the same.

## Limits

* `PUT` within 15 minutes of getting the address, and parse within 1 hour.
* Each `uploadId` parses once. The file is deleted when the parse ends, and a repeat or late parse returns `404 notFound`.
* Parsing before the `PUT` returns `400 invalidRequest`. A file over 36 MB returns `400` and the upload is deleted.
* `uploadRef` without a key returns `400 invalidRequest`.

Getting the address is free. See [Pricing](https://docs.stophy.dev/account/pricing.md) for the parse.


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