---
title: "Create a Workflow"
method: POST
path: "/v1/workflows"
tags: ["Workflows API"]
---

# Create a Workflow

`POST /v1/workflows`

Use this endpoint to create a new workflow definition. New workflows are created in `draft` status.

## Request body

- CreateWorkflowInput
  - `description` string — Optional human-readable description of the workflow's purpose.
  - `edges` WorkflowEdgeInput[] — Connections between nodes that define the execution flow. Each edge links a source node to a target node, optionally with a condition.
    - `condition` string — Optional expression evaluated at runtime to determine whether this edge is followed. Supports referencing step outputs and HTTP status codes.
    - `id` string, required — Unique identifier for this edge within the workflow.
    - `label` string — Optional human-readable label for the edge (useful for visual editors).
    - `source` string, required — ID of the source node.
    - `sourceHandle` string — Optional handle identifier on the source node for visual editors.
    - `target` string, required — ID of the target node.
  - `metadata` object — Custom key-value pairs for tagging or categorizing the workflow.
  - `name` string, required — Unique name for the workflow.
  - `nodes` WorkflowNodeInput[] — The steps that make up this workflow. Each node is a unit of work — a trigger, an executor call, a conditional branch, or an action.
    - `data` object — Configuration data specific to the node type (e.g., triggerId for triggers, executorId + URL for executors).
    - `id` string, required — Unique identifier for this node within the workflow. Used in edges to define connections.
    - `name` string — Optional display name for the node.
    - `position` PositionInput, required
      - `x` integer — Horizontal position in pixels.
      - `y` integer — Vertical position in pixels.
    - `type` 'trigger' | 'executor' | 'conditional' | 'action', required — Type of the node: `trigger` (entry point), `executor` (external call), `conditional` (branching logic), or `action` (internal operation).

## Response `201`

Indicates that the resource was successfully created and the operation was completed as expected.

- WorkflowCreateOutput
  - `createdAt` string, date-time — Timestamp when the workflow was created.
  - `status` string — Initial status of the workflow (always `draft` on creation).
  - `version` string — Version of the workflow definition.
  - `workflowId` string, uuid — Unique identifier of the created workflow.

## Other responses

- `400` — Indicates that the request was malformed or contained invalid parameters.
- `409` — Indicates that the request could not be completed due to a conflict with the current state of the resource.
- `500` — Indicates an unexpected internal error. If this persists, please contact support.

---

[API](https://skmtc.net/lerian/apis/identity-plugin.md) · [All operations](https://skmtc.net/lerian/apis/identity-plugin/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lerian/identity-plugin/versions/25daba385532/schema)