Skip to main content
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.
​
(workflow DSL)
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
}
​
runId
string
UUID that uniquely identifies this execution. Pass it to /engine/runs/{runId} to poll status or retrieve events.
​
status
string
Initial lifecycle status of the run. Typically PENDING immediately after submission.
​
executions
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.
​
(workflow DSL)
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" }
        }
      ]
    }
  ]
}
​
runId
string
Always "SIMULATION" for simulated runs.
​
status
string
Always "COMPLETED" for a finished simulation.
​
executionCount
integer
Total number of execution groups in the response.
​
executions
array
Ordered list of execution groups, each containing the events produced during that iteration.
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
    }
  ]
}
​
active
array
Runs that are in a non-terminal state (PENDING, RUNNING, or STOPPING).
​
completed
array
Runs that have reached a terminal state (COMPLETED, FAILED, or STOPPED).

​
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
​
runId
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
​
runId
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 }
        }
      ]
    }
  ]
}
​
runId
string
The UUID of the run.
​
status
string
The current status of the run at the time of the request.
​
executionCount
integer
Total number of execution groups in the response.
​
executions
array
Ordered list of execution groups.
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
​
runId
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.