Endpoint reference
POST /api/edit
Add text, a logo, a signature image, a QR code or barcode, or a stamp to exact positions on the pages of an existing PDF. Send a list of items; each one is drawn upright on the page you name, at the point you give. Returns the edited PDF as application/pdf.
Request
Method: POST. URL: https://pdfops.dev/api/edit. Body: multipart/form-data.
| Field | Type | Required | Description |
|---|---|---|---|
pdf | File (PDF binary) | Yes | Exactly one PDF, up to 4 MB and 2,000 pages. The whole request must stay under 4.5 MB, Vercel's platform request limit. |
items | String (JSON array) | Yes | The stamps to draw, in order: later items draw on top. Up to 100 items and 64 KB. See Items. |
| image fields | File (PNG or JPEG) | Only for image items | One file field per image, under any name you choose; an image item points at it by that name. Up to 2 MB each and 10 distinct image fields per request. PNG images are limited by decoded size, counted across all PNGs in one request: up to 10 million pixels at 8-bit colour, with or without transparency (a 4K screenshot fits); 16-bit images up to about 7 million, or about 5.8 million with transparency. Use smaller dimensions, 8-bit colour or a JPEG, which has no such limit. Animated PNGs are not accepted. |
password | String | No | Opens a PDF that needs a user password. Not needed for owner-locked files with an empty user password. |
The optional X-API-Key header works as on /api/merge: no header is anonymous, 100 requests per IP per month; a valid key uses your tier's quota; an invalid or revoked key returns 401 invalid_api_key. A successful (2xx) call counts 1 request, however many items it draws. Check consumption with GET /api/usage.
Coordinates
Positions are in PDF points, 72 to the inch, measured from the bottom-left corner of the page as a viewer shows it. A US Letter page is 612 × 792 points and A4 is 595 × 842. If a page is rotated, or has a crop box, the origin is still the bottom-left of what you see, so you never have to undo the rotation yourself. A PDF viewer's measuring tool shows where a blank line or signature box sits; measure from the bottom edge, not the top.
Items
Every item has type, page (1-based), x and y.
Text items: "type": "text"
| Key | Type | Default | Description |
|---|---|---|---|
x, y | Number | Required | The left end of the first line's baseline. |
text | String | Required | 1 to 2,000 characters. A newline starts a new line. Standard fonts cover the Latin-1 range only; other characters fail with unsupported_characters. |
size | Number | 12 | Font size in points, 4 to 200. |
font | String | Helvetica | Helvetica, Helvetica-Bold, Helvetica-Oblique, Times-Roman, Times-Bold or Courier. |
color | String | 000000 | Hex colour with 3 or 6 digits, such as cc0000. A leading hash is optional. |
maxWidth | Number | None | Wrap words so no line is wider than this many points. |
lineHeight | Number | 1.2 | Line spacing as a multiple of size, 0.5 to 5. Later lines go below the first. |
rotation | Number | 0 | Degrees counter-clockwise as the viewer sees it, -360 to 360. |
opacity | Number | 1 | 0.05 to 1. |
Image items: "type": "image"
| Key | Type | Default | Description |
|---|---|---|---|
x, y | Number | Required | The image's bottom-left corner. |
image | String | Required | The name of the file field holding the PNG or JPEG. Several items can reuse one image; it is stored in the PDF once. |
width, height | Number | Intrinsic size | Size in points. Give one and the other follows the image's aspect ratio. Give neither and each pixel becomes one point. |
opacity | Number | 1 | 0.05 to 1. |
PNG transparency is kept, so a signature scanned onto a transparent background sits on the line without a white box around it.
Barcode items: "type": "barcode"
The barcode is generated from value and drawn as vector shapes, not a picture, so it stays sharp and scans at any zoom or print size. Up to 25 barcode items per request.
| Key | Type | Default | Description |
|---|---|---|---|
x, y | Number | Required | The barcode's bottom-left corner. |
format | String | Required | 2D: qrcode, datamatrix, azteccode, pdf417. Linear: code128, code39, ean13, ean8, upca, itf14, interleaved2of5, gs1-128. |
value | String | Required | 1 to 3,000 characters to encode. The format's own rules apply: ean13 takes 12 or 13 digits (the check digit is added or verified), gs1-128 takes bracketed application identifiers such as (01)09506000134352(17)261231. QR codes take any text, including URLs and non-Latin characters. |
width, height | Number | See description | Size in points. For qrcode, datamatrix and azteccode, give one and the other keeps the shape; give neither and it is 72 points (one inch) wide. For the others, a side you leave out keeps its natural size: one point per bar module, one inch tall. Setting only height never makes bars thinner. |
includeText | Boolean | false | Print the human-readable digits under a linear barcode. |
errorCorrection | String | M | qrcode only: L, M, Q or H. Use H if you will print a logo over the middle. |
color | String | 000000 | Bar colour as hex. Keep it dark: scanners need contrast. |
background | String | None | Optional hex fill behind the barcode, such as ffffff on a coloured page. No quiet zone is added, so leave a clear margin around the code. |
opacity | Number | 1 | 0.05 to 1. |
Response
On success: 200 OK, Content-Type: application/pdf, body is the edited PDF.
On any failure: 4xx or 500, Content-Type: application/json, body is { "error": "<code>", "details": "<explanation>" }. Nothing is drawn unless every item is valid.
Error codes
| Error code | Status | Trigger |
|---|---|---|
invalid_multipart | 400 | Request body could not be parsed as multipart/form-data. |
missing_pdf | 400 | The request does not have exactly one pdf file field. |
pdf_too_large | 400 | The pdf file is over 4 MB. |
invalid_pdf | 400 | The PDF could not be parsed (corrupt, or not a PDF). |
encrypted_pdf | 400 | The PDF needs a password we were not given. Send it as the password form field. |
decompressed_too_large | 400 | Object streams inside the PDF decompress to over 32 MB. |
too_many_pages | 400 | The PDF has over 2,000 pages. |
invalid_items | 400 | items is missing, not valid JSON, not an array, over 64 KB, or an item has an unknown type or a bad value, including a barcode value its format cannot encode (the reason is in details). details names the item index and key, such as items[2].size. |
too_many_items | 400 | More than 100 items, more than 10 distinct image fields, or more than 25 barcode items. |
unsupported_characters | 400 | A text item has a character the standard fonts cannot draw. details names the first one. |
invalid_pages | 400 | An item's page is past the end of the document. |
invalid_image | 400 | An image field is missing, not a file, over 2 MB, a PNG too large to decode (see the image fields row), an animated, truncated or corrupt PNG, or not a PNG or JPEG. |
save_failed | 500 | PDF serialization failed. Retryable. |
internal_error | 500 | PNG validation was unavailable on the server. Retryable. |
request_too_large | 413 | The whole request body is over 4.5 MB (Vercel's platform request limit). Rejected before anything is parsed. |
invalid_api_key | 401 | An X-API-Key header was sent but the key is unknown or revoked. Get a fresh key at /pricing. |
rate_limited | 429 | The anonymous per-IP limit (100/month) or your key's monthly quota is used up. Retry-After gives seconds until next calendar month. |
Example
Sign the last line of a one-page agreement and date it: a signature image on the line, the signer's name under it, and the date to the right.
curl -X POST https://pdfops.dev/api/edit \
-F "pdf=@agreement.pdf" \
-F "signature=@signature.png" \
-F 'items=[
{"type":"image","page":1,"x":72,"y":110,"width":160,"image":"signature"},
{"type":"text","page":1,"x":72,"y":96,"text":"Jordan Lee, Operations Lead","size":10},
{"type":"text","page":1,"x":400,"y":112,"text":"2026-11-13","size":11,"font":"Courier"}
]' \
-o signed.pdf \
-H "X-API-Key: pdfops_live_..." # optional, raises your quota to your tier
Keyless calls work: 100 requests per IP per month with no key.
Using this for real? A free API key raises the keyless 100 calls per IP to 250 requests a month, with no card.
Code examples
Have an API key? Add an X-API-Key header to any request. It is optional, and it raises your quota from 100/IP/month to your tier's.
JavaScript (Node.js 22+) — built-in fetch + FormData
import { readFile, writeFile } from 'node:fs/promises';
const fd = new FormData();
fd.append('pdf', new Blob([await readFile('agreement.pdf')], { type: 'application/pdf' }), 'agreement.pdf');
fd.append('signature', new Blob([await readFile('signature.png')], { type: 'image/png' }), 'signature.png');
fd.append('items', JSON.stringify([
{ type: 'image', page: 1, x: 72, y: 110, width: 160, image: 'signature' },
{ type: 'text', page: 1, x: 72, y: 96, text: 'Jordan Lee, Operations Lead', size: 10 },
]));
const res = await fetch('https://pdfops.dev/api/edit', {
method: 'POST',
headers: { 'X-API-Key': process.env.PDFOPS_API_KEY }, // optional
body: fd,
});
if (!res.ok) {
const err = await res.json();
throw new Error(`PDFops edit failed: ${err.error}: ${err.details}`);
}
await writeFile('signed.pdf', Buffer.from(await res.arrayBuffer()));
Python — requests
import json, os, requests
items = [
{"type": "image", "page": 1, "x": 72, "y": 110, "width": 160, "image": "signature"},
{"type": "text", "page": 1, "x": 72, "y": 96, "text": "Jordan Lee, Operations Lead", "size": 10},
]
with open("agreement.pdf", "rb") as pdf, open("signature.png", "rb") as sig:
res = requests.post(
"https://pdfops.dev/api/edit",
headers={"X-API-Key": os.environ.get("PDFOPS_API_KEY", "")}, # optional
files={"pdf": pdf, "signature": sig},
data={"items": json.dumps(items)},
)
res.raise_for_status()
open("signed.pdf", "wb").write(res.content)
From an AI agent (MCP)
The hosted MCP server at https://pdfops.dev/api/mcp exposes this as the pdf_edit tool. Each image item takes the image itself as an https:// URL or a data:image/png;base64,… URI instead of a field name, and the tool returns the edited PDF inline. See PDFops for AI agents.
Behavioral notes
- Stamps are drawn on top of the page. They do not fill or change form fields; use
/api/fill-formfor fillable forms. - A signature image is not a digital signature. The page shows the signature, but no cryptographic signature or certificate is added.
- Barcodes are generated, not read. This endpoint draws barcodes; it does not scan existing ones.
- Standard fonts only. No custom fonts and no characters beyond Latin-1.
- The output is deterministic. The same input gives the same bytes: the modification date and producer are pinned, and an existing creation date is kept.
- Limits: 4 MB per PDF, 2 MB per image, 100 items, 10 images, 25 barcodes, 4.5 MB per request (Vercel's platform limit).
FAQ
How do I add a signature to a PDF with an API?
Upload the signature as a PNG with a transparent background, then send an image item with the page and the point where the signature line starts, and a width in points. Add text items for the printed name and date. The result is a visible signature, not a cryptographic digital signature.
How do I find the x and y position on the page?
Coordinates are points from the bottom-left of the page as displayed, 72 to the inch. On a US Letter page (612 × 792), a line one inch from the bottom and one inch from the left is at x: 72, y: 72. A PDF viewer's measuring tool gives exact positions.
Can I put the same logo on every page?
Yes. Send one image field and one image item per page, all pointing at the same field name. The image is stored in the PDF once, so the file grows by the size of one copy.
How do I add a QR code or barcode to a PDF?
Send a barcode item with the format, the value to encode, the page and the bottom-left point, for example {"type":"barcode","page":1,"x":480,"y":40,"format":"qrcode","value":"https://example.com/invoice/1042","width":72}. No image file is needed. Twelve formats are supported, including QR, Data Matrix, Code 128, EAN-13, UPC-A and GS1-128.
Why was my text rejected with unsupported_characters?
The standard PDF fonts cover the Latin-1 range. A character outside it, such as a CJK character or an emoji, is refused. details names the first bad character.
Related: Add a diagonal watermark · Stamp page numbers · Fill form fields.
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 and the key arrives in your inbox.