API documentation

The PPWEditor.com API runs the web editor’s PDF processing for these features: text and image watermarks, headers and footers with page numbers, document metadata, redaction, rasterizing pages to images, password protection (encryption) and a digital signature. You upload a PDF as multipart/form-data, set the options in a few form fields, and get the processed PDF back, either directly in the response or as a job that you poll and then download.

API usage and web editor usage share one account: the same monthly free pages and the same page-credit balance.

API access is approved by hand, per account.

1. Sign in on PPWEditor.com and open /developers.
2. Request API access. Add a short note about what you’ll use it for (up to 500 characters).
3. We review the request. Once it’s approved, create a key on the same page and give it a name you’ll recognize.
4. Copy the key right away. It is shown once: we store only a hash of it, so it can’t be shown again. If you lose it, revoke it and create a new one.

You can have up to 5 active keys. Revoke keys you no longer use on /developers; a revoked key stops working on the next request. If API access for your account is revoked, all of its keys are revoked with it and stay revoked even if access is approved again later.

Send your key in the Authorization header of every request:

Authorization: Bearer ppw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Keys start with ppw_. A request without a usable Authorization: Bearer <key> header gets 401 UNAUTHORIZED: the header is missing, empty (for example because the environment variable that should hold the key is unset) or malformed.
• A token that doesn’t start with ppw_, or isn’t an active key, gets 401 INVALID_API_KEY. A key stops being active when it is revoked or deleted, or when its account no longer exists.
• A request that carries a Bearer token is judged on that key alone, never on a browser session cookie.
• Server-side only. The API sends no CORS headers, so browsers block calls from web pages on other origins, and a key placed in front-end code is a leaked key. Call the API from your backend, scripts or scheduled jobs, keep the key in an environment variable or secrets store, and never commit it.
• If a key leaks, revoke it on /developers and create a new one.

https://ppweditor.com/api/v1

• Use HTTPS. All paths below are relative to this base URL.
• POST requests are multipart/form-data. Files go in file fields; each option group (watermark, headerFooter, metadata, redact, protect) is a JSON object sent as a text field; forceRender, flattenQuality and filenameSuffix are plain text fields. See the Options reference for defaults.
• The whole request body, all files and fields together, is limited to 100 MB (104,857,600 bytes) by the web server. Larger requests are answered with 413 before they reach the API, and that response is not JSON.
• Responses are JSON (application/json) or the processed file.
• With curl, send JSON fields with --form-string rather than -F: -F gives special meaning to a leading @ or < and to ;type= inside the value.

Each option group (watermark, headerFooter, metadata, redact, protect) is a JSON object sent as a text field. Leave a group out, or send it empty, and that feature stays off. Inside a group, keys you leave out or set to null take the editor’s defaults, listed in the Default column. No key is required: send enabled plus whatever you want to change.

A group that isn’t a JSON object (invalid JSON, an array, null, true, a number, or a file part instead of a text field) is rejected with 400 BAD_OPTION, and the message names the field, for example "watermark" is not valid JSON.

Watermark — watermark

Drawn on every page. By default a watermark rasterizes every page: the output pages are images, so the watermark can’t be removed, but their text can no longer be selected, searched or copied. The request becomes a job.

Send "flatten": false to keep the pages as they are instead: the watermark is drawn on top as vector text or as an image, the document’s text stays selectable, and when nothing else rasterizes pages (forceRender, redaction) the PDF comes back directly in the response. Such a watermark can be removed with a PDF editor.

{"enabled": true} alone draws CONFIDENTIAL diagonally across every page (60 pt, gray, 25% opacity, rotated 45°). For an image watermark, send "mode": "image" and the image in the watermarkImage file field.

Text watermark with every key spelled out. Apart from enabled, these are the defaults, so {"enabled": true} alone gives the same result:

{
  "enabled": true,
  "flatten": true,
  "mode": "text",
  "text": "CONFIDENTIAL",
  "imageData": "",
  "imageScale": 0.3,
  "opacity": 0.25,
  "fontSize": 60,
  "color": "#808080",
  "rotation": 45,
  "position": "diagonal"
}

Image watermark with curl. Only PNG and JPEG work. The format is recognized from the image’s content (its first bytes), not from the part’s type or the data URL. Any other format, for example WEBP, GIF or SVG, is rejected with 400 BAD_OPTION (“The watermark image must be a PNG or JPG file.”) before any work starts, and nothing is charged.

