Endpoint reference

`POST /api/unlock`

Save a PDF without encryption. Print, copy and modify restrictions are gone from the output. Returns the unlocked PDF as application/pdf.

Request

Method: POST. URL: https://pdfops.dev/api/unlock. 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.
`password`	String	No	Needed only for a PDF that asks for a password to open. Owner-locked files with an empty user password open without it.

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.

Response

On success: 200 OK, Content-Type: application/pdf, body is the PDF saved without encryption. If the input was not encrypted, it is returned re-saved, with the response header x-pdfops-note: not-encrypted.

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 user password and none was sent, or the one sent is wrong.
`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.
`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/unlock \
  -F "pdf=@locked.pdf" \
  -o unlocked.pdf \
  -H "X-API-Key: pdfops_live_..."  # optional, raises your quota to your tier
# PDF with an open password: add -F "password=..."

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('locked.pdf')], { type: 'application/pdf' }), 'locked.pdf');

// fd.append('password', '...'); // only if the PDF asks for one to open

const res = await fetch('https://pdfops.dev/api/unlock', {
  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 unlock failed: ${err.error}: ${err.details}`);
}
if (res.headers.get('x-pdfops-note') === 'not-encrypted') console.log('input was not encrypted');
await writeFile('unlocked.pdf', Buffer.from(await res.arrayBuffer()));

Behavioral notes

This does not crack passwords. It removes restrictions from a file you can already open. A PDF that needs a password to open still needs that password in the password field.
Document info is kept. Title, author, dates and the rest of the Info dictionary survive decryption, including for files that store them in a cross-reference stream.
An unencrypted input is not an error. It comes back re-saved with x-pdfops-note: not-encrypted.
The output is deterministic. The modification date and producer are pinned, and an existing creation date is kept.
Limits: 4 MB per PDF, 2,000 pages, 4.5 MB per request (Vercel's platform limit).

FAQ

Can it open a PDF when I forgot the password?

No. It does not guess or crack passwords. It only saves a copy without the restrictions, for files you can already open.

How do I add a password instead?

Use /api/protect.

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