REST API v1

API Documentation

Integrate PDF·AI's 280+ document operations directly into your app. Upload a file, describe what you want in plain English, and get a processed file back — all in two API calls.

280+

Operations

2 calls

to process a file

REST

multipart/JSON

24h

file retention

Authentication

All requests require an API key in the Authorization header. API key management will be available in an upcoming release.

HTTP HEADER

Authorization: Bearer pdfai_your_key_here

Plan requirement

API access requires Business or Enterprise plan. Free and Pro plans cannot use the API.

Key format

Keys start with pdfai_. You can have up to 5 active keys per account. Keys are shown in full only once at creation.

Quick Start

Two calls to process any file: POST to process, GET to download. Use /api/v1/process for anything — the AI understands plain English.

# 1. Upload & process in one step
curl -X POST https://api.pdfai.app/api/v1/process \
  -H "Authorization: Bearer pdfai_your_key_here" \
  -F "file=@invoice.pdf" \
  -F "operation=compress to under 1MB"

# 2. Download the result
curl -O -J https://api.pdfai.app/api/v1/download/{outputId} \
  -H "Authorization: Bearer pdfai_your_key_here"

How It Works

⬆

STEP 01

Upload File

Send your PDF or document as multipart/form-data with your API key.

⚡

STEP 02

AI Processes

The AI reads your instruction, plans the operations, and executes them on the backend.

⬇

STEP 03

Download Result

Receive an outputId and downloadUrl. Fetch the finished file within 24 hours.

Tip: Use /api/v1/process with any natural-language instruction for maximum flexibility. Or use the shortcut endpoints (/compress, /merge, etc.) for typed, structured calls.

Endpoints

Account

GET/api/v1/me

Account Info

Returns your plan, daily usage statistics, and all active API keys.

Example

curl https://api.pdfai.app/api/v1/me \
  -H "Authorization: Bearer pdfai_your_key_here"

Response

JSON

{
  "plan": "business",
  "limits": { "ops_per_day": 1000, "max_file_mb": 500 },
  "api_usage": {
    "calls_used": 42,
    "calls_limit": 10000,
    "calls_remaining": 9958
  },
  "api_keys": [
    { "id": "ck_abc", "name": "Production", "prefix": "pdfai_xxxx",
      "callsUsed": 42, "callsLimit": 10000, "active": true }
  ]
}

GET/api/v1/status

System Status

Check whether the API and backend processing engine are healthy.

Example

curl https://api.pdfai.app/api/v1/status \
  -H "Authorization: Bearer pdfai_your_key_here"

Response

JSON

{
  "status": "ok",
  "backend": {
    "status": "healthy",
    "uptime_s": 86400,
    "operations_available": 298
  }
}

GET/api/v1/operations

List Operations

Returns every supported operation name (280+). Use these names with the /process endpoint.

Example

curl https://api.pdfai.app/api/v1/operations \
  -H "Authorization: Bearer pdfai_your_key_here"

Response

JSON

{
  "total": 298,
  "categories": {
    "compression": ["compress", "optimize_images", ...],
    "watermark":   ["add_watermark", "remove_watermark", ...],
    "conversion":  ["pdf_to_word", "word_to_pdf", "pdf_to_excel", ...],
    "security":    ["protect", "unlock", "redact", ...],
    "editing":     ["merge", "split", "rotate", "crop", ...]
  }
}

Processing

POST/api/v1/process

AI Process (General)

The universal endpoint. Describe what you want in plain English — the AI plans and executes the operation on your file. Supports all 280+ operations.

Parameters — multipart/form-data

Field	Type	Req.	Description
`file`	`File`	Required	PDF or supported input file
`operation`	`string`	Required	Natural language instruction e.g. "compress", "add watermark DRAFT", "split into pages", "summarize"

Example

curl -X POST https://api.pdfai.app/api/v1/process \
  -H "Authorization: Bearer pdfai_your_key_here" \
  -F "file=@document.pdf" \
  -F "operation=compress and add watermark CONFIDENTIAL"

Response

JSON

{
  "outputId": "f3a1b2c3-d4e5-6789",
  "downloadUrl": "/api/v1/download/f3a1b2c3-d4e5-6789",
  "message": "Compressed PDF (saved 68%)",
  "details": { "original_size": 4096000, "output_size": 1310720 }
}

POST/api/v1/compress

Compress PDF

Reduce PDF file size. Optionally control the quality tradeoff.

Parameters — multipart/form-data

Field	Type	Req.	Description
`file`	`File`	Required	PDF file to compress
`quality`	`"low" \| "medium" \| "high"`	Optional	Compression aggressiveness (default: "medium")

Example

curl -X POST https://api.pdfai.app/api/v1/compress \
  -H "Authorization: Bearer pdfai_your_key_here" \
  -F "file=@large.pdf" \
  -F "quality=high"

Response

JSON

{
  "outputId":      "a1b2c3d4",
  "downloadUrl":   "/api/v1/download/a1b2c3d4",
  "originalSize":  4096000,
  "compressedSize": 983040,
  "savings":       76
}

POST/api/v1/watermark

Add Watermark

Stamp a text watermark on every page of a PDF.

