REST API

Image, PDF & file processing API

All file processors share one jobs endpoint. Choose the operation with toolName; find parameters and complete examples for every tool below.

1. Create an API key

Register, verify your email and sign in to a free account.
Open Settings → API keys (also available in the user menu), enter a name and create a key.
The full key is shown once. Copy it to your server-side API_KEY environment variable. Revoke and replace a lost key.

Authorization: Bearer $API_KEY

Uploads, jobs, polling, downloads and rule management require a valid API key or a signed-in web session. Use an API key for scripts, MCP and automation; never put it in frontend code. Revoked keys stop working immediately.

Each key allows up to 120 requests/minute by default, including polling. Job quotas are shared across the account and keys: free defaults to 20/day, Pro to 100/day. Read GET /api/tools/entitlements for actual configuration.

2. Upload → create job → poll → download

Request	Input / response
POST /api/tools/files	multipart field file → data.file.id; one file per upload
POST /api/tools/jobs	{toolName, input: {fileId / fileIds, execution: "async", …}} → data.job.id
GET /api/tools/jobs?id=JOB_ID	data.job.status + data.job.result
GET /api/tools/artifacts?id=ARTIFACT_ID&download=1	Authenticated binary download; ID at data.job.result.data.artifact.id
DELETE /api/tools/jobs?id=JOB_ID	Cancel a pending job; terminal jobs may return 409

HTTP 202 (status: accepted) is not completion. Poll every 2 seconds until data.job.status is completed, failed, cancelled or expired. Read success data at data.job.result.data and failure details at data.job.result.error.details. Inspection returns JSON without a download file.

mode: must_pass requires every rule to pass; best_effort can return a candidate with warnings. Send inline rules or a saved ruleId, never both. Single-image tools accept one fileId per job; create a job per image.

Uploads and artifacts normally last 24 hours; use expiresAt. Set Idempotency-Key on job creation and reuse it with the same body after network failures. Free jobs allow 25 MB combined, 100 pages, 40 MP and up to 10 inputs. Pro allows 100 inputs; engine limits still apply.

3. Parameters and examples by tool

File preflight · validate_file

POST /api/tools/validate

file contains supplied facts and rules contains constraints. No bytes are uploaded or inspected. Saved ruleId requires authentication.

{
  "file": {
    "name": "example.png",
    "mimeType": "image/png",
    "bytes": 180000
  },
  "rules": {
    "maxBytes": 200000
  },
  "mode": "must_pass"
}

Open tool and generate code from your form

Compress images · compress_image

POST /api/tools/jobs

fileId, targetBytes (bytes), format, allowDownscale; rules.maxBytes can validate the output.

{
  "toolName": "compress_image",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "format": "jpeg",
    "targetBytes": 200000,
    "allowDownscale": true,
    "execution": "async"
  }
}

Open tool and generate code from your form

Convert images · convert_image

POST /api/tools/jobs

fileId, format; optional background (#RRGGBB) and dpi (JPEG/PNG only).

{
  "toolName": "convert_image",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "format": "webp",
    "execution": "async"
  }
}

Open tool and generate code from your form

Resize images · resize_image

POST /api/tools/jobs

fileId, at least one of width/height (pixels), fit (contain/cover), allowUpscale, format, dpi.

{
  "toolName": "resize_image",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "width": 1200,
    "fit": "contain",
    "allowUpscale": false,
    "format": "jpeg",
    "execution": "async"
  }
}

Open tool and generate code from your form

Crop images · crop_image

POST /api/tools/jobs

fileId, crop: {x,y,width,height} in pixels from the top-left corner; format selects the output type.

{
  "toolName": "crop_image",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "crop": {
      "x": 0,
      "y": 0,
      "width": 200,
      "height": 200
    },
    "format": "png",
    "execution": "async"
  }
}

Open tool and generate code from your form

Remove background · remove_background

POST /api/tools/jobs

Remove the background from an image and download a transparent PNG.

{
  "toolName": "remove_background",
  "input": {
    "fileId": "FILE_ID",
    "execution": "async"
  }
}

Open tool and generate code from your form

Inspect images · inspect_image

POST /api/tools/jobs

