PDF Tools API

A REST API for Falcon PDF's processing tools — merge, compress, convert, OCR and more. Upload a file, run an operation, download the result. Enterprise access is credit-billed and authenticated with an API key.

Base URL: https://api.falconpdf.com

:::info Getting a key API keys are issued per enterprise client. Create one from your Falcon PDF account's developer settings. The full key is shown once and cannot be recovered — only rotated. :::

Authentication

Send your API key as a Bearer token. Keys have the form fpk_live_<id>.<secret>.

Authorization: Bearer fpk_live_<id>.<secret>

Keep the secret server-side. Enterprise requests are not subject to the browser rate limits or human verification used on the free web tools.

Credits & billing

• Each submitted job costs 1 credit, debited when the job is accepted.
• The debit happens whether the job later succeeds or fails. There are no refunds.
• The remaining balance is returned in the response body as credits_remaining and in the X-Credits-Remaining response header.
• When you run out, the API returns 402 Payment Required.

Request flow

Processing is asynchronous: submit a job, poll its status, then download the result.

1. Submit a multipart upload to POST /api/upload/ → get a job_id.
2. Poll GET /api/status/{job_id}/ until finished or failed.
3. Download from GET /api/download/{job_id}/.

note

Results are available for a limited time (about one hour) after completion.

Endpoints

POST /api/upload/

Multipart form. Fields: file (plus file2, file3… for multi-file tools like merge), operation, and an optional params JSON string. Max 100 MB per file.

curl -X POST https://api.falconpdf.com/api/upload/ \
  -H "Authorization: Bearer fpk_live_<id>.<secret>" \
  -F operation=compress \
  -F 'params={"quality":"ebook"}' \
  -F file=@document.pdf

{
  "job_id": "7b1e...",
  "status": "queued",
  "queue": "pdf-jobs-paid",
  "credits_remaining": 4821,
  "rate_per_minute": 60
}

GET /api/status/{job_id}/

curl https://api.falconpdf.com/api/status/7b1e.../ \
  -H "Authorization: Bearer fpk_live_<id>.<secret>"

// while running
{ "job_id": "7b1e...", "status": "queued", "result": null }

// when done
{ "job_id": "7b1e...", "status": "finished", "result": { "status": "completed" } }

// on a processing error
{ "job_id": "7b1e...", "status": "failed", "result": { "status": "failed", "error": "..." } }

Status values: queued, started, finished, failed, canceled. A password-protected input comes back as failed with a password_required_files list — resubmit the password via /api/update/.

GET /api/download/{job_id}/

Returns the result file (a 302 redirect to a short-lived signed URL). Call it only once status is finished.

curl -L -o result.pdf https://api.falconpdf.com/api/download/7b1e.../ \
  -H "Authorization: Bearer fpk_live_<id>.<secret>"

POST /api/update/{job_id}/

Retry a failed job with new parameters — e.g. supply a password for a protected PDF. JSON body. Does not cost an additional credit.

curl -X POST https://api.falconpdf.com/api/update/7b1e.../ \
  -H "Authorization: Bearer fpk_live_<id>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{"password":"s3cr3t"}'

POST /api/cancel/{job_id}/

Cancel a queued or running job.

Operations

Pass one of these as operation. The params JSON is operation-specific (e.g. {"quality":"ebook"} for compress, {"pages":"1-3"} for split).

operation	input	description
merge	PDFs	Combine multiple PDFs into one
split	PDF	Split into pages / ranges (ZIP)
extract	PDF	Extract a page range
rotate	PDF	Rotate pages
delete	PDF	Remove pages
organize	PDF	Reorder pages
compress	PDF	Reduce file size
unlock	PDF	Remove a known password
protect	PDF	Add a password
flatten	PDF	Flatten form fields
watermark	PDF	Add a text watermark
redact	PDF	Black out regions
number	PDF	Add page numbers
crop	PDF	Crop pages
ocr	PDF	Add a searchable text layer
pdf_to_images	PDF	Render pages to PNG/JPG (ZIP)
pdf_to_doc	PDF	Convert to DOCX
pdf_to_excel	PDF	Extract tables to XLSX
pdf_to_ppt	PDF	Convert to PPTX
pdf_to_html	PDF	Convert to HTML
pdf_to_text	PDF	Extract text
pdf_to_pdfa	PDF	Convert to PDF/A
word_to_pdf	DOC/DOCX/ODT/RTF…	Office document to PDF
excel_to_pdf	XLS/XLSX/CSV…	Spreadsheet to PDF
ppt_to_pdf	PPT/PPTX…	Presentation to PDF
webpage_to_pdf	HTML / URL	Render a page to PDF
images_to_pdf	JPG/PNG…	Combine images into a PDF

Errors

status	meaning
400	Bad request — missing file, unsupported operation or file type, invalid params
402	Out of API credits (top up to continue)
403	Invalid or inactive API key
404	Job or result not found
409	Job already started
413	File exceeds the 100 MB limit
503	Could not queue the job — retry

End-to-end example

# 1. submit
JOB=$(curl -s -X POST https://api.falconpdf.com/api/upload/ \
  -H "Authorization: Bearer $FALCON_API_KEY" \
  -F operation=pdf_to_doc -F 'params={}' -F file=@report.pdf \
  | jq -r .job_id)

# 2. poll
until curl -s https://api.falconpdf.com/api/status/$JOB/ \
  -H "Authorization: Bearer $FALCON_API_KEY" | jq -e '.status=="finished"'; do
  sleep 2
done

# 3. download
curl -L -o report.docx https://api.falconpdf.com/api/download/$JOB/ \
  -H "Authorization: Bearer $FALCON_API_KEY"