Parameters — multipart/form-data

Field	Type	Req.	Description
`file`	`File`	Required	PDF file
`text`	`string`	Required	Watermark text, e.g. "CONFIDENTIAL"
`opacity`	`number (0.0 – 1.0)`	Optional	Text transparency (default: 0.3)
`position`	`"center" \| "diagonal"`	Optional	Layout style (default: "diagonal")

Example

curl -X POST https://api.pdfai.app/api/v1/watermark \
  -H "Authorization: Bearer pdfai_your_key_here" \
  -F "file=@document.pdf" \
  -F "text=CONFIDENTIAL" \
  -F "opacity=0.35" \
  -F "position=diagonal"

Response

JSON

{
  "outputId":    "b2c3d4e5",
  "downloadUrl": "/api/v1/download/b2c3d4e5"
}

POST/api/v1/merge

Merge PDFs

Combine two or more PDFs into one document. Files are merged in the order they are sent.

Parameters — multipart/form-data

Field	Type	Req.	Description
`files`	`File[]`	Required	Two or more PDFs. Use key "files" for each file.

Example

curl -X POST https://api.pdfai.app/api/v1/merge \
  -H "Authorization: Bearer pdfai_your_key_here" \
  -F "files=@part1.pdf" \
  -F "files=@part2.pdf" \
  -F "files=@part3.pdf"

Response

JSON

{
  "outputId":    "c3d4e5f6",
  "downloadUrl": "/api/v1/download/c3d4e5f6",
  "pageCount":   48
}

POST/api/v1/protect

Password Protect

Encrypt a PDF with a password. The document cannot be opened without the correct password.

Parameters — multipart/form-data

Field	Type	Req.	Description
`file`	`File`	Required	PDF file to protect
`password`	`string`	Required	Password to set

Example

curl -X POST https://api.pdfai.app/api/v1/protect \
  -H "Authorization: Bearer pdfai_your_key_here" \
  -F "file=@document.pdf" \
  -F "password=MySecretPass123"

Response

JSON

{
  "outputId":    "d4e5f6a7",
  "downloadUrl": "/api/v1/download/d4e5f6a7"
}

POST/api/v1/convert

Convert Format

Convert files between PDF, Word (DOCX), and Excel (XLSX) formats.

Parameters — multipart/form-data

Field	Type	Req.	Description
`file`	`File`	Required	Input file (PDF or DOCX)
`to`	`"word" \| "pdf" \| "excel"`	Required	Target output format

Example

curl -X POST https://api.pdfai.app/api/v1/convert \
  -H "Authorization: Bearer pdfai_your_key_here" \
  -F "file=@report.pdf" \
  -F "to=word"

Response

JSON

{
  "outputId":    "e5f6a7b8",
  "downloadUrl": "/api/v1/download/e5f6a7b8",
  "format":      "word"
}

POST/api/v1/extract

Extract Content

Extract images, tables, or text from a PDF. Tables can be exported as XLSX or DOCX.

Parameters — multipart/form-data

Field	Type	Req.	Description
`file`	`File`	Required	PDF file
`type`	`"images" \| "tables" \| "text"`	Required	What to extract
`format`	`"xlsx" \| "docx"`	Optional	Table output format (default: "xlsx")

Example

curl -X POST https://api.pdfai.app/api/v1/extract \
  -H "Authorization: Bearer pdfai_your_key_here" \
  -F "file=@spreadsheet.pdf" \
  -F "type=tables" \
  -F "format=xlsx"

Response

JSON

{
  "outputId":    "f6a7b8c9",
  "downloadUrl": "/api/v1/download/f6a7b8c9",
  "type":        "tables"
}

Output

GET/api/v1/download/:id

Download Result

Download a processed output file using its ID. The ID is returned by every processing endpoint in the outputId field. Files are available for 24 hours.

Example

curl -O -J https://api.pdfai.app/api/v1/download/f3a1b2c3-d4e5-6789 \
  -H "Authorization: Bearer pdfai_your_key_here"

Response

JSON

// Binary file stream
// Content-Type: application/pdf
// Content-Disposition: attachment; filename="output.pdf"

Error Codes

All errors return JSON with an error field:{ "error": "API call limit reached (10000 calls/month). Upgrade your plan for more." }

400

Bad Request

Missing or invalid parameters. Check the error message for details.

401

Unauthorized

Missing, invalid, or revoked API key.

403

Forbidden

Your current plan does not include API access. Upgrade to Business or Enterprise.

404

Not Found

The requested output file does not exist or has expired (files expire after 24 hours).

429

Rate Limited

Monthly API call limit reached. Upgrade your plan for more calls.

502

Bad Gateway

The processing backend returned an error. Try again or check /api/v1/status.

503

Unavailable

Backend is temporarily unreachable. Check /api/v1/status for details.

Plans & Limits

Free

No API

API calls—

Ops/day5/day

Max file10 MB

Pro

No API

API calls—

Ops/day100/day

Max file100 MB

Business

API ✓

API calls10k/month

Ops/day1k/day

Max file500 MB

Enterprise

API ✓

API callsUnlimited

Ops/dayUnlimited

Max fileUnlimited

View Pricing & Upgrade →