Endpoint reference

`POST /api/extract-pages`

Q: Can I use this to reorder pages?

Yes. List every page in the new order: pages=3,1,2 returns page 3 first, then 1, then 2. Pages you leave out are dropped.

Q: How do I take everything after page 5?

Use an open range: pages=5- means page 5 through the last page.

Build a new PDF from chosen pages of an input PDF. Pages come out in the order you list them, and a page can be listed more than once, so this is also the reorder tool. Returns the new PDF as application/pdf.

Request

Method: POST. URL: https://pdfops.dev/api/extract-pages. Body: multipart/form-data.

Field	Type	Required	Description
`pdf`	File (PDF binary)	Yes	The PDF to work on, up to 4 MB and 2,000 pages. The whole request must stay under 4.5 MB, Vercel's platform request limit.
`pages`	String	Yes	Page list such as `1-3,5,8-` (see Page lists). The output has exactly these pages, in this order. `3,1,3` gives pages 3, 1, 3.
`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. Check consumption with GET /api/usage.

Page lists

The pages value is a comma list of items: N (one page), A-B (an inclusive range) or A- (page A through the last page). Pages are 1-based. Spaces around items and around the dash are ignored. last and negative numbers are not supported. A page past the end of the PDF, a reversed range, an empty item or an empty value fails with invalid_pages.

Response

On success: 200 OK, Content-Type: application/pdf, body is the new PDF with the selected pages.

On any failure: 4xx or 500, Content-Type: application/json, body is { "error": "<code>", "details": "<explanation>" }.

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. Owner-locked files with an empty user password (most government blanks) open on their own; for a real user password 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_pages`	400	`pages` is missing, empty, malformed or out of range, or selects more than 2,000 pages in total (duplicates count). `details` says which item failed.
`copy_failed`	500	The selected pages could not be copied. Retryable.
`save_failed`	500	PDF serialization failed. 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. No fallback to the anonymous IP cap. Get a fresh key at /pricing.
`rate_limited` (anonymous)	429	No `X-API-Key` header and the per-IP limit (100/month) is exhausted. `Retry-After` gives seconds until next calendar month.
`rate_limited` (keyed)	429	Your key's tier quota (Free 250 / Indie 4,000 / Pro 25,000 per month) is exhausted. `Retry-After` gives seconds until next calendar month.

Example

curl -X POST https://pdfops.dev/api/extract-pages \
  -F "pdf=@report.pdf" \
  -F "pages=1-3,7" \
  -o excerpt.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.

Get a free API key

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('report.pdf')], { type: 'application/pdf' }), 'report.pdf');
fd.append('pages', '1-3,7');

const res = await fetch('https://pdfops.dev/api/extract-pages', {
  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 extract-pages failed: ${err.error}: ${err.details}`);
}
await writeFile('excerpt.pdf', Buffer.from(await res.arrayBuffer()));

Behavioral notes

Order and duplicates are kept. pages=3,1,3 returns three pages: 3, 1, 3.
The output is deterministic. The same input and the same pages return the same bytes. Dates are set to the Unix epoch and the producer to pdfops.dev.
Pages are copied into a new document. Page content and page size stay as they were. Document-level extras such as the AcroForm, outline and attachments do not carry over.
Limits: 4 MB per PDF, 2,000 pages, 4.5 MB per request (Vercel's platform limit).

FAQ

Can I use this to reorder pages?

Yes. List every page in the new order: pages=3,1,2 returns page 3 first, then 1, then 2. Pages you leave out are dropped.

How do I take everything after page 5?

Use an open range: pages=5- means page 5 through the last page.

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.

Get a free API key

← All docs · PDFops home