Docs

API reference

One endpoint renders HTML or a public URL and answers with the PDF. Base URL: https://pdfember.com/api/v1.

Quickstart

1. Sign in and create an API key on the dashboard. 2. Send HTML:

curl https://pdfember.com/api/v1/pdf \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1><p>From pdfember.</p>"}' \
  -o hello.pdf

From Laravel with its HTTP client, or with the PHP package:

$response = Http::withToken(config('services.pdfember.key'))
    ->timeout(70)
    ->post('https://pdfember.com/api/v1/pdf', [
        'html' => view('invoices.show', compact('invoice'))->render(),
        'page' => ['size' => 'A4', 'margin' => 12],
    ])
    ->throw();

return response($response->body(), 200, ['Content-Type' => 'application/pdf']);

Authentication

Send the key as a bearer token: Authorization: Bearer pdx_live_…. Keys are shown once, when created; pdfember stores only their hash. Revoke a key on the dashboard and it stops working at once.

POST /v1/pdf

Body: JSON with the render options. Send exactly one of html or url. The answer is 200 with Content-Type: application/pdf and these headers:

• X-Pdfember-Pages: pages in the PDF.
• X-Pdfember-Documents-Left: documents left this month. A render is one document, however many pages it has.
• X-Pdfember-Render-Ms: time spent rendering.
• X-Pdfember-Render-Id: the render's id, as on the dashboard.

Render options

Unknown options are refused with 422, so a typo never renders silently.

Layouts

pages

Paper pages with your print CSS. Use it for documents that are printed or attached: invoices, contracts, the "print" version of a resume.

single-page

One page, as wide as width and as tall as the document: no page breaks at all, and forced breaks in the page are ignored. It reads exactly like the web preview, which makes it the right "digital" version of a resume. Documents taller than 19,000 px are refused; use pages for those.

Page breaks

A plain browser print cuts the page wherever the paper ends. Before printing, pdfember measures the laid-out document and adds break rules (your HTML is not rewritten):

• Blocks up to keepTogetherMax of a page (job entries, cards, table rows, figures) are never split.
• Headings, and short emphasised lines such as section and entry titles, stay with the content after them.
• Longer lists may split, but keep at least two items on each side; a short intro (title, dates, lead line) stays with the first items.
• Paragraphs keep at least three lines on each side (orphans and widows).
• Boxes taller than a page keep their padding on every page, so text does not start on the paper's edge.
• A coloured column that runs the document's full height, like a resume sidebar, is repainted on every page.
• Table headers repeat on every page.

Steer it from your HTML when needed:

<section data-pdfember-keep>…</section>          <!-- never split -->
<h3 data-pdfember-keep-with-next>…</h3>          <!-- stay with the next block -->
<div data-pdfember-break-before>…</div>         <!-- start a new page -->
<div data-pdfember-allow-break>…</div>          <!-- no smart breaks inside -->

CSS break-before, break-after and break-inside rules in your styles are respected. Try it in the playground with the comparison ticked.

POST /v1/tools/{tool}

PDF tools work on files you already have: merge, split, rotate, crop, stamp page numbers and more. Send multipart/form-data with the files as files[] (in order) and the tool's options as form fields. Files are processed in memory and never stored; together they may be up to 25 MB. Try them in the browser on PDF tools.

The answer is 200 with the PDF, or for split a ZIP of PDFs (Content-Type: application/zip). The headers are those of a render, plus X-Pdfember-Files: the PDFs in the answer. A run is one document, like a render, however many pages or files it outputs. Options that are not sent take their defaults; unknown ones are refused with 422.

Page lists such as pages read like "1-3, 5, 8-last": single pages, ranges, last, and open ranges ("8-"). Empty means every page. Text options of the stamp tools print in any script, and {n} and {total} become the page number and the last page's number.

Password-protected PDFs are refused; remove the password first. Tools that redraw pages (resize, n-up) keep the page content but not links or form fields; merge and split keep page links but not bookmarks.

merge · Merge

Combine several PDFs into one, in the order uploaded. PDF files: 2 to 20.

curl https://pdfember.com/api/v1/tools/merge \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "files[][email protected]" \
  -o out.pdf

alternate-mix · Alternate and mix

Interleave pages of several PDFs, e.g. odd and even pages scanned separately. PDF files: 2 to 20.

curl https://pdfember.com/api/v1/tools/alternate-mix \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "files[][email protected]" \
  -F "reverse=2" \
  -o out.pdf

organize · Organize

Put pages in a new order; repeat or leave out any of them. PDF files: 1.

