Engine API: Execute and Monitor Workflow Runs

The Engine API is the core execution layer of Devset. You use it to submit compiled workflow definitions for asynchronous execution, simulate workflows locally without touching any broker, inspect the state of active or historical runs, and retrieve every event emitted during a run. All endpoints are relative to http://localhost:8082.

POST /engine/execute

Submit a workflow for asynchronous execution. Devset compiles your workflow DSL, queues it internally, and returns a runId immediately. Use that ID with the other /engine/runs endpoints to track progress.

object

required

A compiled workflow definition in Devset’s workflow DSL JSON format. See the Workflow DSL reference for the full schema.

Request example

{
  "id": "order-flow",
  "messageType": "kafka",
  "topic": "orders.events",
  "producerName": "local-kafka",
  "pipeline": [
    {
      "name": "order-created",
      "set": { "id": { "$fn": "uuid()" }, "amount": 42, "status": "PENDING" }
    }
  ]
}

Response — 202 Accepted

{
  "runId": "a3f1c2d4-89ab-4e12-b456-426614174000",
  "status": "PENDING",
  "executions": 1
}

string

UUID that uniquely identifies this execution. Pass it to /engine/runs/{runId} to poll status or retrieve events.

string

Initial lifecycle status of the run. Typically PENDING immediately after submission.

integer

The number of executions requested for this run.

POST /engine/simulate

Simulate a workflow without dispatching any messages to a broker. Devset executes the workflow in-process and returns all events synchronously in a single response. Use this to validate payloads and stage logic before running against a live broker.

object

required

A workflow definition in Devset’s workflow DSL JSON format — the same shape accepted by POST /engine/execute.

Request example

{
  "id": "order-flow",
  "messageType": "kafka",
  "topic": "orders.events",
  "producerName": "local-kafka",
  "pipeline": [
    {
      "name": "order-created",
      "set": { "id": "order-123", "amount": 42, "status": "PENDING" }
    }
  ]
}

Response — 200 OK

{
  "runId": "SIMULATION",
  "status": "COMPLETED",
  "executionCount": 1,
  "executions": [
    {
      "executionIndex": 1,
      "eventCount": 1,
      "events": [
        {
          "stageName": "order-created",
          "header": {},
          "payload": { "id": "order-123", "amount": 42, "status": "PENDING" }
        }
      ]
    }
  ]
}

string

Always "SIMULATION" for simulated runs.

string

Always "COMPLETED" for a finished simulation.

integer

Total number of execution groups in the response.

array

Ordered list of execution groups, each containing the events produced during that iteration.

Show Execution group fields

integer

One-based index of this execution iteration.

integer

Number of events produced in this execution.

array

Events produced during this execution iteration.

Show Event fields

string

The name of the workflow stage that emitted this event.

object

Message headers that would have been attached to the broker message.

object

The fully-resolved message payload for this stage.

Use simulate before every deploy to a live environment. It catches payload construction errors and missing field references without producing any noise in your broker.

GET /engine/runs

List all active and completed runs. The response groups runs into two buckets: active for runs that are still in progress and completed for runs that have reached a terminal state. Response — 200 OK

{
  "active": [
    {
      "runId": "a3f1c2d4-89ab-4e12-b456-426614174000",
      "status": "RUNNING",
      "active": true,
      "requestedExecutions": 10,
      "submittedExecutions": 4,
      "completedExecutions": 3,
      "failedExecutions": 0,
      "errorMessage": null
    }
  ],
  "completed": [
    {
      "runId": "b7e2d1a5-12cd-4f89-c567-537725285111",
      "status": "COMPLETED",
      "active": false,
      "requestedExecutions": 5,
      "submittedExecutions": 5,
      "completedExecutions": 5,
      "failedExecutions": 0,
      "errorMessage": null
    }
  ]
}

array

Runs that are in a non-terminal state (PENDING, RUNNING, or STOPPING).

