> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Create a Workflow > Use this endpoint to create a new workflow definition. New workflows are created in `draft` status. ## OpenAPI ````yaml en/openapi/v3-current/flowker.yaml post /v1/workflows openapi: 3.1.0 info: description: >- Complete API reference for Flowker workflow orchestration services including catalog management, workflow definitions, executor configurations, provider configurations, and workflow executions. title: Flowker API version: 1.2.0 servers: - url: https://flowker.sandbox.lerian.net security: - BearerAuth: [] tags: - name: Catalog API description: >- Browse built-in providers, executors, and triggers available in the Flowker catalog. - name: Workflows API description: >- Create, update, activate, deactivate, clone, and delete workflow definitions. - name: Executions API description: Start workflow executions and track their status and results. - name: Executor Configurations API description: >- List, inspect, update, and delete the executor configuration records a deployment holds. - name: Provider Configurations API description: >- Create, update, enable, and disable the provider configurations that workflow nodes call through. - name: Dashboard API description: >- Retrieve aggregated summaries of workflows and executions for operational dashboards. - name: Webhooks API description: >- Receive webhook callbacks from external systems to trigger workflow executions. - name: Schedule API description: >- Inspect a workflow's upcoming, skipped, and parked scheduled occurrences, and run or discard the parked ones. - name: Schema Registry API description: >- Publish global OpenAPI specification versions for native services and pin the version each tenant resolves against. - name: OpenAPI Schemas API description: >- Upload, inspect, and delete the tenant's external OpenAPI schemas, and derive the contract of a single operation. - name: XSD Schemas API description: >- Upload, inspect, and delete the tenant's XSD schemas used to validate XML webhook payloads. paths: /v1/workflows: post: tags: - Workflows API summary: Create a Workflow description: >- Use this endpoint to create a new workflow definition. New workflows are created in `draft` status. operationId: createWorkflow requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateWorkflowInput' description: Request body containing the workflow definition. required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/WorkflowCreateOutput' description: >- Indicates that the resource was successfully created and the operation was completed as expected. '400': content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Indicates that the request was malformed or contained invalid parameters. '409': content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Indicates that the request could not be completed due to a conflict with the current state of the resource. '500': content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Indicates an unexpected internal error. If this persists, please contact support. components: schemas: CreateWorkflowInput: example: name: Payment Notification Flow description: Receives a webhook trigger and logs the payment event. nodes: - id: trigger-1 type: trigger name: Webhook Trigger position: x: 0 'y': 0 data: triggerType: webhook path: payments/received method: POST input_contract: open format: json - id: log-event type: action name: Log Payment Event position: x: 200 'y': 0 data: action: log edges: - id: e1 source: trigger-1 target: log-event metadata: team: payments environment: sandbox properties: description: description: Optional human-readable description of the workflow's purpose. example: Receives a webhook trigger and logs the payment event. maxLength: 500 type: string edges: description: >- Connections between nodes that define the execution flow. Each edge links a source node to a target node. Branching is routed by the edge's `sourceHandle`, which must match the outcome handle its conditional source node produces. items: $ref: '#/components/schemas/WorkflowEdgeInput' maxItems: 200 type: array metadata: additionalProperties: type: object description: Custom key-value pairs for tagging or categorizing the workflow. example: team: payments environment: sandbox type: object name: description: Unique name for the workflow. example: Payment Notification Flow maxLength: 100 minLength: 1 type: string nodes: description: >- 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. items: $ref: '#/components/schemas/WorkflowNodeInput' maxItems: 100 type: array required: - name type: object WorkflowCreateOutput: properties: createdAt: description: Timestamp when the workflow was created. example: '2026-03-17T14:30:00Z' format: date-time type: string status: description: Initial status of the workflow (always `draft` on creation). example: draft type: string version: description: Version of the workflow definition. example: 1.0.0 type: string workflowId: description: Unique identifier of the created workflow. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 format: uuid type: string type: object ErrorResponse: properties: code: description: Stable, machine-readable Flowker error code. example: FLK-0001 type: string detail: description: >- Human-readable explanation of this occurrence. Responses with a status of 500 or above carry a fixed generic message. example: name is a required field type: string errors: description: Per-field entries for a request that failed validation. items: $ref: '#/components/schemas/ErrorDetail' type: array instance: description: URI reference identifying this specific occurrence. example: /v1/workflows format: uri type: string status: description: HTTP status code. example: 400 type: integer title: description: >- Standard HTTP reason phrase for the status. It does not change per error code. example: Bad Request type: string type: description: >- URI reference identifying the error. Always the error catalog base followed by the code. example: https://errors.lerian.studio/v1/FLK-0001 format: uri type: string type: object WorkflowEdgeInput: properties: condition: description: >- Legacy free-text edge condition, retained for backward compatibility and not evaluated for routing. Leave it empty for new workflows and route with sourceHandle. example: '' maxLength: 500 type: string id: description: Unique identifier for this edge within the workflow. example: e1 maxLength: 50 minLength: 1 type: string label: description: >- Optional human-readable label for the edge (useful for visual editors). example: On success maxLength: 50 type: string source: description: ID of the source node. example: trigger-1 maxLength: 50 minLength: 1 type: string sourceHandle: description: >- Selects which output of the source node this edge follows. Required to route out of a conditional node, where it must equal the winning branch handle — a case output such as `case-1`, the `default` branch, or a boolean handle (`true`/`false`) for a free-text condition. Routing is driven by this handle. example: case-1 maxLength: 50 type: string target: description: ID of the target node. example: log-event maxLength: 50 minLength: 1 type: string required: - id - source - target type: object WorkflowNodeInput: properties: data: additionalProperties: type: object description: >- Configuration data specific to the node type (e.g., triggerType plus the trigger settings for triggers, executorId and providerConfigId for executors). example: triggerType: webhook path: payments/received method: POST input_contract: open format: json type: object id: description: >- Unique identifier for this node within the workflow. Used in edges to define connections. example: trigger-1 maxLength: 50 minLength: 1 type: string name: description: Optional display name for the node. example: Webhook Trigger maxLength: 50 type: string position: $ref: '#/components/schemas/PositionInput' type: description: >- Type of the node: `trigger` (entry point), `executor` (external call), `conditional` (branching logic), or `action` (internal operation). enum: - trigger - executor - conditional - action example: trigger type: string required: - id - position - type type: object ErrorDetail: properties: location: description: Where the problem is, such as body.nodes or path.id. example: body.nodes type: string message: description: Description of the field-level problem. example: expected array length >= 1 type: string value: description: The value that caused the error, when it is safe to echo. type: object PositionInput: properties: x: description: Horizontal position in pixels. example: 100 type: integer 'y': description: Vertical position in pixels. example: 200 type: integer type: object securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer token issued by the identity provider. Send it in the Authorization header as `Bearer `. ````