AdaPDF REST API & Integration Guide

1. Overview & Base URLs

The AdaPDF API operates as a secure REST interface accepting standard multipart/form-data and application/json payloads. All documents are remediated using a non-destructive tag tree engine, preserving original visual geometries, kerning, and images.

2. Authentication

Authenticate requests by including your secret API Key in the HTTP headers. We support both custom headers and standard Bearer tokens:

3. Rate Limits & Quota Gating

Each API key is provisioned with a sliding-window rate limit of 60 requests per minute. If exceeded, the server returns 429 Too Many Requests with a Retry-After response header indicating seconds to wait.

Every processed page deducts 1 Page Credit from your balance. If your account runs out of credits, requests return 402 Payment Required with a link to top up.

4. Multi-Seat Organization Quotas

Under our Professional Plan (3 Team Member Seats) and Agency Plan (10 Team Member Seats), multiple developers and services can integrate with AdaPDF using their own accounts without sharing credentials:

5. Endpoints Reference

{
  "status": "success",
  "doc_id": "8f3e1a02_budget.pdf",
  "pages_processed": 6,
  "pre_score": 42,
  "post_score": 100,
  "is_compliant_wcag_aa": true,
  "download_url": "https://adapdf.io/download/remediated_8f3e1a02_budget.pdf",
  "report_url": "https://adapdf.io/report/remediated_8f3e1a02_budget.pdf"
}

{
  "job_id": "job_9f4e2b810ac3",
  "status": "completed",
  "total_pages": 48,
  "completed_pages": 48,
  "percent_complete": 100,
  "post_score": 98,
  "download_url": "https://adapdf.io/download/remediated_9f4e2b810ac3.pdf",
  "report_url": "https://adapdf.io/report/remediated_9f4e2b810ac3.pdf"
}

{
  "status": "ok",
  "app": "AdaPDF Workbench",
  "version": "1.2.1",
  "database": "connected"
}

6. Webhooks

When you specify a webhook_url in your remediation request, AdaPDF delivers an HTTP POST request immediately upon job completion with the event remediation.completed:

{
  "event": "remediation.completed",
  "job_id": "job_9f4e2b810ac3",
  "status": "completed",
  "total_pages": 84,
  "pre_score": 38,
  "post_score": 98,
  "download_url": "https://adapdf.io/download/remediated_budget.pdf",
  "report_url": "https://adapdf.io/report/remediated_budget.pdf"
}

7. Implementation Examples

import requests

API_KEY = "ada_live_YOUR_KEY"
with open("minutes.pdf", "rb") as f:
    resp = requests.post(
        "https://adapdf.io/api/v1/unattended/remediate",
        headers={"X-API-Key": API_KEY},
        files={"file": f},
        data={"title": "City Council Minutes", "lang": "en-US"}
    )
print(resp.json())

curl -X POST https://adapdf.io/api/v1/unattended/remediate \
  -H "X-API-Key: ada_live_YOUR_KEY" \
  -F "[email protected]" \
  -F "title=City Council Minutes" \
  -F "lang=en-US"

8. Native CLI & Hot-Folder Watcher

For terminal servers and unattended folder monitoring, use the included CLI tool:

# Audit a PDF from the terminal
python -m ada_pdf.cli audit document.pdf --json

# Batch remediate a directory of files
python -m ada_pdf.cli batch ./input_folder -o ./output_folder

# Continuous hot-folder watcher daemon
python -m ada_pdf.cli unattended --input-dir /mnt/inbox --watch

9. Status Codes Reference