array

Runs that have reached a terminal state (COMPLETED, FAILED, or STOPPED).

Show Run status fields

string

UUID that uniquely identifies the run.

string

Current lifecycle status. One of PENDING, RUNNING, COMPLETED, FAILED, STOPPING, or STOPPED.

boolean

true if the run is in a non-terminal state.

integer

Total number of executions requested when the run was submitted.

integer

Number of executions that have been dispatched so far.

integer

Number of executions that have finished successfully.

integer

Number of executions that encountered an error.

string | null

Error detail if the run reached FAILED status, or null otherwise.

GET /engine/runs/

Retrieve the status of a single run by its ID. The response has the same shape as one element in the active or completed arrays returned by GET /engine/runs. Path parameters

string

required

The UUID of the run to look up.

Response — 200 OK

{
  "runId": "a3f1c2d4-89ab-4e12-b456-426614174000",
  "status": "RUNNING",
  "active": true,
  "requestedExecutions": 10,
  "submittedExecutions": 4,
  "completedExecutions": 3,
  "failedExecutions": 0,
  "errorMessage": null
}

GET /engine/runs//events

Fetch all events emitted during a run, grouped by execution index. Each execution group corresponds to one iteration of the workflow. Path parameters

string

required

The UUID of the run whose events you want to retrieve.

Response — 200 OK

{
  "runId": "a3f1c2d4-89ab-4e12-b456-426614174000",
  "status": "COMPLETED",
  "executionCount": 2,
  "executions": [
    {
      "executionIndex": 1,
      "eventCount": 1,
      "events": [
        {
          "stageName": "order-created",
          "header": {},
          "payload": { "id": "order-123", "amount": 42 }
        }
      ]
    },
    {
      "executionIndex": 2,
      "eventCount": 1,
      "events": [
        {
          "stageName": "order-created",
          "header": {},
          "payload": { "id": "order-456", "amount": 75 }
        }
      ]
    }
  ]
}

string

The UUID of the run.

string

The current status of the run at the time of the request.

integer

Total number of execution groups in the response.

array

Ordered list of execution groups.

Show Execution group fields

integer

One-based iteration index for this group of events.

integer

Number of events in this execution group.

array

All events emitted during this execution iteration.

Show Event fields

string

The workflow stage that produced this event.

object

Headers attached to the broker message.

object

The resolved message payload.

Events are available while the run is in progress. You can poll this endpoint during a RUNNING run to observe events as they are produced.

POST /engine/runs//stop

Request a graceful stop for an active run. Devset transitions the run to STOPPING and allows any in-flight stage to complete before halting. The run status moves to STOPPED once it winds down. The response contains the updated run status at the time the stop was acknowledged. Path parameters

string

required

The UUID of the run to stop.

No request body is required. Response — 202 Accepted

{
  "runId": "a3f1c2d4-89ab-4e12-b456-426614174000",
  "status": "STOPPING",
  "active": true,
  "requestedExecutions": 10,
  "submittedExecutions": 6,
  "completedExecutions": 5,
  "failedExecutions": 0,
  "errorMessage": null
}

Poll GET /engine/runs/{runId} to confirm the run reaches STOPPED status.

Sending a stop request to a run that is already COMPLETED, FAILED, or STOPPED is a no-op. The run status will not change, and you will still receive a 202 response.

DSL Reference

API Reference

Engine API: Execute and Monitor Workflow Runs

POST /engine/execute

POST /engine/simulate

GET /engine/runs

GET /engine/runs/

GET /engine/runs//events

POST /engine/runs//stop

​POST /engine/execute

​POST /engine/simulate

​GET /engine/runs

​GET /engine/runs/

​GET /engine/runs//events

​POST /engine/runs//stop

POST /engine/execute

POST /engine/simulate

GET /engine/runs

GET /engine/runs/

GET /engine/runs//events

POST /engine/runs//stop