PDF API
Start free

Macaaw PDF API

PDF API for compressing, converting and signing

One REST API for 20 PDF tools and e-signatures. Every task runs on our servers in London and the files are deleted within 2 hours.

Get a free sandbox keyRead the API documentation

  • OpenAPI 3.1
  • Postman collection
  • Free sandbox
  • Signed webhooks
Compress a PDF with one request
Code sample language
curl https://macaaw.com/public/v1/tasks \
  -H "Authorization: API-Key $MACAAW_API_KEY" \
  -F "files[]=@lease.pdf" \
  -F 'data={"tool":"compress-pdf","options":{"level":"recommended"}}'

# 201 Created
{ "id": "…", "tool": "compress-pdf", "status": "task.queued" }
// Node 18+ (fetch, FormData and Blob are built in)
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("files[]", new Blob([await readFile("lease.pdf")]), "lease.pdf");
form.append("data", JSON.stringify({ tool: "compress-pdf", options: { level: "recommended" } }));

const res = await fetch("https://macaaw.com/public/v1/tasks", {
  method: "POST",
  headers: { Authorization: `API-Key ${process.env.MACAAW_API_KEY}` },
  body: form,
});
const task = await res.json(); // { id, tool, status: "task.queued" }
# Python 3 with requests
import json, os, requests

res = requests.post(
    "https://macaaw.com/public/v1/tasks",
    headers={"Authorization": f"API-Key {os.environ['MACAAW_API_KEY']}"},
    files={"files[]": open("lease.pdf", "rb")},
    data={"data": json.dumps({"tool": "compress-pdf", "options": {"level": "recommended"}})},
)
task = res.json()  # {"id": ..., "status": "task.queued"}
  • 20PDF tools on one endpoint
  • 1 callto upload and start a task
  • < 2 huntil your files are deleted
  • £0for the sandbox

What you can build

The PDF jobs your product shouldn’t have to own

  • Shrink uploads before you store them

    Compress PDFs, or fit them under an exact size, the moment your users upload them.

  • Convert Office files to PDF

    Word, Excel, PowerPoint, OpenDocument and HTML to PDF, with layouts that hold.

  • Make scans searchable

    Text recognition in 27 languages, PDF/A for archives, and tables straight to Excel.

  • Send agreements from your own app

    Create a document from a PDF, place fields with text tags, send it and download the signed copy.

  • Embed signing in your product

    Open a signing session inside your site, limited to the origins you allow.

  • Run batches with webhooks

    Start hundreds of tasks and get a signed callback as each one finishes.

How it works

From key to result in four calls

  1. Create a key

    Make a sandbox key in your account. Switch to a live key when you are ready.

    Account › Developer
  2. Start a task

    Send the files and the tool in one multipart request.

    POST /public/v1/tasks
  3. Hear when it’s done

    Subscribe to task_completed, or poll the task.

    webhook: task_completed
  4. Download

    Fetch the result, then delete it or let it expire.

    GET /tasks/{id}/download

Endpoints

A small, predictable API

Base URL https://macaaw.com/public/v1 · JSON with snake_case keys · Authorization: API-Key …

Full API reference

Tasks · PDF tools

  • GET/toolsEvery tool you can call, with its options
  • POST/tasksUpload files and start a tool in one call
  • GET/tasks/{id}Status: queued, processing, completed or failed
  • GET/tasks/{id}/downloadThe result file, or a ZIP
  • DELETE/tasks/{id}Delete the files now

Documents · e-signatures

  • POST/documentsA PDF plus recipients and fields, or text tags
  • POST/documents/{id}/sendSend by email, or silently for embedded signing
  • GET/documents/{id}/detailsRecipients, fields and the full timeline
  • POST/documents/{id}/sessionA signing link for your own page
  • GET/documents/{id}/downloadThe signed PDF with its certificate

Webhooks

  • POST/webhook-subscriptionsChoose triggers such as task_completed or document_state_changed
  • GET/webhook-eventsDelivery history, with resend

Security

Built for production from day one

The same deletion rules and UK processing as the website, plus the controls an engineering team expects.

  • Keys you controlLive and sandbox keys, shown once and stored as a hash. Revoke any key from your account.
  • Signed webhooksEach delivery carries ?signature= with an HMAC-SHA256 of the body, made with your shared key.
  • Files deleted fastTask files are kept 1 hour on a free account and 2 hours on Pro and Business, then they are gone. DELETE removes them at once.
  • UK processingEvery task runs on our servers in London. Request logs never store file contents or file names.
  • Fair rate limits120 new tasks a minute per user, with Retry-After on every 429.
  • Safe retriesSend an Idempotency-Key and a repeated request returns the first result for 24 hours.

Pricing

Start free. Pay as you grow.

Sandbox

£0

  • Every endpoint, with test data
  • 10 requests a minute
  • Up to 5 pages per task
  • Outputs stamped “Sandbox”
  • Test data deleted after 7 days
Get a sandbox key

Live, on Pro or Business

From £4.99a month, billed yearly

  • Uses your plan’s monthly allowances
  • Then credits: from £5 for 500
  • 1 credit per OCR page, 2 credits per Office conversion
  • 120 new tasks a minute
Compare plans

Enterprise

Volume pricing

  • Volume pricing on pages and conversions
  • Custom limits, sold by contract
  • Annual invoice billing
  • A named contact
Talk to us

Questions

Developers ask

Is there a free way to try the API?

Yes. Any signed-in user can create a sandbox key for free. Sandbox calls are limited to 10 a minute and 5 pages per task, every output is stamped “Sandbox”, and test data is deleted after 7 days.

Which tools can I call?

The 20 tools that run on our servers, from Compress and OCR to Office conversions and PDF/A, plus e-signatures. GET /tools lists them with their options. The 20 browser tools run in your users’ browsers, so they are not in API v1.

How is API usage charged?

Live keys come with Pro and Business. Calls use the same monthly allowances as the website; beyond those, credits apply. Credit packs start at £5 for 500 credits and last 12 months.

Do you have SDKs?

The documentation has copy-and-paste samples in curl, Node and Python for every endpoint, an OpenAPI 3.1 file and a Postman collection, so you can generate a client in any language.

What happens if my webhook endpoint is down?

We retry three more times, after 1 minute, 10 minutes and 1 hour, then mark the delivery failed. You can resend it from your account or with the API.

Ship PDF features this week.

Create a sandbox key in a minute. No card needed.