Macaaw PDF API
PDF API for compressing, converting and signing
One REST API for 20 PDF tools and e-signatures. Every task dey run for our servers for London and we dey delete the files within 2 hours.
Get 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 for one endpoint
- 1 callto upload and start a task
- < 2 huntil we delete your files
- £0for the sandbox
Wetin you fit build
The PDF jobs wey your product no suppose carry
Shrink uploads before you store dem
Compress PDFs, or fit dem under exact size, the moment your users upload dem.
Convert Office files to PDF
Word, Excel, PowerPoint, OpenDocument and HTML to PDF, with layouts wey dey hold.
Make scans searchable
Text recognition for 27 languages, PDF/A for archives, and tables straight to Excel.
Send agreements from your own app
Create document from PDF, put fields with text tags, send am and download the signed copy.
Embed signing for your product
Open signing session inside your site, wey dey limited to the origins wey you allow.
Run batches with webhooks
Start hundreds of tasks and get signed callback as each one finish.
How e dey work
From key to result in four calls
Create a key
Make sandbox key for your account. Switch to live key when you ready.
Account › DeveloperStart a task
Send the files and the tool for one multipart request.
POST /public/v1/tasksHear when e finish
Subscribe to task_completed, or poll the task.
webhook: task_completedDownload
Fetch the result, then delete am or let am expire.
GET /tasks/{id}/download
Endpoints
Small API wey you fit predict
Base URL https://macaaw.com/public/v1 · JSON with snake_case keys · Authorization: API-Key …
Tasks · PDF tools
- GET
/toolsEvery tool wey you fit call, with im options - POST
/tasksUpload files and start tool in one call - GET
/tasks/{id}Status: queued, processing, completed or failed - GET
/tasks/{id}/downloadThe result file, or ZIP - DELETE
/tasks/{id}Delete the files now
Documents · e-signatures
- POST
/documentsPDF plus recipients and fields, or text tags - POST
/documents/{id}/sendSend by email, or quietly for embedded signing - GET
/documents/{id}/detailsRecipients, fields and the full timeline - POST
/documents/{id}/sessionSigning link for your own page - GET
/documents/{id}/downloadThe signed PDF with im certificate
Webhooks
- POST
/webhook-subscriptionsChoose triggers like 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 wey engineering team dey expect.
- Keys wey you controlLive and sandbox keys, wey dem show one time and store as hash. Revoke any key from your account.
- Signed webhooksEach delivery dey carry ?signature= with HMAC-SHA256 of the body, wey dem make with your shared key.
- Files dey delete fastWe dey keep task files for 1 hour for free account and 2 hours for Pro and Business, then dem go comot. DELETE dey remove dem at once.
- UK processingEvery task dey run for our servers for London. Request logs no dey ever store file contents or file names.
- Fair rate limits120 new tasks every minute for each user, with Retry-After for every 429.
- Safe retriesSend Idempotency-Key and repeated request go return the first result for 24 hours.
Pricing
Start free. Pay as you dey grow.
Sandbox
£0
- Every endpoint, with test data
- 10 requests every minute
- Reach 5 pages for each task
- Outputs wey dem stamp “Sandbox”
- Test data dey delete after 7 days
Live, for Pro or Business
From £4.99every month, dem bill am every year
- E dey use your plan monthly allowances
- Then credits: from £5 for 500
- 1 credit for each OCR page, 2 credits for each Office conversion
- 120 new tasks every minute
Enterprise
Volume pricing
- Volume pricing on pages and conversions
- Custom limits, wey dem sell by contract
- Yearly invoice billing
- Contact person wey get name
Questions
Wetin developers dey ask
Free way dey to try the API?
Yes. Any user wey don sign in fit create sandbox key for free. Sandbox calls limit na 10 every minute and 5 pages for each task, dem dey stamp every output “Sandbox”, and we dey delete test data after 7 days.
Which tools I fit call?
The 20 tools wey dey run for our servers, from Compress and OCR to Office conversions and PDF/A, plus e-signatures. GET /tools dey list dem with their options. The 20 browser tools dey run for your users browsers, so dem no dey inside API v1.
How dem dey charge API usage?
Live keys dey come with Pro and Business. Calls dey use the same monthly allowances as the website; after those finish, credits go apply. Credit packs start from £5 for 500 credits and dem dey last 12 months.
You get SDKs?
The documentation get copy-and-paste samples for curl, Node and Python for every endpoint, OpenAPI 3.1 file and Postman collection, so you fit generate client for any language.
Wetin go happen if my webhook endpoint down?
We go retry three more times, after 1 minute, 10 minutes and 1 hour, then we go mark the delivery as failed. You fit resend am from your account or with the API.
Ship PDF features this week.
Create sandbox key in one minute. You no need card.