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
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
Create a key
Make a sandbox key in your account. Switch to a live key when you are ready.
Account › DeveloperStart a task
Send the files and the tool in one multipart request.
POST /public/v1/tasksHear when it’s done
Subscribe to task_completed, or poll the task.
webhook: task_completedDownload
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 …
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
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
Enterprise
Volume pricing
- Volume pricing on pages and conversions
- Custom limits, sold by contract
- Annual invoice billing
- A named contact
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.