Developers

Guides

Tasks (PDF tools)

Compress, convert, merge and OCR files with the Macaaw server tools through the API.

Tasks run the website's server tools — compression, Office conversion, OCR and more — on files you upload. One call uploads the files and starts the task; you poll it (or get the task_completed webhook) and download the result.

Available tools#

GET /tools returns every tool with its accepted file types, file count and options. Tools that run in the browser on the website are listed with "runs_on": "browser" and "api": false; they are not available through the API in v1.

Tool idNameAcceptsPlan
word-to-pdfWord to PDFdocfree
excel-to-pdfExcel to PDFxlsfree
powerpoint-to-pdfPowerPoint to PDFpptfree
other-to-pdfOther formats to PDFodf, rtf, pubfree
pdf-to-wordPDF to Wordpdffree
pdf-to-excelPDF to Excelpdffree
pdf-to-powerpointPDF to PowerPointpdffree
edit-pdfEdit PDFpdfpro
compress-pdfCompress PDFpdffree
compress-to-sizeCompress to a sizepdffree
ocr-pdfOCR PDFpdffree
scan-to-officeScan to Word or Excelpdffree
extract-tablesExtract tablespdffree
extract-invoice-dataExtract invoice datapdfpro
protect-pdfProtect PDFpdffree
unlock-pdfUnlock PDFpdffree
compare-pdfCompare PDFspdfpro
repair-pdfRepair PDFpdffree
pdf-to-pdfaPDF to PDF/Apdffree
html-to-pdfHTML to PDFhtmlfree

Start a task#

POST/tasks

Send multipart/form-data with one or more files[] parts and a data part: { "tool": "<tool id>", "options": { … } }. Options are the ones GET /tools lists for that tool; missing options take their defaults.

curl https://macaaw.com/public/v1/tasks \
  -H "Authorization: API-Key $MACAAW_API_KEY" \
  -F "files[]=@report.pdf;type=application/pdf" \
  -F 'data={"tool": "compress-pdf", "options": {}}'
201 Created
{
  "id": "3f0c9a52-6d1e-4c8b-a1f4-0e7d2b9c8a11",
  "tool": "compress-pdf",
  "status": "task.queued",
  "error": null,
  "input_size": 4831022,
  "output_size": null,
  "output_files": null,
  "stats": null,
  "sandbox": false,
  "date_created": "2026-10-30T11:35:00.000000Z",
  "date_completed": null,
  "expires_at": null
}

Task status#

GET/tasks/{id}
StatusMeaning
task.queuedAccepted and waiting for a worker.
task.processingRunning.
task.completedDone. Download the result before expires_at.
task.failedFailed; error holds a code and a plain-English detail.
task.deletedFiles were deleted (by you, or when the retention time passed).
JSON
{
  "id": "3f0c9a52-6d1e-4c8b-a1f4-0e7d2b9c8a11",
  "tool": "compress-pdf",
  "status": "task.completed",
  "error": null,
  "input_size": 4831022,
  "output_size": 1203311,
  "output_files": 1,
  "stats": {},
  "sandbox": false,
  "date_created": "2026-10-30T11:35:00.000000Z",
  "date_completed": "2026-10-30T11:35:09.000000Z",
  "expires_at": "2026-10-30T12:35:09.000000Z"
}

Download and delete#

GET /tasks/{id}/download returns the result file, or a ZIP when the tool produces several files. DELETE /tasks/{id} deletes the files at once.

Files are kept only briefly, as on the website: 1 hour on Free, 1 hour on API plans and 2 hours on Pro and Business. Sandbox tasks process at most 5 pages and their output is stamped.

Limits#

Live tasks count against your plan exactly like tasks on the website: daily tasks, file size, OCR pages, Office conversions and credits. A tool your plan does not include answers 402 with LIMIT_PRO_TOOL; a used-up allowance answers 402 or 429 with another LIMIT_… code (see Errors).

Tasks (PDF tools) · Macaaw API