Developers

Reference

Tasks

Tools available through the API#

GET/tools

Authorization: API-Key · Rate limit 600 requests / 60 s (sandbox 10 in total)

curl "https://macaaw.com/public/v1/tools" \
  -H "Authorization: API-Key $MACAAW_API_KEY"

Responses#

  • 200OKapplication/json · ToolList
  • 400Validation errorapplication/json · Error
  • 401Missing, unknown or revoked API keyapplication/json · Error
  • 403Plan or permissionapplication/json · Error
  • 404Not foundapplication/json · Error
  • 429Rate limitedapplication/json · Error
    Headers: Retry-After
200 response
{
  "results": [
    {
      "id": "string",
      "name": "string",
      "runs_on": "server",
      "api": true,
      "accepts": [
        "string"
      ],
      "max_files": 1,
      "min_files": 1,
      "plan": "free",
      "beta": true,
      "options": [
        {
          "key": "string",
          "type": "string",
          "choices": [],
          "default": null,
          "min": 1,
          "max": 1,
          "required": true
        }
      ]
    }
  ]
}

Run a server tool#

POST/tasks

Authorization: API-Key · Rate limit 120 requests / 60 s (sandbox 10 in total)

Multipart: files[] and data ({ tool, options }). The task is queued at once.

Headers#

  • Idempotency-Keystring

    Replays the first response for 24 hours.

    max length 255

Request body#

multipart/form-data · required

  • files[]array of string (binary)required
  • dataobjectrequired

    JSON string

    • toolstringrequired
      min length 1 · max length 60
    • optionsobject
curl -X POST "https://macaaw.com/public/v1/tasks" \
  -H "Authorization: API-Key $MACAAW_API_KEY" \
  -F "files[]=@document.pdf;type=application/pdf" \
  -F 'data={"tool":"string","options":{}}'

Responses#

  • 201OKapplication/json · Task
  • 400Validation errorapplication/json · Error
  • 401Missing, unknown or revoked API keyapplication/json · Error
  • 403Plan or permissionapplication/json · Error
  • 404Not foundapplication/json · Error
  • 409Wrong stateapplication/json · Error
  • 413File too largeapplication/json · Error
  • 422Unprocessable fileapplication/json · Error
  • 429Rate limitedapplication/json · Error
    Headers: Retry-After
201 response
{
  "id": "string",
  "tool": "string",
  "status": "task.queued",
  "error": {
    "code": "string",
    "detail": "string"
  },
  "input_size": 1,
  "output_size": 1,
  "output_files": 1,
  "stats": {},
  "sandbox": true,
  "date_created": "2026-10-30T11:35:00.000000Z",
  "date_completed": "2026-10-30T11:35:00.000000Z",
  "expires_at": "2026-10-30T11:35:00.000000Z"
}

Task status#

GET/tasks/{id}

Authorization: API-Key · Rate limit 600 requests / 60 s (sandbox 10 in total)

Path parameters#

  • idstringrequired
curl "https://macaaw.com/public/v1/tasks/$ID" \
  -H "Authorization: API-Key $MACAAW_API_KEY"

Responses#

  • 200OKapplication/json · Task
  • 400Validation errorapplication/json · Error
  • 401Missing, unknown or revoked API keyapplication/json · Error
  • 403Plan or permissionapplication/json · Error
  • 404Not foundapplication/json · Error
  • 429Rate limitedapplication/json · Error
    Headers: Retry-After
200 response
{
  "id": "string",
  "tool": "string",
  "status": "task.queued",
  "error": {
    "code": "string",
    "detail": "string"
  },
  "input_size": 1,
  "output_size": 1,
  "output_files": 1,
  "stats": {},
  "sandbox": true,
  "date_created": "2026-10-30T11:35:00.000000Z",
  "date_completed": "2026-10-30T11:35:00.000000Z",
  "expires_at": "2026-10-30T11:35:00.000000Z"
}

Delete the task files now#

DELETE/tasks/{id}

Authorization: API-Key · Rate limit 600 requests / 60 s (sandbox 10 in total)

Path parameters#

  • idstringrequired
curl -X DELETE "https://macaaw.com/public/v1/tasks/$ID" \
  -H "Authorization: API-Key $MACAAW_API_KEY"

Responses#

  • 204No content
  • 400Validation errorapplication/json · Error
  • 401Missing, unknown or revoked API keyapplication/json · Error
  • 403Plan or permissionapplication/json · Error
  • 404Not foundapplication/json · Error
  • 409Wrong stateapplication/json · Error
  • 429Rate limitedapplication/json · Error
    Headers: Retry-After

Download the result (a ZIP when there are several files)#

GET/tasks/{id}/download

Authorization: API-Key · Rate limit 100 requests / 60 s (sandbox 10 in total)

Path parameters#

  • idstringrequired
curl "https://macaaw.com/public/v1/tasks/$ID/download" \
  -H "Authorization: API-Key $MACAAW_API_KEY" \
  -o result.pdf

Responses#

  • 200Fileapplication/octet-stream · string (binary)
  • 400Validation errorapplication/json · Error
  • 401Missing, unknown or revoked API keyapplication/json · Error
  • 403Plan or permissionapplication/json · Error
  • 404Not foundapplication/json · Error
  • 429Rate limitedapplication/json · Error
    Headers: Retry-After
Tasks API · Macaaw API