Workflows API: Create, Read, Update, Delete DSLs

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.

string

required

A unique, human-readable identifier for this workflow, such as order-flow or payment-retry.

string

required

The broker type this workflow targets. Accepted values: kafka, rabbit.

string

required

The name of the connector to use. Must match a connector saved via the Connectors API.

string

The Kafka topic to publish to. Required when messageType is kafka.

string

The RabbitMQ exchange to publish to. Used when messageType is rabbit.

string

The RabbitMQ routing key. Used when messageType is rabbit.

string

The payload content type. Defaults to json. Use protobuf for Protocol Buffer payloads.

string

Optional identifier of a registered schema to use for payload validation and serialization.

integer

Number of times to execute the pipeline per run. Defaults to 1.

object

Initial workflow-level state map. Values set here are available to pipeline stages via $ref expressions.

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": []
  }
]

string

The unique identifier for this workflow.

string

The broker type: kafka or rabbit.

string

The connector used to dispatch messages.

string | null

The target Kafka topic, or null for RabbitMQ workflows.

string | null

The target RabbitMQ exchange, or null for Kafka workflows.

string | null

The RabbitMQ routing key, or null for Kafka workflows.

integer

Number of executions configured for this workflow.

array

Ordered list of stage definitions.

GET /workflows/

Retrieve the complete DSL document for a single workflow, including all stage definitions. Path parameters

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

string

required

The id of the workflow to replace.

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

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.

DSL Reference

API Reference

Workflows API: Create, Read, Update, Delete DSLs

POST /workflows

GET /workflows

GET /workflows/

PUT /workflows/

DELETE /workflows/

​POST /workflows

​GET /workflows

​GET /workflows/

​PUT /workflows/

​DELETE /workflows/

POST /workflows

GET /workflows

GET /workflows/

PUT /workflows/

DELETE /workflows/