API integration

The module exposes authenticated Magento REST services for definition management, runtime inspection, external triggers and task decisions. Use an integration token whose role contains only the required workflow resources.

Definition management

Supported operations include:

list and retrieve definitions;
save and validate a definition;
simulate and publish a definition;
archive and restore a definition;
list templates;
export and import a definition package.

The routes are under /V1/workflow. Definition codes identify individual resources. Validate and simulate before publishing an API-supplied graph just as you would in Admin.

Start a workflow

POST /V1/workflow/triggers/api/{code} accepts a payload object for a definition with a compatible API trigger. The provider route also accepts the event name, event data and provider. A successful trigger response confirms that work was accepted; the run is still asynchronous.

Example request body:

{
  "payload": {
    "source": "procurement_portal",
    "request_id": "REQ-1048",
    "amount": 789.00
  }
}

Inspect runs and decide tasks

GET /V1/workflow/runs supports limit and offset values. GET /V1/workflow/runs/{runId} returns one run. Task decisions use POST /V1/workflow/tasks/{taskId}/decision with a decisionData object containing an allowed decision and any supported comment data.

Do not retry a task decision blindly after a timeout. Check the task in Magento Admin first because the original request may already have closed it.

Integration safeguards

Keep API-trigger permission separate from workflow publication and task operation. Validate payload size and field count at the sending system as well as in Magento. Use idempotent external reference values where the calling process may retry, and record the returned run identifier for support tracing.