curl https://pdfember.com/api/v1/tools/organize \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "pages=3, 1-2, 4-last" \
  -o out.pdf

split · Split

Cut a PDF into several, by page ranges or every N pages. Answers with a ZIP. PDF files: 1.

curl https://pdfember.com/api/v1/tools/split \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "ranges=1-3, 4-last" \
  -o parts.zip

extract-pages · Extract pages

Keep only the pages you list. PDF files: 1.

curl https://pdfember.com/api/v1/tools/extract-pages \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "pages=1-3, 5" \
  -o out.pdf

delete-pages · Delete pages

Remove the pages you list. PDF files: 1.

curl https://pdfember.com/api/v1/tools/delete-pages \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "pages=1-3, 5" \
  -o out.pdf

split-in-half · Split in half

Cut scanned two-page spreads into single pages. PDF files: 1.

curl https://pdfember.com/api/v1/tools/split-in-half \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "direction=vertical" \
  -o out.pdf

rotate · Rotate

Turn pages by 90, 180 or 270 degrees. PDF files: 1.

curl https://pdfember.com/api/v1/tools/rotate \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "angle=90" \
  -F "pages=2-last" \
  -o out.pdf

flip · Flip

Mirror pages horizontally or vertically. PDF files: 1.

curl https://pdfember.com/api/v1/tools/flip \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "direction=horizontal" \
  -o out.pdf

crop · Crop

Trim margins off pages. PDF files: 1.

curl https://pdfember.com/api/v1/tools/crop \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "top=10" \
  -F "bottom=10" \
  -o out.pdf

resize · Resize

Fit every page onto other paper, with an optional margin. PDF files: 1.

curl https://pdfember.com/api/v1/tools/resize \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "size=A4" \
  -F "margin=10" \
  -o out.pdf

n-up · N-up

Print 2, 4, 6, 8, 9 or 16 pages on one sheet. PDF files: 1.

curl https://pdfember.com/api/v1/tools/n-up \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "pagesPerSheet=4" \
  -o out.pdf

watermark · Watermark

Lay text across pages, at an angle and see-through. PDF files: 1.

curl https://pdfember.com/api/v1/tools/watermark \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "text=CONFIDENTIAL" \
  -F "opacity=0.2" \
  -o out.pdf

page-numbers · Page numbers

Number pages in any format, e.g. "Page {n} of {total}". PDF files: 1.

curl https://pdfember.com/api/v1/tools/page-numbers \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "format=Page {n} of {total}" \
  -F "position=bottom-right" \
  -o out.pdf

header-footer · Header and footer

Add text to the top and bottom of pages, with page numbers. PDF files: 1.

curl https://pdfember.com/api/v1/tools/header-footer \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "headerLeft=Contract 7/2026" \
  -F "footerCenter={n} / {total}" \
  -o out.pdf

metadata · Edit metadata

Set the title, author, subject, keywords and creator. PDF files: 1.

curl https://pdfember.com/api/v1/tools/metadata \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "title=Annual report" \
  -F "author=Anna Kowalska" \
  -o out.pdf

flatten · Flatten forms

Turn fillable form fields into plain page content. PDF files: 1.

curl https://pdfember.com/api/v1/tools/flatten \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -o out.pdf

remove-annotations · Remove annotations

Remove comments, highlights and other annotations. PDF files: 1.

curl https://pdfember.com/api/v1/tools/remove-annotations \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "keepLinks=true" \
  -o out.pdf

images-to-pdf · JPG and PNG to PDF

Turn photos and scans into a PDF, a page per image. JPG or PNG images: 1 to 20.

curl https://pdfember.com/api/v1/tools/images-to-pdf \
  -H "Authorization: Bearer $PDFEMBER_KEY" \
  -F "files[][email protected]" \
  -F "files[][email protected]" \
  -F "size=A4" \
  -F "margin=10" \
  -o out.pdf

GET /v1/usage

{
  "plan": "free",
  "documents_used": 42,
  "documents_included": 1000,
  "documents_left": 958,
  "period_start": "2026-11-01T00:00:00+00:00"
}

Errors

Errors are JSON: {"error": {"code": "…", "message": "…"}}.

Limits

• HTML up to 5 MB, extra CSS up to 256 KB, renders up to 60 seconds.
• PDF tools: files up to 25 MB together; merge, alternate-mix and images-to-pdf take up to 20 files; split makes up to 1,000 PDFs.
• Pages may load public http(s) resources only; private, loopback and link-local addresses are refused.
• Plans set documents a month, renders at once and requests a minute (see pricing). Failed renders do not count.