Skip to main content

Find your next tool

Docs/API/Workflow API: build and run multi-step workflows
API

Workflow API: build and run multi-step workflows

Create a multi-step document workflow with one API call, run it on one file or hundreds, track every run and download the results.

Short answer

POST https://maxscanner.app/api/v1/workflows/ with a list of steps, for example [{"step":"word-to-pdf"},{"step":"compress-pdf"}]. MaxScanner checks that the chain can run in the cloud, saves it and connects it to your API key, and returns an automationId. Start it with POST /api/v1/automations/{automationId}/runs/ and an Idempotency-Key, follow GET /api/v1/automation-runs/{runId}/, and download each output from /api/v1/documents/{documentId}/download/.

Quickstart

  1. 1GET /api/v1/workflow-steps/ to see the steps, what each accepts and produces, and its settings.
  2. 2POST /api/v1/workflows/ with a name and 1–10 steps. Keep workflow.automationId from the response.
  3. 3Import or upload the files, then POST /api/v1/automations/{automationId}/runs/ with their documentIds and an Idempotency-Key.
  4. 4Poll GET /api/v1/automation-runs/{runId}/ until status is completed, or list all runs of the automation.
  5. 5Download each entry of run.outputs with GET /api/v1/documents/{documentId}/download/.

Why a workflow instead of separate calls

A workflow keeps the chain on MaxScanner's side: the output of one step goes straight into the next without coming back to your server, every run is retried and recorded, and the results land in My Documents. You can open an API-created workflow in Dashboard → Workflows to check it, and you can change the chain later without redeploying your code by creating a new workflow and switching the automation id.

Steps you can use

These steps run on MaxScanner's cloud workers, so a workflow made of them can run without a browser.

stepInput → outputSettings
word-to-pdf, excel-to-pdf, pptx-to-pdf, ppt-to-pdf, rtf-to-pdfOffice file → PDF—
merge-pdf2 or more PDFs → one PDF (first step only)—
compress-pdfPDF → smaller PDF—
rotate-pdfPDF → PDFdegrees: 90, 180 or 270
extract-pagesPDF → PDFpages: "1,3-5" (1-based)
image-transformJPG, PNG or WebP → JPG, PNG, WebP or AVIFformat, quality, maxWidth, maxHeight, width, height, targetBytes
image-ocrJPG, PNG or WebP → text (English)—

Create a workflow

Steps run in the order you list them and each step must accept what the previous one produces; the response is 422 workflow_not_runnable with the reason when they do not fit. Send an Idempotency-Key so a retried request returns the same workflow. Creating a workflow costs one request (one credit on paid plans), and each key can own up to 25 active workflows.

curl -X POST 'https://maxscanner.app/api/v1/workflows/' \
  -H "Authorization: Bearer $MAXSCANNER_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: create-contract-flow-v1' \
  -d '{
    "name": "Contracts to small PDF",
    "steps": [
      { "step": "word-to-pdf" },
      { "step": "compress-pdf" }
    ]
  }'

Run it on one file or many

Inputs are documents already in the account: API imports, uploads completed with /extension/upload/complete/, earlier outputs and Android scans. Each run needs an Idempotency-Key; repeating it never starts a second run. Use "mode": "together" (the default) when the files belong in one run, such as several PDFs for merge-pdf. Use "mode": "each" to start one run per file — up to 100 files in one call. Each run costs 3 credits on paid plans and one request on the Free plan; if the plan limit is reached part-way, the response lists how many files were not started.

const res = await fetch(`https://maxscanner.app/api/v1/automations/${automationId}/runs/`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MAXSCANNER_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'contracts-2026-11-11',
  },
  body: JSON.stringify({
    mode: 'each', // one run per document
    inputs: documentIds.map((documentId) => ({ kind: 'document', documentId })),
  }),
});
const { runs, replayedCount, notStarted } = await res.json();

Track runs and download the results

GET /api/v1/automation-runs/{runId}/ returns the status (reserved, executing, suspended, completed, failed or cancelled) and, once completed, an outputs list with the documentId, filename, type and size of every saved file. GET /api/v1/automations/{automationId}/runs/ lists the latest 100 runs with a count per status, which is the quickest way to follow a bulk call. Status reads are free.

curl 'https://maxscanner.app/api/v1/automation-runs/$RUN_ID/' -H "Authorization: Bearer $MAXSCANNER_API_KEY"

# then, for each output:
curl "https://maxscanner.app/api/v1/documents/$DOCUMENT_ID/download/" -H "Authorization: Bearer $MAXSCANNER_API_KEY"

Manage workflows

Workflows built in the visual editor can be run from the API too: open Dashboard → Workflows → Versions → Run from the API and pick the key. The editor also offers steps that need a person, such as signing, waits and approvals; those stay out of API-created workflows.

  • GET /api/v1/workflows/ lists every workflow this key can start, with its steps
  • GET /api/v1/workflows/{workflowId}/ returns one
  • DELETE /api/v1/workflows/{workflowId}/ disconnects it from the key; workflows created through the API are archived, runs already started finish
  • To change steps, create a new workflow and switch your code to its automationId

Frequently asked questions

Do I have to use the visual editor?

No. POST /api/v1/workflows/ creates the workflow from JSON. The editor is optional, for reviewing it or for steps that are not available through the API.

What is the difference between "together" and "each"?

"together" starts one run that receives every input, which merge-pdf needs. "each" starts a separate run per input, so one bad file does not affect the others and results arrive as each file finishes.

Which permission does the key need?

"Run saved workflows" (workflows:run and workflows:read) to create and run workflows, "Save documents" to import the input files and "Read documents" to download the outputs.

Does a workflow run send a webhook when it finishes?

Not yet. Poll the run or the run list; webhooks are sent for processing jobs started directly with /jobs, /pipeline, /pdf-job and /media/process.

Related guides