Endpoints

Every route takes a POST with multipart/form-data and answers with the file. Files go in form parts named files; options are plain form fields. The base URL is https://api.pdfdispatch.com. The older paths under /v1/forms/... keep working, so code written for them does not have to change.

Routes

Convert to PDF

Screenshots

The same as the HTML, URL and Markdown routes above, with screenshot in place of convert: /v1/screenshot/html, /v1/screenshot/url and /v1/screenshot/markdown. They answer with a PNG, JPEG or WebP image (form field format).

Edit PDFs

Each successful request to any of these routes counts as one PDF (what counts).

Headers

HTML to PDF

Send one file named index.html. Other files of the same request (CSS, images, fonts) can be linked from it by their file name, for example <link rel="stylesheet" href="style.css">.

curl https://api.pdfdispatch.com/v1/convert/html \
  --header "Authorization: Bearer $PDD_KEY" \
  --header "Output-Filename: invoice-1042" \
  --form files=@index.html \
  --form files=@style.css \
  --form files=@logo.png \
  --form paperWidth=8.27 \
  --form paperHeight=11.7 \
  --form printBackground=true \
  --output invoice-1042.pdf

A page header and footer: add files named header.html and footer.html; they are repeated on every page.

URL to PDF

Chromium opens the page as a browser would, JavaScript included. The page must be on the public internet.

curl https://api.pdfdispatch.com/v1/convert/url \
  --header "Authorization: Bearer $PDD_KEY" \
  --form url=https://example.com/report \
  --form waitForSelector="#chart-ready" \
  --output report.pdf

Markdown to PDF

Send an index.html that names the Markdown files with {{ toHTML "file.md" }}, and the Markdown files.

curl https://api.pdfdispatch.com/v1/convert/markdown \
  --header "Authorization: Bearer $PDD_KEY" \
  --form files=@index.html \
  --form files=@notes.md \
  --output notes.pdf

Office files to PDF

Word, Excel, PowerPoint, OpenDocument, RTF, plain text and many more. Several files in one request come back as a ZIP of PDFs, or as one PDF with merge=true.

curl https://api.pdfdispatch.com/v1/convert/office \
  --header "Authorization: Bearer $PDD_KEY" \
  --form files=@contract.docx \
  --output contract.pdf

Fonts that are not in the document may be replaced by similar ones, which can move line breaks. Embed the fonts in the document to keep the exact look.

Merge PDFs

The files are merged in the order of their names (numbers first, then letters).

curl https://api.pdfdispatch.com/v1/pdf/merge \
  --header "Authorization: Bearer $PDD_KEY" \
  --form files=@1-cover.pdf \
  --form files=@2-report.pdf \
  --form files=@3-appendix.pdf \
  --output merged.pdf

Common options

Form fields, sent with the files. A wrong value gets 400 with a plain-text message that names the field.

Webhooks

For big files, have the result sent to your server instead of waiting for it. With the headers below the API answers 204 No Content at once, makes the PDF, and then sends it to Webhook-Url.

curl https://api.pdfdispatch.com/v1/convert/url \
  --header "Authorization: Bearer $PDD_KEY" \
  --header "Webhook-Url: https://example.com/hooks/pdf" \
  --header "Webhook-Events-Url: https://example.com/hooks/pdf-events" \
  --header 'Webhook-Extra-Http-Headers: {"Authorization": "Bearer your-own-token"}' \
  --form url=https://example.com/report

A webhook request counts as one PDF when it is accepted with 204. The calls to your server carry the request's X-Request-Id.

Pages and files the API fetches

The API fetches web pages for the URL routes, the images, styles and scripts your HTML links to, and calls your webhooks. It reaches only the public internet: localhost, private networks and cloud metadata addresses are refused. A refused URL gets 403; a refused image or style inside a page is left out and the PDF is still made. Send local assets as files of the request instead.