Docs
PDFops API reference
Every endpoint runs on V8 edge runtimes — Cloudflare
Workers, Vercel, Deno, Bun — so you call them from inside your
edge function, no headless browser required. Keyless calls get
100 requests per IP per month; a free API key raises that to 250
requests per month — POST your email to
/api/signup and pass the emailed key as
X-API-Key. Paid tiers (Indie 4,000, Pro 25,000
requests/month) are live at /pricing. All
endpoints accept and return PDF or JSON; no SDK required.
There's also a no-code path: email a
blank fillable PDF + values to fill@pdfops.dev and the reply
comes back filled, with the equivalent API call included.
Endpoints
-
POST /api/fill-formFill AcroForm fields in a PDF template you upload. Multipart request with
pdf(binary) andfields(JSON). Returns the filled PDF asapplication/pdf. -
POST /api/mergeMerge two or more PDFs into one. Multipart request with repeated
pdffields, concatenated in field order. Returns the merged PDF asapplication/pdf. -
POST /api/inspectList the AcroForm fields in a PDF you upload — names, types, options, current values — plus a paste-ready
fillTemplatefor/api/fill-form. Multipart request withpdf(binary). Returns JSON. -
POST /api/extract-pagesBuild a new PDF from chosen pages, in the order you list them (so it also reorders). Multipart request with
pdfandpages. Returnsapplication/pdf. -
POST /api/delete-pagesRemove pages from a PDF and keep the rest in order. Multipart request with
pdfandpages. Returnsapplication/pdf. -
POST /api/rotateRotate all pages or chosen pages by 90, 180, 270 or -90 degrees. Multipart request with
pdf,degreesand optionalpages. Returnsapplication/pdf. -
POST /api/splitSplit a PDF by page ranges or fixed chunk size. Multipart request with
pdfandrangesorevery. Returns JSON with each part as base64. -
POST /api/watermarkStamp a text watermark on all pages or chosen pages, with opacity, size, colour, rotation and position. Multipart request with
pdfandtext. Returnsapplication/pdf. -
POST /api/editAdd text, a logo or a signature image at exact positions on chosen pages. Multipart request with
pdf,items(JSON) and any PNG or JPEG files. Returnsapplication/pdf. -
POST /api/extract-textGet the text and tables out of a born-digital PDF: reading-order text per page, every line with its position, tables as rows of cells (optionally as CSV). Multipart request with
pdf. Returns JSON or plain text. -
POST /api/find-textSearch a born-digital PDF for a word, phrase or pattern and get each hit with its page and box in points. Literal or regular-expression search, resumable across pages. Multipart request with
pdfandquery. Returns JSON. -
POST /api/text-to-pdfTurn Markdown, plain text or CSV into a PDF: headings, lists, tables, code blocks and links on the built-in fonts, A4 or Letter. Not HTML-to-PDF. JSON request with
content. Returnsapplication/pdf. -
POST /api/add-fieldsCreate fillable form fields in an existing PDF: text, multiline text, checkboxes, radio groups, dropdowns and signature boxes at exact page coordinates. Multipart request with
pdfandfields. Returnsapplication/pdf. -
POST /api/image-to-pdfTurn JPG and PNG images into one PDF, one image per page, on pages the size of the image or on A4 or Letter with a margin. Multipart request with repeated
pdfimage files. Returnsapplication/pdf. -
POST /api/attachEmbed files in a PDF, such as an XML invoice, with a name, MIME type, description and PDF/A-3 relationship. Multipart request with
pdfandfile. Returnsapplication/pdf. -
POST /api/page-numbersStamp page numbers using a
{n} / {total}style format, with position, size, start number and margin. Multipart request withpdf. Returnsapplication/pdf. -
POST /api/unlockSave a PDF without encryption so print, copy and modify restrictions are gone. Multipart request with
pdfand optionalpassword. Returnsapplication/pdf. -
POST /api/protectEncrypt a PDF with an open password, an owner password, or both, and choose which actions stay allowed. Multipart request with
pdfand passwords. Returnsapplication/pdf. -
POST /api/metadataRead page count, page sizes, Info fields, dates, encryption status and form field count. Multipart request with
pdf. Returns JSON. -
POST /api/set-metadataSet title, author, subject, keywords and creator. Multipart request with
pdfand at least one field. Returnsapplication/pdf. -
POST /api/invoiceGenerate a complete US-Letter invoice PDF from JSON — no template upload. JSON body with
from,to,items; optional number, dates, currency, tax rate, notes. Deterministic: the same JSON returns a byte-identical PDF. Returnsapplication/pdf. -
POST /api/signupGet a free API key (250 requests/month) emailed to you. JSON body with
email. Returns{ "ok": true }; the key arrives by email. Re-signing up rotates your key. -
GET /api/usageCheck your key's quota: tier, limit, used, remaining, period, reset date. Requires
X-API-Key. Reads the same counter the rate limiter enforces. -
POST /api/waitlistFeedback: tell us what to build next. JSON body with use case, current solution, expected volume, pay range, optional email + message. Returns
{ "ok": true }. Not needed for keys — those are self-serve at/pricing.
Using this for real? A free API key raises the keyless 100 calls per IP to 250 requests a month, with no card.
Contract — applies to every endpoint
- Base URL:
https://pdfops.dev - Auth: Optional
X-API-Keyheader on the PDF endpoints. No header: anonymous, per-IP rate-limited. Valid key: your tier's monthly quota. Invalid or revoked key:401 invalid_api_key— no fallback to the IP cap. - Rate limit: anonymous, 100 successful (2xx) requests per IP per calendar month (UTC); keyed, your tier's quota — Free 250, Indie 4,000, Pro 25,000 per month. The middleware only counts accepted requests; 4xx and 5xx don't consume budget.
- Rate-limit response:
429 Too Many RequestswithRetry-Afterseconds-until-next-month — same shape anonymous or keyed. - Request body format:
multipart/form-datafor PDF-upload endpoints (/fill-form,/merge,/inspect, and the page and document operations from/extract-pagesto/set-metadata);application/jsonfor/invoice(structured data in, PDF out),/signup, and/waitlist. - Response on success:
200 OKwithapplication/pdfbody (binary endpoints),application/jsonwith{ "ok": true }(signup, waitlist), or a JSON report (/inspect,/metadata,/split,/usage). - Response on validation failure:
400 Bad Requestwithapplication/jsonbody{ "error": "<code>", "details": "<explanation>" }. - Response on server error:
500 Internal Server Errorwith the same JSON shape. Treat as retryable. - Timeout: the platform stops any request that runs longer than 60 seconds and answers
504(plain text from the platform, not the JSON shape above). The request still counts against your quota: the count is taken before the work starts and a killed request never gives it back. A PDF that needs that long is almost certainly crafted; retrying will not help.
Authentication & quotas
The PDF endpoints (every /api/* route above that takes a pdf, plus /api/invoice) resolve your quota from the X-API-Key header:
| Request | Result |
|---|---|
No X-API-Key header | Anonymous: 100 requests/IP/month. |
| Valid key | Your tier's quota: Free 250 / Indie 4,000 / Pro 25,000 requests per month. |
| Invalid or revoked key | 401 invalid_api_key. No fallback to the IP cap — a caller who thinks they're keyed should find out, not be quietly mis-metered. |
| Over quota | 429 with { "error": "rate_limited" } and a Retry-After header (seconds until the 1st of next month, UTC). |
Quota is consumed only on 2xx responses — failed requests are free. Get a free key at /pricing (or POST /api/signup); check consumption with GET /api/usage or the dashboard.
Clients & integrations
- TypeScript SDK:
npm install pdfops-sdk— typed, zero-dependency client for every endpoint. Edge-safe: Cloudflare Workers, Vercel Edge, Deno, Bun, Node 18+, browsers. Source · npm. - Python client:
pip install pdfops— zero-dependency, typed client for every endpoint (Python 3.9+);inspect,fill_form,merge,invoice,usage, and since 0.2.0extract_pages,delete_pages,rotate,split,watermark,page_numbers,unlock,protect,metadata,set_metadata. PyPI · source. - n8n node (verified by n8n):
n8n-nodes-pdfops. The version n8n has verified (0.2.1, the one n8n Cloud installs) has Fill Form, Inspect Fields, Merge, Generate Invoice and Get Usage. Releases from 0.3.0 on npm add extract, delete, rotate and split pages, watermark, page numbers, unlock, protect and metadata; n8n has not approved them yet, so for now they install only on self-hosted n8n (Settings → Community Nodes; update the node there if it was installed at 0.2.1). Releases since 0.3.1 also take an input PDF password on Fill Form, Inspect Fields and Merge. Every operation is also callable from an HTTP Request node. Get a free key for the node. Published templates: merged onboarding packets, Stripe invoice PDFs. - Zapier (beta): Fill PDF Form, Merge PDFs, Inspect PDF Form Fields and Create Invoice PDF as Zap actions, with file inputs and outputs that chain into Drive, Gmail or Dropbox steps. Accept the invite to use it before the public listing goes live. Zapier guide.
- MCP server:
npx -y pdfops-mcp— gives AI agents (Claude Code, Claude Desktop, Cursor, any MCP client) fifteen local tools:pdf_inspect,pdf_fill,pdf_merge,pdf_invoice,pdfops_usage, plus page extract/delete/rotate/split, watermark, page numbers, unlock, protect and metadata read/set since 0.4.0. Tools take file paths, so PDF bytes never enter the model's context. Listed in the official MCP registry asdev.pdfops/pdfops-mcp. Setup for Claude Code, Claude Desktop, Cursor and VS Code · Source. - OpenAPI 3.1:
/openapi.json— full request/response schemas for codegen and tool integration.
Fillable PDFs — quick start
Don't have a fillable PDF handy? Grab the sample invoice-template.pdf — it has customer_name + total AcroForm fields ready to fill via the curl example on each docs page.
For tax forms (W-9, W-8BEN, I-9) the IRS publishes AcroForm-ready PDFs at irs.gov/forms-instructions — just rename the default IRS field names to something predictable (see the W-9 walkthrough) and your code survives the annual form refresh.
Get a free API key. Keyless calls get 100 requests per IP per month; a free key raises that to 250, with no card. Enter your email, the key arrives in your inbox, and the signup page walks you through a first call. For calling PDFops from an edge function, that call is one line:
const pdf = await fetch("https://pdfops.dev/api/invoice", { method: "POST", headers: { "X-API-Key": env.PDFOPS_API_KEY, "Content-Type": "application/json" }, body: JSON.stringify({ from: "Acme LLC", to: "Globex", items: [{ description: "Consulting", quantity: 2, unit_price: 150 }] }) });