Skip to content

API Reference

The workflow engine exposes a REST API on port 3030 (default). The Swagger UI at http://localhost:3030/api is the authoritative, always-up-to-date API reference with request/response schemas and a “Try it out” feature.

Endpoint Groups

Group Base Path Purpose
Workflow Definitions /workflow-definition Publish, list, delete, and restore workflow definitions (the old create/update routes are removed)
Workflow Executions /workflow-execution Trigger, monitor, and abort workflow executions
Blackboard /blackboard Job polling and result submission (used by workers)
Function Blocks /function-blocks Registration and lookup of function blocks
Workers /workers Worker registration, heartbeat, and lifecycle
Health & Version /health, /version Probes, version info, and SDK compatibility
Schema /schema Workflow JSON Schema (for IDE validation)

Common Operations

Publish a workflow

curl -X POST http://localhost:3030/workflow-definition/publish \
  -H "Content-Type: application/json" \
  -d '{ "workflow": { ... } }'

The request body is one DTO: the workflow document under workflow, with the options (increment, dryRun, acceptBump) beside it. The engine compares the document against the version it would displace and refuses a declared version that doesn’t bump enough to honestly describe the change. See Publishing & Versioning for the full contract – the options, every response status, and the version floor – or Your First Workflow for a walkthrough.

Removed: POST /workflow-definition and POST /workflow-definition/update

The routes /publish replaces are gone and answer 404. See The old routes are gone for the payload mapping if you still have a client on the old shapes.

Delete and restore a workflow definition

curl -X DELETE http://localhost:3030/workflow-definition/wf.example.neops.io%2Fhello_world%3A1.0.0
curl -X POST http://localhost:3030/workflow-definition/wf.example.neops.io%2Fhello_world%3A1.0.0/restore

DELETE soft-deletes: the version stops resolving and disappears from listings, but its number stays taken and its content is kept. POST .../{id}/restore clears the tombstone again (so does republishing the identical document – restore is the way back when you don’t have the original content at hand). Restoring returns 400 if the definition is not soft-deleted, 404 if it does not exist, and 403 if it would exceed the workflow-definition license cap – soft-deleting the last live version of a (package, name) frees a licensed slot, so restoring re-claims one.

Execute a workflow

curl -X POST http://localhost:3030/workflow-execution \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "wf.example.neops.io/hello_world:1.0.0",
    "executeOnParameters": { "ids": [1, 2, 3] },
    "parameters": {}
  }'
Field Description
workflow SemVer identifier (package/name:version)
executeOnParameters.ids Entity IDs to execute on (from CMS). Omit for global workflows
parameters Runtime parameter values matching the workflow’s parameterSchema

Health check

curl http://localhost:3030/health/
# {"status": "ok"}

Get the workflow schema

curl http://localhost:3030/schema/

Returns the full RootWorkflow JSON Schema. Point your IDE at this endpoint for live validation – see IDE Setup.

Swagger UI

For the full list of endpoints, request/response schemas, and interactive testing, open the Swagger UI (requires a running engine).