PDF Toolkit API Documentation

Quickstart

Four HTTP endpoints for working with PDFs. Send a file, get a file back. No SDK to install.

1. Create an account

Register with an email and password. This returns a session token immediately, so you don't need to confirm your email before continuing to the next steps.

curl -X POST https://pdf-toolkit-api.fly.dev/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"at-least-8-chars"}'

2. Confirm your email

Click the confirmation link we send you. A confirmed email is required before you can create an API key.

3. Create a key

curl -X POST https://pdf-toolkit-api.fly.dev/auth/api-keys \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my app"}'

4. Make a request

Every request to /v1 needs the x-api-key from step 3, not the session token. Uploads are multipart/form-data.

curl -H "x-api-key: $KEY" \
  -F "files=@a.pdf" -F "files=@b.pdf" \
  https://pdf-toolkit-api.fly.dev/v1/merge -o merged.pdf

Account

Everything above is under /auth, authenticated with a session token (Authorization: Bearer ...), separate from the x-api-key used for the PDF endpoints. A few more account endpoints:

Login

curl -X POST https://pdf-toolkit-api.fly.dev/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"..."}'

Returns a session token directly, or {"twoFactorRequired":true,"pendingId":"..."} if you've enabled 2FA on the account. Submit the emailed code with POST /auth/login/2fa {pendingId, code} to get your session token.

Two-factor authentication

Off by default. Toggle with POST /auth/2fa/enable / POST /auth/2fa/disable (session-authenticated). When enabled, login emails a 6-digit code that expires in 10 minutes.

Forgot your password?

curl -X POST https://pdf-toolkit-api.fly.dev/auth/forgot-password \
  -H "Content-Type: application/json" -d '{"email":"you@example.com"}'

Emails a reset link if the address is registered. POST /auth/reset-password {token, newPassword} completes it and signs you out everywhere else.

API key authentication

Pass your key as x-api-key on every request under /v1. Missing or invalid keys get a 401.

Each key carries a monthly request quota. Requests past the quota get a 429 until the calendar month rolls over.

Response format

merge, split, compress, and pdf-to-image return the file itself as raw bytes on success, application/pdf, image/png, or application/zip. That is the actual product, so a plain curl -o file.pdf works with no decoding step.

Everything else, health checks, usage, and every error, uses one JSON envelope:

{ "code": 200, "status": "success", "data": { ... } }
{ "code": 400, "status": "error", "data": { "error": "Upload a PDF file under the 'file' field" } }

Merge

Combines 2 or more PDFs, in the order they're sent, into one PDF.

curl -H "x-api-key: $KEY" \
  -F "files=@a.pdf" -F "files=@b.pdf" \
  https://pdf-toolkit-api.fly.dev/v1/merge -o merged.pdf

Returns application/pdf.

Split

Splits a PDF. Without ranges, returns one PDF per page, zipped. With ranges, extracts just those pages into a single PDF.

# one PDF per page, zipped
curl -H "x-api-key: $KEY" -F "file=@doc.pdf" https://pdf-toolkit-api.fly.dev/v1/split -o pages.zip

# just pages 1-3 and 5
curl -H "x-api-key: $KEY" -F "file=@doc.pdf" -F "ranges=1-3,5" \
  https://pdf-toolkit-api.fly.dev/v1/split -o excerpt.pdf

Returns application/pdf for a single-range extract, application/zip otherwise.

Compress

Re-saves the PDF with object streams enabled, deduping shared objects and compressing cross-reference data. A real but modest reduction, deep image recompression is on the roadmap.

curl -H "x-api-key: $KEY" -F "file=@doc.pdf" \
  https://pdf-toolkit-api.fly.dev/v1/compress -o compressed.pdf

Returns application/pdf. Response headers X-Original-Size-Bytes and X-Compressed-Size-Bytes report the before and after size.

PDF to image

Rasterizes pages to PNG or JPEG.

curl -H "x-api-key: $KEY" -F "file=@doc.pdf" -F "ranges=1" \
  https://pdf-toolkit-api.fly.dev/v1/pdf-to-image -o page1.png

Returns a single image if one page is requested, application/zip for more than one.

Usage

Current month's usage against your key's quota.

curl -H "x-api-key: $KEY" https://pdf-toolkit-api.fly.dev/v1/usage

# {"code":200,"status":"success","data":{"plan":"free","monthlyLimit":100,"usedThisMonth":12,"remaining":88}}

Errors

Every error uses the response envelope above with a matching HTTP status.

400

Missing files, malformed page ranges, or an upload that isn't a valid PDF.

401

Missing, invalid, or revoked x-api-key.

422

The PDF couldn't be rendered to an image.

429

Monthly quota exceeded for this key.

500

Something broke server side.

Rate limits

Two limits apply independently: your key's monthly quota (set per key, 100/month on the free plan), and a flat 60 requests per minute per IP address as an abuse backstop.