--form-string 'watermark={"enabled":true,"mode":"image","imageScale":0.25,"opacity":0.4,"rotation":0,"position":"bottom-right"}' \
-F "watermarkImage=@logo.png;type=image/png"

Header and footer — headerFooter

Three text positions at the top and three at the bottom of every page, drawn upright even on rotated pages. The text sits a margin of 1.2% of the page height (at least 6 pt) from the edges. Header and footer alone don’t rasterize anything; the PDF comes back directly.

Page numbers are on by default: {"enabled": true} alone prints 3 / 12 centered in the footer of each page. Send "includePageNumbers": false to leave that spot empty.

Tokens

• Every occurrence of a token in a field is replaced, not just the first one.
• Page numbers count the pages of each file, so in a /batch request every file starts at 1.
• Text is drawn in the chosen standard PDF font when that font can show it (Western European characters, Windows-1252). A field with other characters, for example Turkish ğ, ş, İ, ı, Polish ł, Greek, Cyrillic or №, is drawn in an embedded Noto Sans font instead. The other fields keep the chosen font. Characters that Noto Sans doesn’t have either, such as arrows (→), emoji or Chinese, Japanese and Korean characters, are left out; the rest of the text is still printed and the request doesn’t fail.

Every key spelled out. Only enabled and the keys you change are needed; here includePageNumbers doesn’t matter, because footerCenter has its own text:

{
  "enabled": true,
  "headerLeft": "Acme Ltd",
  "headerCenter": "",
  "headerRight": "{date}",
  "footerLeft": "Internal",
  "footerCenter": "Page {page} of {total}",
  "footerRight": "",
  "includePageNumbers": false,
  "includeDate": false,
  "fontSize": 9,
  "fontFamily": "Helvetica",
  "color": "#000000",
  "opaqueBackground": false
}

Metadata — metadata

Each field is written when it is non-empty; there is no on/off switch, and the enabled key the editor sends is ignored. So is creator: the server sets the PDF Creator and Producer fields itself.

{
  "title": "Q3 Report",
  "author": "Acme Ltd",
  "subject": "Quarterly results",
  "keywords": "finance, quarterly, 2026"
}

Redaction — redact

Covers areas of pages with opaque black or white boxes and removes what was underneath. The pages that have boxes are rasterized, so the covered text and images are gone from the file, not just hidden. Redaction always makes the request a job.

• When redaction is the only reason to rasterize (no forceRender, and no watermark or one with "flatten": false), only the pages that have boxes are rasterized, at the flattenQuality resolution. Where possible, text on those pages that doesn’t touch a box is put back as an invisible layer, so it can still be selected and searched; the other pages are copied unchanged. The result is named <name>-redacted.pdf, and the job’s progress counts only the redacted pages.
• Together with forceRender or a rasterizing watermark, every page is rasterized.
• Redaction is strict. If a page can’t be rasterized, the job fails (in /batch, that file is listed in failures) instead of returning a page with the original content still under the box. Nothing is charged for a failed file.
• In /batch, the same boxes are applied to every file, at the same page index and relative position.

A box 35% of the page wide and 5% high, 10% from the left and 20% from the top of the first page, and a second one near the bottom of the third page:

{
  "enabled": true,
  "color": "black",
  "regions": [
    { "page": 0, "x": 0.1, "y": 0.2, "w": 0.35, "h": 0.05 },
    { "page": 2, "x": 0.55, "y": 0.8, "w": 0.3, "h": 0.1 }
  ]
}

Rasterizing — forceRender and flattenQuality

forceRender=true turns every page into an image, even without a watermark, so the text can’t be selected, copied or edited. The request becomes a job. flattenQuality sets the resolution whenever pages are rasterized, by forceRender, a watermark or redaction:

Send protect with "enabled": true and a userPassword to encrypt the output with AES-256. The file then asks for a password when it is opened.

{
  "enabled": true,
  "userPassword": "open-sesame",
  "ownerPassword": "a-different-long-secret"
}

