Skip to main content
The Workflows API gives you a durable store for your workflow definitions. You save a workflow here once and then reference it by ID when executing, sharing, or editing it. Every workflow is stored as its full DSL JSON document, and you can retrieve or replace it at any time. All endpoints are relative to http://localhost:8082.

​
POST /workflows

Save a new workflow definition. Devset stores the DSL document and makes it retrievable by the id field you provide inside the body.
​
id
string
required
A unique, human-readable identifier for this workflow, such as order-flow or payment-retry.
​
messageType
string
required
The broker type this workflow targets. Accepted values: kafka, rabbit.
​
producerName
string
required
The name of the connector to use. Must match a connector saved via the Connectors API.
​
topic
string
The Kafka topic to publish to. Required when messageType is kafka.
​
exchange
string
The RabbitMQ exchange to publish to. Used when messageType is rabbit.
​
routingKey
string
The RabbitMQ routing key. Used when messageType is rabbit.
​
contentType
string
The payload content type. Defaults to json. Use protobuf for Protocol Buffer payloads.
​
schemaId
string
Optional identifier of a registered schema to use for payload validation and serialization.
​
executions
integer
Number of times to execute the pipeline per run. Defaults to 1.
​
state
object
Initial workflow-level state map. Values set here are available to pipeline stages via $ref expressions.
​
pipeline
array
required
Ordered list of stage definitions. Each stage describes one message to produce.
Request example 
{
  "id": "order-flow",
  "messageType": "kafka",
  "topic": "orders.events",
  "producerName": "local-kafka",
  "executions": 1,
  "pipeline": [
    {
      "name": "order-created",
      "set": {
        "id": { "$fn": "uuid()" },
        "amount": 42,
        "status": "PENDING"
      }
    },
    {
      "name": "order-confirmed",
      "set": {
        "id": { "$ref": "order-created.id" },
        "status": "CONFIRMED"
      }
    }
  ]
}
Response — 201 Created The full stored workflow document is returned. 
{
  "id": "order-flow",
  "messageType": "kafka",
  "topic": "orders.events",
  "producerName": "local-kafka",
  "executions": 1,
  "pipeline": [
    {
      "name": "order-created",
      "set": {
        "id": { "$fn": "uuid()" },
        "amount": 42,
        "status": "PENDING"
      }
    },
    {
      "name": "order-confirmed",
      "set": {
        "id": { "$ref": "order-created.id" },
        "status": "CONFIRMED"
      }
    }
  ]
}

​
GET /workflows

List all saved workflows. The response is an array of workflow documents. Use GET /workflows/{workflowId} to fetch a specific workflow by ID. Response — 200 OK 
[
  {
    "id": "order-flow",
    "messageType": "kafka",
    "topic": "orders.events",
    "producerName": "local-kafka",
    "executions": 1,
    "pipeline": []
  },
  {
    "id": "payment-retry",
    "messageType": "kafka",
    "topic": "payments.events",
    "producerName": "local-kafka",
    "executions": 3,
    "pipeline": []
  },
  {
    "id": "notification-flow",
    "messageType": "rabbit",
    "exchange": "notifications",
    "routingKey": "user.notified",
    "producerName": "local-rabbit",
    "executions": 1,
    "pipeline": []
  }
]
​
id
string
The unique identifier for this workflow.
​
messageType
string
The broker type: kafka or rabbit.
​
producerName
string
The connector used to dispatch messages.
​
topic
string | null
The target Kafka topic, or null for RabbitMQ workflows.
​
exchange
string | null
The target RabbitMQ exchange, or null for Kafka workflows.
​
routingKey
string | null
The RabbitMQ routing key, or null for Kafka workflows.
​
executions
integer
Number of executions configured for this workflow.
​
pipeline
array
Ordered list of stage definitions.

​
GET /workflows/

Retrieve the complete DSL document for a single workflow, including all stage definitions. Path parameters
​
workflowId
string
required
The id of the workflow to retrieve.
Response — 200 OK 
{
  "id": "order-flow",
  "messageType": "kafka",
  "topic": "orders.events",
  "producerName": "local-kafka",
  "executions": 1,
  "pipeline": [
    {
      "name": "order-created",
      "set": {
        "id": { "$fn": "uuid()" },
        "amount": 42,
        "status": "PENDING"
      }
    }
  ]
}

​
PUT /workflows/

Replace an existing workflow definition entirely. The body must be the full DSL document — partial updates are not supported. Devset overwrites the previously stored definition and returns the updated document. Path parameters
​
workflowId
string
required
The id of the workflow to replace.
​
(workflow DSL)
object
required
The complete, updated workflow DSL document. Must include all required top-level fields and a full pipeline array.
Request example 
{
  "id": "order-flow",
  "messageType": "kafka",
  "topic": "orders.events",
  "producerName": "local-kafka",
  "executions": 1,
  "pipeline": [
    {
      "name": "order-created",
      "set": {
        "id": { "$fn": "uuid()" },
        "amount": 99,
        "status": "PENDING",
        "currency": "USD"
      }
    }
  ]
}
Response — 200 OK 
{
  "id": "order-flow",
  "messageType": "kafka",
  "topic": "orders.events",
  "producerName": "local-kafka",
  "executions": 1,
  "pipeline": [
    {
      "name": "order-created",
      "set": {
        "id": { "$fn": "uuid()" },
        "amount": 99,
        "status": "PENDING",
        "currency": "USD"
      }
    }
  ]
}
If you change the id field inside the body, Devset uses the path parameter workflowId as the authoritative identifier. Avoid changing id in a PUT request to prevent confusion.

​
DELETE /workflows/

Permanently delete a saved workflow definition. This operation cannot be undone. Path parameters
​
workflowId
string
required
The id of the workflow to delete.
Response — 204 No Content An empty 204 No Content response confirms that the workflow was deleted successfully.
Deleting a workflow does not cancel or affect any runs that were already submitted using that workflow. Active runs continue to completion regardless of whether the source definition is deleted.