fileId; returns decoded dimensions, DPI and EXIF/GPS facts. No download artifact.

{
  "toolName": "inspect_image",
  "input": {
    "fileId": "FILE_ID",
    "execution": "async"
  }
}

Open tool and generate code from your form

Images to PDF · convert_image_to_pdf

POST /api/tools/jobs

fileIds in page order; pageSize (original/a4/letter), pageOrientation (portrait/landscape), marginPoints (0–144 pt), pageDpi (36–600).

{
  "toolName": "convert_image_to_pdf",
  "input": {
    "fileIds": [
      "FILE_ID_1",
      "FILE_ID_2"
    ],
    "mode": "best_effort",
    "pageSize": "a4",
    "pageOrientation": "portrait",
    "marginPoints": 24,
    "pageDpi": 150,
    "execution": "async"
  }
}

Open tool and generate code from your form

Inspect PDF · inspect_file

POST /api/tools/jobs

fileId; returns actual PDF pages, dimensions, fonts and embedded image facts. No download artifact.

{
  "toolName": "inspect_file",
  "input": {
    "fileId": "FILE_ID",
    "execution": "async"
  }
}

Open tool and generate code from your form

Compress PDF · compress_pdf

POST /api/tools/jobs

fileId; rules.maxBytes sets the target in bytes. Strict mode fails with a rule report if the target cannot be met.

{
  "toolName": "compress_pdf",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "rules": {
      "maxBytes": 200000
    },
    "execution": "async"
  }
}

Open tool and generate code from your form

Merge PDFs · merge_pdfs

POST /api/tools/jobs

fileIds, at least 2, merged in array order; optional rules validate the result.

{
  "toolName": "merge_pdfs",
  "input": {
    "fileIds": [
      "FILE_ID_1",
      "FILE_ID_2"
    ],
    "mode": "best_effort",
    "execution": "async"
  }
}

Open tool and generate code from your form

Select PDF pages · split_pdf

POST /api/tools/jobs

fileId, pageRange (e.g. 1-3,5,2) or pages array; page numbers start at 1 and may be reordered or repeated.

{
  "toolName": "split_pdf",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "pageRange": "1-2",
    "execution": "async"
  }
}

Open tool and generate code from your form

Rotate PDF · rotate_pdf

POST /api/tools/jobs

fileId, rotation (90/180/270); optional pageRange/pages, omitted to rotate all pages.

{
  "toolName": "rotate_pdf",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "rotation": 90,
    "pageRange": "1",
    "execution": "async"
  }
}

Open tool and generate code from your form

Submission package · create_submission_package

POST /api/tools/jobs

fileIds, packageName, namingTemplate; free template: {index}-{name}.{ext}. Custom templates require Pro. ZIP includes files, manifest and per-file reports.

{
  "toolName": "create_submission_package",
  "input": {
    "fileIds": [
      "FILE_ID_1",
      "FILE_ID_2"
    ],
    "mode": "best_effort",
    "packageName": "submission-package",
    "namingTemplate": "{index}-{name}.{ext}",
    "execution": "async"
  }
}

Open tool and generate code from your form

Errors, permissions & integrations

401: missing, invalid or revoked key. 403: account/key lacks permission. 429 / rate_limited: request rate or daily quota reached; back off only when retrying is allowed. invalid_input: check parameters. subscription_required: plan capability required. processing_failed/rule failures: inspect error.details. Polling HTTP 200 alone does not mean processing succeeded.

The catalog, OpenAPI and supplied-facts /api/tools/validate endpoint are public. Guest web processing has a separate session/IP-limited path, not anonymous automation credentials. Files, jobs, rules and artifacts are owner-scoped.

Use /api/tools/rules (GET/POST/DELETE) for saved rules and GET /api/tools/jobs for history. OpenAPI contains full schemas. MCP and REST share tools and account quotas. Pro checkout and top-ups are not open yet.

OpenAPI 3.1 MCP Machine-readable catalog

# CLI: ATTACHREADY_BASE_URL + ATTACHREADY_API_KEY
node scripts/tools-cli.mjs run convert_image --input '{"fileId":"FILE_ID","format":"webp"}' --wait