• Opened with the user password, the file can be printed in high resolution, its form fields filled in and its content read by accessibility tools. Changing it, copying text or images, adding comments, and inserting, deleting or rotating pages are not allowed. PDF readers apply these restrictions; the owner password lifts them.
• Encryption is the last step, after every other change, in every case: a PDF returned directly, a /process job and each PDF in a /batch ZIP (the ZIP itself isn’t encrypted).
• An encrypted file is not signed: when password protection is on, sign is ignored, because a signature and the encryption can’t both cover the final file.
• Password protection doesn’t change whether the response is a direct PDF or a job.
• Password-protected PDFs can’t be uploaded again (422 ENCRYPTED_PDF), so keep an unencrypted copy if you’ll need to process the file later.

Send protect={"sign": true} to sign the output. Without it, or with "sign": false, the PDF is not signed. (The web editor turns signing on by default; the API does not.) A file with password protection is never signed.

• The signature is added last, after every other change, so any later modification of the file invalidates it.
• It uses a self-signed certificate (common name ppweditor.com, reason “Certified by ppweditor.com”). It lets a reader detect changes made after signing; it does not prove who you are. PDF readers such as Acrobat show the signer’s identity as not verified, because the certificate is not issued by a trusted authority. The certificate can change over time, so don’t pin it.
• If signing fails, the server returns the unsigned PDF without reporting an error. If the signature matters to you, check that it is present.
• Signing does not change whether the response is a direct PDF or a job.

• Every account has 100 free pages per calendar month, shared between the web editor and the API. Unused free pages don’t carry over.
• Every page of every processed file counts, whatever the options.
• Pages beyond the free allowance are paid with page credits from your balance, one credit per page. Credits are used only for the part above the allowance: credits needed = max(0, pages − free pages left).
• The check runs before processing (for /batch, on the pages of all files together). Pages of your jobs that are still running or whose results you have not downloaded yet count as used here, and the credits they will need are held from your balance, until they are downloaded, fail or expire. If the credits needed exceed your balance, the request fails with 402 QUOTA_EXCEEDED and nothing is processed or charged.
• Pages are counted and credits deducted only for results you download, when the first download starts: a PDF returned directly as its response starts, a job result on the first /jobs/{jobId}/result request. A file that fails and a job that times out or is never downloaded cost nothing. Downloading the same result again within 15 minutes is free. Because the balance can change in between, a job’s first download checks it again and may answer 402 QUOTA_EXCEEDED; the result is kept so you can retry after buying credits.
• Check your numbers any time with GET /usage.

120 requests per minute per key, counted over a sliding 60-second window across all endpoints, status polls included. Above that the API answers 429 RATE_LIMITED with a Retry-After: 60 header. Rejected requests count toward the window too, so wait the Retry-After seconds instead of retrying straight away.

Errors from the API are JSON with a human-readable error message, and most also carry a machine-readable code. Branch on the HTTP status first and use code to tell cases apart where it is present. The exception is 413, which comes from the web server in front of the API and is not JSON.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{"error":"Rate limit: at most 120 requests per minute per key","code":"RATE_LIMITED"}

Failures inside a job are not HTTP errors: the request that created the job succeeded, and GET /jobs/{jobId} later reports status: "error" with an error message. Asking for that job’s result returns 422 JOB_FAILED.

The examples read the key from the PPW_API_KEY environment variable.

Metadata and header/footer in one request (direct PDF)

curl https://ppweditor.com/api/v1/process \
  -H "Authorization: Bearer $PPW_API_KEY" \
  -F "file=@report.pdf" \
  --form-string 'metadata={"title":"Q3 Report","author":"Acme Ltd"}' \
  --form-string 'headerFooter={"enabled":true,"headerLeft":"Acme Ltd","headerRight":"{date}","footerCenter":"Page {page} of {total}"}' \
  -o report-out.pdf \
  -w "%{http_code} %{content_type}\n"

# "200 application/pdf"  -> report-out.pdf is the finished file
# anything else          -> report-out.pdf holds the error body
#                           (JSON, except a 413 from the web server)

The header shows the company name on the left and the processing date on the right; the footer shows Page 3 of 12 in the center. Keys left out of headerFooter take their defaults.

Password-protected PDF with a selectable-text watermark (direct PDF)

curl https://ppweditor.com/api/v1/process \
  -H "Authorization: Bearer $PPW_API_KEY" \
  -F "file=@offer.pdf" \
  --form-string 'watermark={"enabled":true,"text":"DRAFT","flatten":false}' \
  --form-string 'protect={"enabled":true,"userPassword":"open-sesame"}' \
  -o offer-protected.pdf \
  -w "%{http_code} %{content_type}\n"

# "200 application/pdf"  -> offer-protected.pdf asks for "open-sesame" when opened

