Docs
Optimize PDF structure
Apply lossless stream and object optimization while preserving the document catalog.
POST /v1/pdf/optimize. Authenticated with your RelayPDF API key. Choose binary output, a temporary download URL, or an asynchronous job.
Request example
Replace the example input URL with a publicly accessible file you control. The example authorizes up to $1; successful work is charged for measured usage. Use a new idempotency key for a different request.
curl https://api.relaypdf.com/v1/pdf/optimize \
-H "Authorization: Bearer $RELAYPDF_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: optimize-example-001" \
-H "X-RelayPDF-Max-Charge-Microdollars: 1000000" \
--data '{"url":"https://example.com/input.pdf","response":"url","filename":"optimized.pdf","options":{}}'Input and response
Provide exactly one of url, file, or fileId. All other fields are optional unless an operation option is marked required.
| Field | Meaning |
|---|---|
| url | HTTPS input URL; public URL input is limited to 15 MiB. |
| file | Base64 input, optionally a data URI; decoded limit 15 MiB. |
| fileId | Private upload ID from POST /v1/files; maximum 100 MiB. |
| response | binary (default), url, or async. |
| filename | Optional output filename matching the actual output extension. |
| callbackUrl | Optional HTTPS per-job callback; unsigned. |
| options | Only use the options documented for the selected operation. |
Operation options
Pass these fields inside the options object. Unknown or irrelevant options should not be relied upon.
| Option | Default | Meaning |
|---|---|---|
| password | None | Input password. |
Output and limitations
Optimization does not guarantee a smaller output. It does not downsample images. Use /v1/pdf/compress-advanced for lossy size/quality presets.
PDF inputs are limited to 500 pages and returned output to 32 MiB. Uploaded inputs expire after 24 hours. Download successful output before its 24-hour URL expires.
Failed jobs are unbilled. A 402 can mean insufficient available credit or a spending limit; a 409 indicates an idempotency conflict; a 413 indicates an exceeded size limit. Do not retry invalid inputs unchanged.
Node SDK
Use a release version containing client.process. With older published packages, call REST until the matching SDK version is available.
import { RelayPDF } from "@relaypdf/sdk";
const client = new RelayPDF({ apiKey: process.env.RELAYPDF_API_KEY! });
const result = await client.process("optimize", {
"url": "https://example.com/input.pdf",
"response": "url",
"filename": "optimized.pdf",
"options": {}
}, { idempotencyKey: "optimize-example-002", maxChargeMicrodollars: 1_000_000 });
console.log(result);Pricing and job lifecycle
The assigned native rate applies. Final release pricing is $0.0004 per successful job plus $0.0005 per native execution second. Existing accounts retain their assigned rate. Reservations reduce available credit before work; unused funds return after settlement. See /docs/billing and /docs/idempotency for receipts, limits, and retries.