PDFella API · v1
PDF tools for your own app
Merge, split, rotate, watermark, number, protect, unlock and extract text from PDFs with a simple REST API. It runs the same engine as PDFella, so every improvement to our tools reaches your integration automatically.
Quick start
Send files as multipart/form-data. The processed file comes back in the response body, so there's nothing to poll or download separately.
curl https://api.pdfella.com/v1/merge \ -H "Authorization: Bearer $PDFELLA_API_KEY" \ -F "files=@first.pdf" \ -F "files=@second.pdf" \ -o merged.pdf
// Node.js 18+
const form = new FormData();
form.append("file", new Blob([await fs.promises.readFile("report.pdf")]), "report.pdf");
form.append("text", "CONFIDENTIAL");
const res = await fetch("https://api.pdfella.com/v1/watermark", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PDFELLA_API_KEY}` },
body: form,
});
if (!res.ok) throw new Error((await res.json()).error.message);
await fs.promises.writeFile("report-watermarked.pdf", Buffer.from(await res.arrayBuffer()));Prefer a GUI? Import the OpenAPI spec into Postman or Insomnia (Import → Link) to get a ready-made collection of every endpoint.
Authentication
Every request needs your API key in the Authorization header: Bearer pdfella_sk_…. Keys are secret: call the API from your server, never from a browser or mobile app where users could read the key. If a key leaks, tell us and we'll revoke it and issue a new one.
GET /v1/me returns your key's name, rate limit and request counts for the last 30 days.
Limits
| File size | 50 MB per file, 100 MB per request |
| Files per request | 50 |
| Rate limit | 60 requests per minute per key (higher on request). Responses include X-RateLimit-Limit and X-RateLimit-Remaining. |
| Data retention | None. Files are processed in memory and discarded when the response is sent. We log only the endpoint, status, size and timing. |
Errors
Errors return JSON: { "error": { "code": "…", "message": "…" } }. The message is written for developers and safe to log.
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing or invalid API key. |
| 403 | key_revoked | This API key has been revoked. |
| 404 | not_found | No such endpoint. |
| 400 | invalid_request | A file or parameter is missing or invalid. message says which. |
| 415 | unsupported_type | A file isn't the type the endpoint accepts (checked from its contents, not its name). |
| 413 | too_large | A file or the whole request is over the size limit. |
| 422 | password_required | The PDF needs a password to open; send it as password. |
| 422 | wrong_password | The password doesn't open this PDF. |
| 422 | damaged | The PDF couldn't be read. Try /repair first. |
| 429 | rate_limited | Too many requests. Wait for the number of seconds in Retry-After. |
| 500 | internal | Something went wrong on our side. |
Versioning
The API is versioned in the path (/v1). Within a version we only make backwards-compatible changes: new endpoints, new optional fields and better output from the same engine as PDFella. Anything that could break an integration ships as a new version, announced well in advance. Every response carries an X-PDFella-API-Version header.
Password-protected PDFs: every endpoint that reads a PDF accepts an optional password field. PDFs that only restrict printing or copying open without one.
Endpoints
Organise
Merge PDFs
Same as the PDFella toolPOST /v1/merge
Combine several PDFs into one, in the order they are sent.
| Field | Type | Description |
|---|---|---|
| files[]* | files: PDF | Two or more PDFs, merged in the order given. |
| password | string | Password to open the input PDF, if it needs one. |
Returns application/pdf: The merged PDF.
curl https://api.pdfella.com/v1/merge \ -H "Authorization: Bearer $PDFELLA_API_KEY" \ -F "files=@first.pdf" \ -F "files=@second.pdf" \ -o output.pdf
Split PDF
Same as the PDFella toolPOST /v1/split
Divide a PDF into several files by page ranges, every N pages, or odd and even pages.
| Field | Type | Description |
|---|---|---|
| file* | file: PDF | The PDF to process. |
| mode | ranges | every | odd-even | How to split. Default every. |
| ranges | string | With mode=ranges: page ranges separated by ;, one output file each, e.g. 1-3;4-6;7-. |
| every | integer | With mode=every: pages per output file. Default 1. |
| password | string | Password to open the input PDF, if it needs one. |
Returns application/zip: A ZIP archive with one PDF per part.
curl https://api.pdfella.com/v1/split \ -H "Authorization: Bearer $PDFELLA_API_KEY" \ -F "file=@document.pdf" \ -F "ranges=1-3;4-" \ -o output.zip
Extract pages
Same as the PDFella toolPOST /v1/extract-pages
Create a new PDF from selected pages, in the order given.
| Field | Type | Description |
|---|---|---|
| file* | file: PDF | The PDF to process. |
| pages* | page ranges | Pages to keep, in order, e.g. 3,1-2. |
| password | string | Password to open the input PDF, if it needs one. |
Returns application/pdf: A PDF with only the selected pages.
curl https://api.pdfella.com/v1/extract-pages \ -H "Authorization: Bearer $PDFELLA_API_KEY" \ -F "file=@document.pdf" \ -F "pages=1-3,5" \ -o output.pdf
Delete pages
Same as the PDFella toolPOST /v1/delete-pages
Remove pages from a PDF.
| Field | Type | Description |
|---|---|---|
| file* | file: PDF | The PDF to process. |
| pages* | page ranges | Pages to remove, e.g. 2,5-7. |
| password | string | Password to open the input PDF, if it needs one. |
Returns application/pdf: The PDF without the removed pages.
curl https://api.pdfella.com/v1/delete-pages \ -H "Authorization: Bearer $PDFELLA_API_KEY" \ -F "file=@document.pdf" \ -F "pages=1-3,5" \ -o output.pdf
Rotate pages
Same as the PDFella toolPOST /v1/rotate
Rotate pages clockwise by 90, 180 or 270 degrees.
| Field | Type | Description |
|---|---|---|
| file* | file: PDF | The PDF to process. |
| angle | 90 | 180 | 270 | Clockwise rotation in degrees. Default 90. |
| pages | page ranges | Pages to apply this to, e.g. 1-3,5,8-. Defaults to every page. |
| password | string | Password to open the input PDF, if it needs one. |
Returns application/pdf: The rotated PDF.
curl https://api.pdfella.com/v1/rotate \ -H "Authorization: Bearer $PDFELLA_API_KEY" \ -F "file=@document.pdf" \ -F "pages=1-3,5" \ -o output.pdf
Reorder pages
Same as the PDFella toolPOST /v1/reorder
Put pages in a new order. Pages you leave out are removed.
| Field | Type | Description |
|---|---|---|
| file* | file: PDF | The PDF to process. |
| order* | page ranges | The new page order, e.g. 3,1,2,4-. |
| password | string | Password to open the input PDF, if it needs one. |
Returns application/pdf: The reordered PDF.
curl https://api.pdfella.com/v1/reorder \ -H "Authorization: Bearer $PDFELLA_API_KEY" \ -F "file=@document.pdf" \ -F "order=3,1,2,4-" \ -o output.pdf
Stamp
Add a watermark
Same as the PDFella toolPOST /v1/watermark
Stamp text or an image (PNG/JPG) on pages, once or tiled.
| Field | Type | Description |
|---|---|---|
| file* | file: PDF | The PDF to process. |
| image | file: PNG, JPG | Image watermark. Send this or text. |
| text | string | Text watermark. Send this or an image file. |
| font | Helvetica | Times | Courier | Text font. Default Helvetica. |
| bold | boolean | Bold text. Default true. |
| size | number | Font size in points. Default 48. |
| color | #rrggbb | Text colour as #rrggbb. Default #d1242f. |
| opacity | number | Opacity from 0 to 1. Default 0.3. |
| rotation | number | Counter-clockwise rotation in degrees. Default 45. |
| position | top-left | top-center | top-right | middle-left | center | middle-right | bottom-left | bottom-center | bottom-right | tile | Where to place it; tile repeats it across the page. Default center. |
| image_scale | number | Image watermark scale (1 = image pixels as points). Default 0.3. |
| layer | over | under | Draw over or under the page content. Default over. |
| pages | page ranges | Pages to apply this to, e.g. 1-3,5,8-. Defaults to every page. |
| password | string | Password to open the input PDF, if it needs one. |
Returns application/pdf: The watermarked PDF.
curl https://api.pdfella.com/v1/watermark \ -H "Authorization: Bearer $PDFELLA_API_KEY" \ -F "file=@document.pdf" \ -F "text=CONFIDENTIAL" \ -F "pages=1-3,5" \ -o output.pdf
Add page numbers
Same as the PDFella toolPOST /v1/page-numbers
Number pages with a format of your choice.
| Field | Type | Description |
|---|---|---|
| file* | file: PDF | The PDF to process. |
| format | string | Text to stamp. Tokens: {page}, {pages}, {date}, {name}. Default {page}. |
| position | top-left | top-center | top-right | bottom-left | bottom-center | bottom-right | Where on the page. Default bottom-center. |
| size | number | Font size in points. Default 11. |
| color | #rrggbb | Text colour as #rrggbb. Default #15171c. |
| margin | number | Distance from the page edge in points. Default 28. |
| start_at | integer | Number of the first numbered page. Default 1. |
| pages | page ranges | Pages to number, e.g. 2-. Defaults to every page. |
| password | string | Password to open the input PDF, if it needs one. |
Returns application/pdf: The numbered PDF.
curl https://api.pdfella.com/v1/page-numbers \
-H "Authorization: Bearer $PDFELLA_API_KEY" \
-F "file=@document.pdf" \
-F "format=Page {page} of {pages}" \
-F "pages=1-3,5" \
-o output.pdfConvert
Images to PDF
Same as the PDFella toolPOST /v1/images-to-pdf
Turn JPG and PNG images into a PDF, one image per page.
| Field | Type | Description |
|---|---|---|
| files[]* | files: PNG, JPG | JPG or PNG images, one page each, in the order given. |
| page_size | fit | a4 | letter | fit makes each page the size of its image. Default fit. |
| orientation | auto | portrait | landscape | Page orientation for A4 and Letter. Default auto. |
| margin | number | Margin around each image in points. Default 0. |
Returns application/pdf: A PDF with one page per image.
curl https://api.pdfella.com/v1/images-to-pdf \ -H "Authorization: Bearer $PDFELLA_API_KEY" \ -F "files=@first.png" \ -F "files=@second.png" \ -o output.pdf
PDF to text
Same as the PDFella toolPOST /v1/pdf-to-text
Extract the text of every page. Scanned pages without a text layer return no text.
| Field | Type | Description |
|---|---|---|
| file* | file: PDF | The PDF to process. |
| password | string | Password to open the input PDF, if it needs one. |
Returns text/plain: Plain text, with a divider line before each page.
curl https://api.pdfella.com/v1/pdf-to-text \ -H "Authorization: Bearer $PDFELLA_API_KEY" \ -F "file=@document.pdf" \ -o output.txt
Flatten PDF
Same as the PDFella toolPOST /v1/flatten
Bake form fields into the page so they can no longer be edited.
| Field | Type | Description |
|---|---|---|
| file* | file: PDF | The PDF to process. |
| password | string | Password to open the input PDF, if it needs one. |
Returns application/pdf: The flattened PDF.
curl https://api.pdfella.com/v1/flatten \ -H "Authorization: Bearer $PDFELLA_API_KEY" \ -F "file=@document.pdf" \ -o output.pdf
Security
Protect PDF
Same as the PDFella toolPOST /v1/protect
Encrypt a PDF with a password (AES-256).
| Field | Type | Description |
|---|---|---|
| file* | file: PDF | The PDF to process. |
| new_password* | string | Password needed to open the output (1–128 characters). |
| allow_print | boolean | Allow printing. Default true. |
| allow_copy | boolean | Allow copying text and images. Default false. |
| allow_edit | boolean | Allow editing. Default false. |
| password | string | Password to open the input PDF, if it needs one. |
Returns application/pdf: The encrypted PDF.
curl https://api.pdfella.com/v1/protect \ -H "Authorization: Bearer $PDFELLA_API_KEY" \ -F "file=@document.pdf" \ -F "new_password=" \ -o output.pdf
Unlock PDF
Same as the PDFella toolPOST /v1/unlock
Remove the password and printing/copying restrictions from a PDF.
| Field | Type | Description |
|---|---|---|
| file* | file: PDF | The PDF to process. |
| password | string | Password to open the input PDF, if it needs one. |
Returns application/pdf: The PDF without encryption.
curl https://api.pdfella.com/v1/unlock \ -H "Authorization: Bearer $PDFELLA_API_KEY" \ -F "file=@document.pdf" \ -o output.pdf
Repair PDF
Same as the PDFella toolPOST /v1/repair
Rebuild a damaged PDF's structure so it opens again.
| Field | Type | Description |
|---|---|---|
| file* | file: PDF | The PDF to process. |
| password | string | Password to open the input PDF, if it needs one. |
Returns application/pdf: The repaired PDF.
curl https://api.pdfella.com/v1/repair \ -H "Authorization: Bearer $PDFELLA_API_KEY" \ -F "file=@document.pdf" \ -o output.pdf