With "flatten": false the watermark is drawn on top of the pages and nothing is rasterized, so the encrypted PDF comes back in the same response and its pages keep their real text instead of becoming images.

Batch, poll, download

# 1. Start the batch (always a job). The watermark rasterizes every page.
#    {"enabled":true} alone draws CONFIDENTIAL diagonally (the defaults).
curl https://ppweditor.com/api/v1/batch \
  -H "Authorization: Bearer $PPW_API_KEY" \
  -F "files=@contract-a.pdf" \
  -F "files=@contract-b.pdf" \
  --form-string 'watermark={"enabled":true}' \
  --form-string 'protect={"sign":true}' \
  -F "flattenQuality=good" \
  --form-string "filenameSuffix=_final"

# {"jobId":"5f0c2a9d-…","status":"processing","filename":"ppweditor-batch _final.zip","total":2,"totalPages":14}

# 2. Poll the job until its status is "done" or "error".
JOB_ID=5f0c2a9d-…
while :; do
  JOB=$(curl -s -H "Authorization: Bearer $PPW_API_KEY" https://ppweditor.com/api/v1/jobs/$JOB_ID)
  STATUS=$(echo "$JOB" | jq -r '.status // .code // "unknown"')
  case "$STATUS" in
    processing)   sleep 3 ;;
    RATE_LIMITED) sleep 60 ;;
    *)            break ;;
  esac
done
echo "$JOB"   # "done", "error" with an "error" message, or an error body such as 404

# 3. Download the ZIP. Pages are counted and credits used when this first
#    download starts. Downloading it again within 15 minutes is free, so a
#    download that breaks off is simply repeated; after that it gets 410.
[ "$STATUS" = "done" ] && curl -s -H "Authorization: Bearer $PPW_API_KEY" \
  -o contracts.zip -w "%{http_code}\n" https://ppweditor.com/api/v1/jobs/$JOB_ID/result

# 200 -> contracts.zip is the archive; 410 or 422 -> it holds the JSON error

Usage

curl -H "Authorization: Bearer $PPW_API_KEY" https://ppweditor.com/api/v1/usage

# {"freePages":100,"usedPages":37,"creditPages":250}

Python (requests): direct or job

Sends a watermarked, signed PDF. The watermark makes this a job; the code branches on Content-Type, so it also works for requests that return the PDF directly.

import json
import os
import time

import requests

BASE = "https://ppweditor.com/api/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["PPW_API_KEY"]}


class ApiError(Exception):
    pass


def call(method, url, **kwargs):
    """Sends a request, waits out the rate limit, raises ApiError on 4xx/5xx."""
    while True:
        r = requests.request(method, url, headers=HEADERS, timeout=300, **kwargs)
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "60")))
            continue
        if r.status_code >= 400:
            try:
                body = r.json()
            except ValueError:  # 413 comes from the web server, not as JSON
                body = {"error": r.reason}
            # For example 400 BAD_OPTION, 422 ENCRYPTED_PDF, 410 RESULT_GONE
            raise ApiError(r.status_code, body.get("code"), body.get("error"))
        return r


with open("contract.pdf", "rb") as f:
    pdf_in = f.read()  # bytes, so a retry after 429 sends the whole file again

r = call(
    "POST",
    f"{BASE}/process",
    files={"file": ("contract.pdf", pdf_in, "application/pdf")},
    data={
        # Keys left out take the defaults: diagonal, 45°, gray, 25% opacity.
        "watermark": json.dumps({"enabled": True, "text": "DRAFT"}),
        "metadata": json.dumps({"title": "Contract"}),
        "protect": json.dumps({"sign": True}),
        "flattenQuality": "good",
    },
)

if r.headers["Content-Type"].startswith("application/pdf"):
    pdf = r.content  # processed within the request
else:
    job_id = r.json()["jobId"]
    delay = 1
    while True:
        time.sleep(delay)
        delay = min(delay + 1, 5)
        job = call("GET", f"{BASE}/jobs/{job_id}").json()
        if job["status"] == "error":
            raise ApiError("job failed", job.get("error"), job.get("failures"))
        if job["status"] == "done":
            break
    # Billed when the first download starts; repeats within 15 minutes are free.
    pdf = call("GET", f"{BASE}/jobs/{job_id}/result").content

with open("contract-out.pdf", "wb") as out:
    out.write(pdf)