> ## Documentation Index
> Fetch the complete documentation index at: https://docs.promptlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Workflow

Create a new Workflow or create a new version of an existing Workflow programmatically. Use this endpoint when you want to define the full workflow graph, including nodes, edges, input variables, folder placement, release labels, and external IDs.

## Behavior Notes

* To create a new workflow, pass `name`; to create a new version, pass `workflow_id` or `workflow_name`.
* Workflow nodes use the same building blocks as evaluation columns. See [Node & Column Types](/features/evaluations/column-types).
* Conditional edge and workflow authoring concepts are covered in [Workflows](/why-promptlayer/workflows).

## Related

* [Update Workflow](/reference/patch-workflow)
* [Run Workflow](/reference/run-workflow)
* [Workflows](/why-promptlayer/workflows)


## OpenAPI

````yaml POST /rest/workflows
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security:
  - ApiKeyAuth: []
paths:
  /rest/workflows:
    post:
      tags:
        - workflow
      summary: Create Workflow
      operationId: createWorkflow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkflow'
            examples:
              simpleWorkflow:
                summary: Create a simple workflow
                value:
                  name: greeting-workflow
                  commit_message: Initial version
                  nodes:
                    - name: greeting
                      node_type: VARIABLE
                      is_output_node: true
                      configuration:
                        value:
                          type: string
                          value: Hello, World!
                      dependencies: []
                  release_labels:
                    - production
              multipleNodes:
                summary: Create a workflow with multiple nodes
                value:
                  name: classifier-workflow
                  nodes:
                    - name: classify
                      node_type: PROMPT_TEMPLATE
                      is_output_node: false
                      configuration:
                        template:
                          prompt_name: intent-classifier
                          label: production
                      dependencies:
                        - user_message
                    - name: response
                      node_type: PROMPT_TEMPLATE
                      is_output_node: true
                      configuration:
                        template:
                          prompt_name: response-generator
                          label: production
                      dependencies:
                        - classify
                        - user_message
                  required_input_variables:
                    user_message: string
              newVersion:
                summary: Create a new version
                value:
                  workflow_name: my-workflow
                  commit_message: v2 updates
                  nodes:
                    - name: greeting
                      node_type: VARIABLE
                      is_output_node: true
                      configuration:
                        value:
                          type: string
                          value: Hello, World!
                      dependencies: []
                  release_labels:
                    - staging
      responses:
        '201':
          description: Workflow created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWorkflowResponse'
              examples:
                created:
                  summary: Workflow created
                  value:
                    success: true
                    workflow_id: 123
                    workflow_name: greeting-workflow
                    workflow_version_id: 456
                    version_number: 1
                    base_version: null
                    release_labels:
                      - production
                    nodes:
                      - id: node-uuid
                        name: greeting
                        node_type: VARIABLE
                        is_output_node: true
                    required_input_variables: {}
                    external_ids: []
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: External ID conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalIdErrorResponse'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    CreateWorkflow:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          nullable: true
          description: >-
            The name for a new workflow. If not provided, a name will be
            auto-generated.
        workflow_id:
          type: integer
          nullable: true
          description: The ID of an existing workflow to create a new version for.
        workflow_name:
          type: string
          nullable: true
          description: The name of an existing workflow to create a new version for.
        folder_id:
          type: integer
          nullable: true
          description: The folder ID to place the workflow in.
        commit_message:
          type: string
          nullable: true
          description: A message describing the changes in this version.
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowNode'
          description: >-
            Complete list of workflow nodes. At least one node must be marked
            is_output_node=true.
        required_input_variables:
          type: object
          additionalProperties:
            type: string
          description: A mapping of variable names to their types.
        edges:
          type: array
          items:
            $ref: '#/components/schemas/Edge'
          nullable: true
          description: Conditional edges between nodes.
        release_labels:
          type: array
          items:
            type: string
          nullable: true
          description: Labels to attach to this version.
        external_ids:
          type: array
          items:
            $ref: '#/components/schemas/ExternalId'
          description: Identifiers from other systems.
      required:
        - nodes
      description: >-
        Request body for creating a new workflow or a new version of an existing
        workflow. Use name for a new workflow, or workflow_id/workflow_name to
        version an existing workflow.
    CreateWorkflowResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful.
        workflow_id:
          type: integer
          description: The ID of the workflow.
        workflow_name:
          type: string
          description: The name of the workflow.
        workflow_version_id:
          type: integer
          description: The ID of the created workflow version.
        version_number:
          type: integer
          description: The version number.
        base_version:
          type: integer
          nullable: true
          description: The base version this was created from (PATCH only).
        release_labels:
          type: array
          items:
            type: string
          nullable: true
          description: Labels attached to this version.
        nodes:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              node_type:
                type: string
              is_output_node:
                type: boolean
          description: Summary of nodes in the workflow.
        required_input_variables:
          type: object
          additionalProperties:
            type: string
          description: Required input variables for the workflow.
        external_ids:
          type: array
          items:
            $ref: '#/components/schemas/ExternalId'
          description: External ID mappings for the workflow.
      required:
        - success
        - workflow_id
        - workflow_name
        - workflow_version_id
        - version_number
        - external_ids
      description: Response after creating or patching a workflow.
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          default: false
          description: Indicates that the request failed.
        message:
          type: string
          description: Human-readable error message.
        error:
          type: string
          description: Machine-readable or fallback error message.
      additionalProperties: true
      description: >-
        Standard error response. Some legacy endpoints may return either message
        or error.
    ExternalIdErrorResponse:
      properties:
        success:
          type: boolean
          const: false
          default: false
          title: Success
        message:
          type: string
          title: Message
      type: object
      required:
        - message
      title: ExternalIdErrorResponse
    WorkflowNode:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Unique name for the node within this workflow.
        node_type:
          type: string
          description: >-
            The type of node. Common types include VARIABLE, CODE_EXECUTION,
            PROMPT_TEMPLATE, ENDPOINT, COMPARE, CONTAINS, LLM_ASSERTION,
            AI_DATA_EXTRACTION, CODING_AGENT. See Node & Column Types
            documentation for the complete list.
          examples:
            - VARIABLE
            - PROMPT_TEMPLATE
            - CODE_EXECUTION
        configuration:
          type: object
          description: Node-specific configuration.
          additionalProperties: true
        dependencies:
          type: array
          items:
            type: string
          description: Names of nodes or input variables this node depends on.
        is_output_node:
          type: boolean
          description: Whether this node is an output node.
      required:
        - name
        - node_type
        - configuration
        - is_output_node
      example:
        name: greeting
        node_type: VARIABLE
        is_output_node: true
        configuration:
          value:
            type: string
            value: Hello, World!
        dependencies: []
    Edge:
      type: object
      properties:
        source_node_name:
          type: string
          description: The source node name.
        target_node_name:
          type: string
          description: The target node name.
        is_and:
          type: boolean
          description: >-
            Whether multiple conditionals use AND logic (true) or OR logic
            (false).
        conditionals:
          type: array
          items:
            $ref: '#/components/schemas/EdgeConditional'
          minItems: 1
          description: At least one conditional.
      required:
        - source_node_name
        - target_node_name
        - is_and
        - conditionals
    ExternalId:
      properties:
        source:
          type: string
          maxLength: 128
          minLength: 1
          title: Source
          description: The external system or namespace that owns the ID.
        external_id:
          type: string
          maxLength: 512
          minLength: 1
          title: External Id
          description: The identifier for this entity in the external system.
      type: object
      required:
        - source
        - external_id
      additionalProperties: false
      title: ExternalId
      description: >-
        Customer-defined mapping between a PromptLayer entity and an external
        system identifier.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    EdgeConditional:
      type: object
      properties:
        position:
          type: integer
          minimum: 0
          description: Order of evaluation.
        operator:
          type: string
          enum:
            - '='
            - '!='
            - <
            - '>'
            - <=
            - '>='
            - in
            - not_in
            - is_null
            - is_not_null
          description: Comparison operator.
        left_config:
          type: object
          description: Left side of comparison. Can be static_value or source.
        right_config:
          type: object
          description: Right side of comparison. Can be static_value or source.
      required:
        - position
        - operator
        - left_config
        - right_config
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  responses:
    UnauthorizedError:
      description: Unauthorized - missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFoundError:
      description: Not found - requested resource does not exist or is not accessible.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Validation error - request parameters or body are invalid.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/HTTPValidationError'
              - $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````