Automation port: API reference

Turn the port on in Preferences, Automation. The batch chapter says what it is for.

The automation port is a small HTTP/1.1 API on 127.0.0.1 (port 7431 by default), off until it is turned on in Preferences › Automation.

Rules every request meets

One request per connection: every answer says Connection: close. No answer carries CORS headers. Every answer is JSON; an error is {"error": "<a sentence>"}.

Routes

GET /v1/health

{"ok": true, "app": "AntiPDF", "version": "1.0.4", "jobs_running": 1, "jobs_waiting": 0}

POST /v1/jobs

Starts a job. The body is a job description:

{
  "recipe": "Invoices in",
  "inputs": ["D:\\Scans\\2026-10", "D:\\Scans\\extra.pdf"],
  "output": {"folder": "D:\\Invoices\\2026-10", "suffix": " (processed)",
             "exists": "number", "keep_folders": true, "log": true},
  "dry_run": false,
  "workers": 2,
  "memory_mb": 2048
}

Every path must be absolute and inside the folders allowed in Preferences, as written and as it really is (links followed), unless Any folder is on. A job may name at most 10,000 files and 20 GB in all.

Answers: 202 {"id": "1a04c9ebf9b3a442", "state": "running", "href": "/v1/jobs/1a04c9ebf9b3a442"}; 400 a job that cannot run (the sentence says why: an unknown step or option, steps in an order that cannot work); 403 a path outside the allowed folders, or no folder allowed yet; 404 an input that is not there; 503 sixteen jobs waiting already.

GET /v1/jobs

The jobs kept (the last 64 finished, and all running or waiting), newest first: {"jobs": [{"id": "...", "state": "finished"}]}.

GET /v1/jobs/{id}

{
  "id": "1a04c9ebf9b3a442", "state": "finished", "recipe": "Invoices in",
  "dry_run": false, "seconds": 12.4,
  "counts": {"waiting": 0, "working": 0, "done": 2, "skipped": 1, "failed": 0, "stopped": 0},
  "log": "D:\\Invoices\\2026-10\\AntiPDF batch 2026-10-12 09.31.07.log",
  "files": [
    {"input": "D:\\Scans\\2026-10\\a.pdf", "state": "done",
     "message": "3 scanned pages read. 62% smaller (4.1 MB to 1.5 MB).",
     "outputs": ["D:\\Invoices\\2026-10\\a (processed).pdf"]},
    {"input": "D:\\Scans\\2026-10\\b.pdf", "state": "skipped",
     "message": "It is protected with a password. Open it in AntiPDF and save a copy without the password, then add that copy.",
     "outputs": []}
  ]
}

A job's state: waiting (for a place: two run at once), running, stopping, finished, stopped, or refused (with problem: it could not start, for example a Pro step without Pro). A file's state: waiting, working (with step, counted from 1), done, skipped, failed, stopped.

DELETE /v1/jobs/{id}

Stops a job after the steps in progress: 202 {"id": "...", "state": "stopping"}. A job not started yet, or finished, answers 200 with its state.

Steps

Each step is {"do": "<step>", <options>}. Unknown steps and options are refused with their names.

Examples

Make every scan in a folder searchable, as text files next to them:

curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"steps": [{"do": "ocr"}, {"do": "text"}], "inputs": ["D:\\Scans"], "output": {"suffix": ""}}' \
  http://127.0.0.1:7431/v1/jobs

Wait for a job in Python:

import json, time, urllib.request
TOKEN, BASE = "<the token>", "http://127.0.0.1:7431"
def call(method, path, body=None):
    req = urllib.request.Request(BASE + path, method=method,
        data=json.dumps(body).encode() if body is not None else None,
        headers={"Authorization": "Bearer " + TOKEN, "Content-Type": "application/json"})
    with urllib.request.urlopen(req) as r:
        return json.load(r)
job = call("POST", "/v1/jobs", {"recipe": "Invoices in", "inputs": [r"D:\Scans\2026-10"],
                                "output": {"folder": r"D:\Invoices\2026-10"}})
while (state := call("GET", "/v1/jobs/" + job["id"]))["state"] in ("waiting", "running", "stopping"):
    time.sleep(2)
for f in state["files"]:
    print(f["state"], f["input"], f.get("message", ""))

Always check redacted copies before you send them.