API documentation

Quickstart

1. Create an API key in the dashboard. It is shown once; store it as an environment variable such as BPE_API_KEY.
2. Send a file (or a public file URL) to an endpoint. You get a job ID back straight away.
3. Poll the job until its status is done, or pass a webhook_url and we call you.
4. Download each output from its url. Links last 15 minutes; files are deleted after an hour.

1. Create a job

curl -X POST https://api.bestpdfever.com/v1/compress \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@input.pdf" \
  -F 'options={"targetKB":500}'

HTTP/1.1 202 Accepted
{
  "id": "6f1c1a52-8d2e-4a59-9a4e-2f6b0f6e3c1d",
  "status": "queued",
  "credits": 2,
  "statusUrl": "https://api.bestpdfever.com/v1/jobs/6f1c1a52-8d2e-4a59-9a4e-2f6b0f6e3c1d"
}

2. Wait for the result

curl https://api.bestpdfever.com/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $BPE_API_KEY"

{
  "id": "6f1c1a52-8d2e-4a59-9a4e-2f6b0f6e3c1d",
  "status": "done",
  "progress": 1,
  "outputs": [
    { "name": "report-compressed.pdf", "size": 482113, "contentType": "application/pdf", "url": "https://…" }
  ]
}

Authentication

Send your key in the Authorization header on every request. Keys start with bpe_live_.

Authorization: Bearer bpe_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Keep keys on your server; never put them in browser or mobile app code. We store only a hash, so a lost key can’t be recovered: revoke it and create a new one. Check your plan and remaining credits with GET /v1/account.

Jobs and files

Every endpoint accepts either form:

• multipart/form-data: one or more file fields (in order), an optional options field containing a JSON object, and an optional webhook_url.
• application/json: { "url": "https://…" } or { "urls": [...] } with public file URLs, plus options and webhook_url. We download the files for you (redirects are followed; private network addresses are refused).

Jobs move through queued → active → done or failed. A failed job has an error code and costs nothing:

Jobs are only visible to the account that created them. Uploaded files are deleted as soon as the job has run.

Webhooks

On paid plans, add webhook_url to any request and we POST the finished job to it (the same JSON as GET /v1/jobs/:id). Non-2xx responses are retried three times over about 45 seconds.

POST /your/webhook
BPE-Signature: t=1760000000,v1=5f2b…

{ "id": "6f1c…", "status": "done", "outputs": [ … ] }

Verify each delivery with your signing secret from the dashboard: compute HMAC-SHA256 of `${t}.${rawBody}` and compare it with v1.

import { createHmac, timingSafeEqual } from "node:crypto";

// header = req.headers["bpe-signature"], rawBody = the exact request body string
function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false; // replay window
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}

Credits and limits

Each successful job costs the credits listed on its endpoint. The Free plan includes 100 credits per calendar month and stops at the limit; paid plans continue and bill overage per credit. Rate limits apply per account per minute, and file size limits per file. See pricing.

Errors

Errors return JSON: { "error": "code", "message": "…", "detail": "…" }.

Endpoint reference

curl -X POST https://api.bestpdfever.com/v1/merge \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@file1.pdf" \
  -F "file=@file2.pdf"

curl -X POST https://api.bestpdfever.com/v1/split \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@input.pdf" \
  -F 'options={"ranges":"1-3,4-6"}'

curl -X POST https://api.bestpdfever.com/v1/rotate \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@input.pdf" \
  -F 'options={"pages":"1,3-5"}'

curl -X POST https://api.bestpdfever.com/v1/compress \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@input.pdf" \
  -F 'options={"targetKB":500}'

curl -X POST https://api.bestpdfever.com/v1/repair \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@input.pdf"

curl -X POST https://api.bestpdfever.com/v1/ocr \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@input.pdf" \
  -F 'options={"languages":["eng","fra"]}'

curl -X POST https://api.bestpdfever.com/v1/convert/word-to-pdf \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@input.doc"

curl -X POST https://api.bestpdfever.com/v1/convert/powerpoint-to-pdf \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@input.ppt"

curl -X POST https://api.bestpdfever.com/v1/convert/excel-to-pdf \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@input.xls"

curl -X POST https://api.bestpdfever.com/v1/convert/html-to-pdf \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"options":{"url":"https://example.com"}}'

curl -X POST https://api.bestpdfever.com/v1/convert/pdf-to-word \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@input.pdf"

curl -X POST https://api.bestpdfever.com/v1/convert/pdf-to-powerpoint \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@input.pdf"

curl -X POST https://api.bestpdfever.com/v1/convert/pdf-to-excel \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@input.pdf"

curl -X POST https://api.bestpdfever.com/v1/convert/pdf-to-pdfa \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@input.pdf"

curl -X POST https://api.bestpdfever.com/v1/protect \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@input.pdf" \
  -F 'options={"userPassword":"s3cret"}'

curl -X POST https://api.bestpdfever.com/v1/unlock \
  -H "Authorization: Bearer $BPE_API_KEY" \
  -F "file=@input.pdf"