Skip to content

POST /v1/fetch-pdf downloads a PDF from a URL and converts it exactly like a PDF sent to /v1/convert, with the same OCR options. It costs the PDF price plus 5 credits for the download. For a web page, use /v1/fetch.

Terminal window
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"}'

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.
ocr_model no auto (default) or a model id (OCR models).
preserve_images no true (default) or false.

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

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

After the download the PDF is priced like an upload (Formats and 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.

The same as /v1/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.

The errors of /v1/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.