# Convert a PDF from a link

> POST /v1/fetch-pdf downloads a PDF from a URL and converts it like an uploaded PDF, for the PDF price plus a small download fee.

`POST /v1/fetch-pdf` downloads a PDF from a URL and converts it exactly like a PDF sent to [`/v1/convert`](https://md.tlelabs.com/docs/convert/), with the same OCR options. It costs the PDF price plus 5 credits for the download. For a web page, use [`/v1/fetch`](https://md.tlelabs.com/docs/fetch/).

```sh
curl -X POST https://api.md.tlelabs.com/v1/fetch-pdf \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf", "ocr": "auto"}'
```

## Request

`Content-Type: application/json`, a JSON object of at most 2 MiB:

| Field             | Required | Value                                                                                                            |
| ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `url`             | yes      | An `http` or `https` URL without user name or password, on a public host (not `localhost` or a private address). |
| `ocr`             | no       | `auto` (default), `force` or `off`, as for [`/v1/convert`](https://md.tlelabs.com/docs/convert/#ocr-modes).      |
| `ocr_model`       | no       | `auto` (default) or a model id ([OCR models](https://md.tlelabs.com/docs/ocr-models/)).                          |
| `preserve_images` | no       | `true` (default) or `false`.                                                                                     |

A field of the wrong type or value gets `400 invalid_request` with `details.field`.

## Download

- With fewer than 6 credits available (the fee and one page) you get `402 insufficient_credits` before anything is downloaded.
- The file is downloaded without cookies or a login. Redirects are followed, up to 20 redirects, and every one is checked like the URL you sent (`400 invalid_url` when refused, `422 too_many_redirects` after 20).
- The first bytes must be a PDF header: anything else gets `415 unsupported_content` and the download stops.
- Files over 50 MB get `413 file_too_large`.
- An HTTP error from the server gets `422 fetch_failed` with `details.http_status`; a server that cannot be reached gets `502 fetch_failed`; one that sends nothing for 30 seconds gets `504 fetch_timeout`.

Every download error happens before credits are reserved: it is not charged.

## Price

After the download the PDF is priced like an upload ([Formats and pricing](https://md.tlelabs.com/docs/formats-and-pricing/#pricing)). The most it can cost plus 5 is reserved; you are charged for the pages actually converted plus 5. A conversion that fails releases the reservation and is not charged.

## Response

The same as [`/v1/convert`](https://md.tlelabs.com/docs/convert/) (`format: "pdf"`), with:

| Field                      | Meaning                                                    |
| -------------------------- | ---------------------------------------------------------- |
| `usage.processing_credits` | The download fee (5), included in `usage.credits_charged`. |
| `metadata.url`             | The URL you sent.                                          |
| `metadata.final_url`       | The URL of the file after redirects.                       |

With `Accept: text/markdown` the body is the Markdown with the headers of `/v1/convert` plus `X-Processing-Credits` and `X-Final-Url`.

## Errors

The errors of [`/v1/convert`](https://md.tlelabs.com/docs/convert/) for a PDF, and:

| Status | Code                                  | When                                                                                                   |
| ------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| 400    | `invalid_url`                         | The URL or a redirect is not `http`/`https`, has credentials, or points to a local or private address. |
| 402    | `insufficient_credits`                | Not enough credits for the fee and one page (before the download) or for the reservation (after it).   |
| 413    | `request_too_large`                   | JSON body over 2 MiB.                                                                                  |
| 415    | `unsupported_content`                 | The link is not a PDF file.                                                                            |
| 422    | `fetch_failed` / `too_many_redirects` | The server answered an HTTP error / more than 20 redirects.                                            |
| 502    | `fetch_failed`                        | The server could not be reached.                                                                       |
| 504    | `fetch_timeout`                       | The server sent nothing for 30 seconds.                                                                |
