API Reference

PDF Processing API

A REST API for merging, splitting, compressing, OCR-ing, and converting PDFs programmatically. Available on the Business plan.

Authentication

Create an API key in Settings → API Keys. Keys are scoped to a workspace and can be revoked at any time. The full key is shown only once at creation — store it securely. Send it as a Bearer token on every request:

Authorization: Bearer ppk_live_xxxxxxxxxxxxxxxxxxxx

Rate limits & quotas

Requests are rate-limited per API key (currently 120 requests/minute).
Each processing call counts against your plan's monthly API-call quota. Track usage in Settings → API Keys.
Exceeding either limit returns HTTP 429 with a machine-readable error code.

Error format

Errors use a consistent envelope with a machine-readable code:

{
  "error": {
    "code": "quota_exceeded",
    "message": "You have reached your plan's monthly API call limit.",
    "field_errors": null
  }
}

Status

Code

Meaning

401

not_authenticated / authentication_failed

Missing, malformed, revoked, or invalid API key.

403

api_access_disabled

Your plan does not include API access.

400

validation_error

Bad input — see message and field_errors.

429

rate_limit_exceeded

Too many requests — back off and retry.

429

quota_exceeded

Monthly API-call limit reached for your plan.

404

not_found

Job or document not found in your workspace.

Endpoints

POST/api/v1/merge/

Merge PDFs

Combine two or more PDFs into a single document. Send the files as repeated multipart 'files' fields, in the order you want them merged.

Request

curl -X POST https://api.propdfsuite.com/api/v1/merge/ \
  -H "Authorization: Bearer ppk_live_..." \
  -F "files=@a.pdf;type=application/pdf" \
  -F "files=@b.pdf;type=application/pdf" \
  -F "output_title=Combined.pdf"

Response

{
  "id": "1ee5d5a5-...",
  "operation": "merge",
  "status": "completed",
  "progress_percent": 100,
  "error": null,
  "outputs": [
    {
      "document_id": "1c019ad8-...",
      "download_url": ".../api/v1/documents/1c019ad8-.../download/"
    }
  ]
}

POST/api/v1/split/

Split PDF

Split a PDF into multiple documents by 1-indexed, inclusive page ranges. 'ranges' is a JSON array sent as a multipart field.

Request

curl -X POST https://api.propdfsuite.com/api/v1/split/ \
  -H "Authorization: Bearer ppk_live_..." \
  -F "file=@source.pdf;type=application/pdf" \
  -F 'ranges=[{"start":1,"end":3},{"start":4,"end":10}]'

Response

{
  "id": "...",
  "operation": "split",
  "status": "completed",
  "outputs": [
    { "document_id": "...", "download_url": "..." },
    { "document_id": "...", "download_url": "..." }
  ]
}

POST/api/v1/compress/

Compress PDF

Reduce a PDF's file size. Optional 'quality' is one of screen, ebook (default), printer, or prepress.

Request

curl -X POST https://api.propdfsuite.com/api/v1/compress/ \
  -H "Authorization: Bearer ppk_live_..." \
  -F "file=@big.pdf;type=application/pdf" \
  -F "quality=ebook"

Response

{
  "id": "...",
  "operation": "compress",
  "status": "completed",
  "outputs": [
    { "document_id": "...", "download_url": "..." }
  ]
}

POST/api/v1/ocr/

OCR PDF

Extract text from a scanned PDF. Optional 'language' (default 'eng'): eng, fra, deu, spa, ita, por, ara, chi_sim. Returns the extracted text in the job result.

Request

curl -X POST https://api.propdfsuite.com/api/v1/ocr/ \
  -H "Authorization: Bearer ppk_live_..." \
  -F "file=@scan.pdf;type=application/pdf" \
  -F "language=eng"

Response

{
  "id": "...",
  "operation": "ocr",
  "status": "completed",
  "result": {
    "text": "Extracted text…",
    "total_pages": 3,
    "language": "eng"
  }
}

POST/api/v1/convert/

Convert to PDF

Convert an Office document or image to PDF (.docx, .doc, .pptx, .ppt, .xlsx, .xls, OpenDocument, .txt, .csv, .rtf, and common image formats). Conversion is synchronous — the finished PDF is returned directly.

Request

curl -X POST https://api.propdfsuite.com/api/v1/convert/ \
  -H "Authorization: Bearer ppk_live_..." \
  -F "file=@report.docx;type=application/vnd.openxmlformats-officedocument.wordprocessingml.document"

Response

{
  "document_id": "8bbbc89a-...",
  "title": "report",
  "page_count": 4,
  "file_size_bytes": 51234,
  "download_url": ".../api/v1/documents/8bbbc89a-.../download/"
}

GET/api/v1/jobs/{id}/

Get job status

Poll an asynchronous job (merge/split/compress/ocr). When status is 'completed', 'outputs' (or 'result' for OCR) is populated. Statuses: pending, processing, completed, failed.

Request

curl https://api.propdfsuite.com/api/v1/jobs/1ee5d5a5-.../ \
  -H "Authorization: Bearer ppk_live_..."

Response

{
  "id": "1ee5d5a5-...",
  "operation": "merge",
  "status": "processing",
  "progress_percent": 65,
  "outputs": []
}

GET/api/v1/documents/{id}/download/

Download a result

Download the PDF for a result document id returned by any operation. Responds with application/pdf.

Request

curl -L -o result.pdf \
  https://api.propdfsuite.com/api/v1/documents/1c019ad8-.../download/ \
  -H "Authorization: Bearer ppk_live_..."

Response

<binary application/pdf>