---
title: "Create workflow"
method: POST
path: "/v1/workspaces/{workspace_id}/workflows"
tags: ["Workflows"]
---

# Create workflow

`POST /v1/workspaces/{workspace_id}/workflows`

## Request

- Base URL: `https://api.stacksync.com`
- URL: `https://api.stacksync.com/v1/workspaces/{workspace_id}/workflows`
- Auth: HTTP bearer

Create a workflow with only its Input step, as the builder's New workflow does: its other steps are saved in its draft once it exists (PATCH /draft), which sets up their triggers. A document refused leaves no workflow behind.

## Path parameters

- `workspace_id` integer, required

## Query parameters

- `region` 'besg' | 'usnv', required

## Headers

- `Idempotency-Key` string, nullable: Makes the create retry-safe for 24 hours: a retry with the same key answers the resource the first call created, with the Idempotent-Replayed: true header, and creates nothing. 1 to 255 visible ASCII characters. The same key with a different request answers 422; while the first call still runs, 409.

## Request body

- CreateWorkflowBody
  - `workflow_name` string, required
  - `workflow_resource_id` string, nullable: A human-readable id, unique in the workspace (lowercase letters, digits and _, at most 60); derived from the name when absent
  - `folder_id` string, nullable: The folder to create it in; the root when absent
  - `is_shared_with_workspace` boolean, nullable
  - `document` WorkflowSchemaModel
    - `workflow_execution_timeout` integer, nullable
    - `workflow_module_execution_timeout` integer, nullable
    - `return_workflow_module_instance_ids` string[], nullable
    - `modules` WorkflowSchemaModuleModel[], required
      - `name` string, required
      - `workflow_module_instance_id` string, required
      - `module_id` string, required
      - `description` string, nullable
      - `properties` object, required
      - `connections` union[]
        - union
          - WorkflowModuleConnectionManagedModelByResourceId
            - `connection_app_type` string, nullable
            - `connection_management_type` string, nullable
            - `connection_resource_id` string, required
          - WorkflowModuleConnectionManagedModelByName
            - `connection_app_type` string, nullable
            - `connection_management_type` string, nullable
            - `connection_name` string, required
          - WorkflowModuleConnectionUserDataModel
            - `connection_data` WorkflowModuleConnectionUserDataValueModel
              - …
            - `connection_management_type` string, nullable
      - `module_options` WorkflowSchemaModuleOptionsModel
        - `patches` object, nullable
        - `layout` WorkflowSchemaModuleOptionsLayoutModel
          - `group_module_instance_id` string, nullable
        - `enable_error_handling` boolean, nullable
        - `workflow_module_execution_timeout` integer, nullable
      - `error_handling_strategy` WorkflowModuleErrorStrategyModel
        - `conditions` WorkflowModuleErrorStrategyConditionModel[]
          - `condition` union, required
            - WorkflowModuleConditionGroupModel
              - …
            - WorkflowModuleConditionValueModel
              - …
            - WorkflowModuleConditionComparatorModel
              - …
          - `retry_policy` WorkflowModuleErrorStrategyConditionActionModel, required
            - `retry_count` integer
            - `retry_interval` integer
        - `else_condition` WorkflowModuleErrorStrategyConditionActionModel
          - `retry_count` integer
          - `retry_interval` integer
    - `edges` WorkflowSchemaEdgeModel[], required
      - `source` WorkflowSchemaEdgeHandleModel, required
        - `handle_id` string, nullable
        - `workflow_module_instance_id` string, required
      - `target` WorkflowSchemaEdgeHandleModel, required
        - `handle_id` string, nullable
        - `workflow_module_instance_id` string, required
      - `edge_id` string, required
  - `validate_only` boolean: Run every check of the write and answer 204 without writing: a refused write answers the error the write would

## Response `201`

Created

- CreatedWorkflow
  - `workflow_id` string, required
  - `workflow_name` string, required
  - `region` 'besg' | 'usnv', required
  - `version` WorkflowVersionSummary, required: A version without its document; step_ids lists its steps (workflow_module_instance_id)
    - `workflow_version` string, required
    - `is_draft` boolean, required
    - `is_deployed` boolean, required
    - `last_modified_time` string, required
    - `step_ids` string[], required
  - `triggers` StepTrigger[], required
    - `step_id` string, required
    - `status` 'succeeded' | 'failed', required: Whether what a step runs alongside the workflow (schedule, email route, Gmail watch, queue consumer...) is set up
    - `msg` string, nullable

## Other responses

- `204`: No Content
- `400`: Bad Request
- `403`: Forbidden
- `409`: Conflict
- `422`: Unprocessable Content

---

[API](https://skmtc.dev/stacksync/apis/stacksync-api.md) - [All operations](https://skmtc.dev/stacksync/apis/stacksync-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stacksync/apis/stacksync-api/revisions/21f4ba4b214e?raw)