Skip to main content
POST
/
rest
/
workflows
Create Workflow
curl --request POST \
  --url https://api.promptlayer.com/rest/workflows \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "nodes": [
    {
      "name": "<string>",
      "node_type": "<string>",
      "configuration": {},
      "is_output_node": true,
      "dependencies": [
        "<string>"
      ]
    }
  ],
  "name": "<string>",
  "workflow_id": 123,
  "workflow_name": "<string>",
  "folder_id": 123,
  "commit_message": "<string>",
  "required_input_variables": {},
  "edges": [
    {
      "source_node_name": "<string>",
      "target_node_name": "<string>",
      "is_and": true,
      "conditionals": [
        {
          "position": 1,
          "operator": "=",
          "left_config": {},
          "right_config": {}
        }
      ]
    }
  ],
  "release_labels": [
    "<string>"
  ]
}
'
{
  "success": true,
  "workflow_id": 123,
  "workflow_name": "<string>",
  "workflow_version_id": 123,
  "version_number": 123,
  "base_version": 123,
  "release_labels": [
    "<string>"
  ],
  "nodes": [
    {
      "id": "<string>",
      "name": "<string>",
      "node_type": "<string>",
      "is_output_node": true
    }
  ],
  "required_input_variables": {}
}
Create a new Workflow or a new version of an existing Workflow programmatically. This endpoint allows you to define the complete workflow configuration including nodes, edges (conditional connections), input variables, and release labels.

​
HTTP Request

POST /rest/workflows

​
Request Body

The request body expects a JSON object with the following structure:

​
Schema

{
  "name": "string (optional, for new workflows)",
  "workflow_id": "integer (optional, for new version of existing workflow)",
  "workflow_name": "string (optional, for new version of existing workflow)",
  "folder_id": "integer (optional)",
  "commit_message": "string (optional)",
  "nodes": [
    {
      "name": "string (required)",
      "node_type": "string (required)",
      "configuration": "object (required)",
      "dependencies": ["string"],
      "is_output_node": "boolean"
    }
  ],
  "required_input_variables": {
    "variable_name": "type"
  },
  "edges": [
    {
      "source_node_name": "string",
      "target_node_name": "string",
      "is_and": "boolean",
      "conditionals": [
        {
          "position": "integer",
          "operator": "string",
          "left_config": "object",
          "right_config": "object"
        }
      ]
    }
  ],
  "release_labels": ["string"]
}

​
Parameters

​
Workflow Identification

  • name (string, optional): The name for a new workflow. If not provided, a name will be auto-generated. Cannot be used with workflow_id or workflow_name.
  • workflow_id (integer, optional): The ID of an existing workflow to create a new version for.
  • workflow_name (string, optional): The name of an existing workflow to create a new version for.
  • folder_id (integer, optional): The folder ID to place the workflow in.

​
Version Details

  • commit_message (string, optional): A message describing the changes in this version.

​
Nodes

Each node represents a step in the workflow:
  • name (string, required): Unique name for the node within this workflow.
  • node_type (string, required): The type of node. See Node Types below.
  • configuration (object, required): Node-specific configuration.
  • dependencies (array of strings, optional): Names of nodes or input variables this node depends on.
  • is_output_node (boolean, required): Whether this node is an output node. At least one node must be an output node.

​
Input Variables

  • required_input_variables (object, optional): A mapping of variable names to their types (e.g., {"user_query": "string"}).

​
Edges (Conditional Connections)

Edges define conditional branching between nodes:
  • source_node_name (string, required): The source node name.
  • target_node_name (string, required): The target node name (must have source in its dependencies).
  • is_and (boolean, required): Whether multiple conditionals use AND logic (true) or OR logic (false).
  • conditionals (array, required): At least one conditional:
    • position (integer): Order of evaluation.
    • operator (string): One of =, !=, <, >, <=, >=, in, not_in, is_null, is_not_null.
    • left_config (object): Left side of comparison.
    • right_config (object): Right side of comparison.

​
Release Labels

  • release_labels (array of strings, optional): Labels to attach to this version (e.g., ["production", "staging"]).

​
Node Types

Workflows use the same node types as evaluation pipelines. For the complete list of supported node types and their detailed configuration options, see the Node & Column Types documentation. Common node types include:
Node TypeDescription
VARIABLEStatic value
CODE_EXECUTIONRun Python or JavaScript code
PROMPT_TEMPLATECall an LLM with a prompt template
ENDPOINTMake an HTTP request
FOR_LOOPIterate over a collection (details)
WHILE_LOOPExecute until condition is met (details)
COMPARECompare two values
CONTAINSCheck if string contains value
LLM_ASSERTIONLLM-based evaluation
AI_DATA_EXTRACTIONExtract structured data
CODING_AGENTClaude Code sandbox

​
Response

Status Code: 201 (Created) 
{
  "success": true,
  "message": "Workflow created successfully",
  "workflow_id": 123,
  "workflow_name": "my-agent",
  "workflow_version_id": 456,
  "version_number": 1,
  "release_labels": ["production"],
  "nodes": [
    {
      "id": "uuid",
      "name": "output_node",
      "node_type": "VARIABLE",
      "is_output_node": true
    }
  ],
  "required_input_variables": {
    "user_input": "string"
  }
}

​
Examples

​
Create a Simple Workflow

import requests

response = requests.post(
    "https://api.promptlayer.com/rest/workflows",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "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"]
    }
)

​
Create a Workflow with Multiple Nodes

response = requests.post(
    "https://api.promptlayer.com/rest/workflows",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "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": "is_urgent",
                "node_type": "CONTAINS",
                "is_output_node": False,
                "configuration": {
                    "source": "classify",
                    "value": "urgent"
                },
                "dependencies": ["classify"]
            },
            {
                "name": "response",
                "node_type": "PROMPT_TEMPLATE",
                "is_output_node": True,
                "configuration": {
                    "template": {
                        "prompt_name": "response-generator",
                        "label": "production"
                    }
                },
                "dependencies": ["classify", "is_urgent", "user_message"]
            }
        ],
        "required_input_variables": {
            "user_message": "string"
        }
    }
)

​
Create a Workflow with Conditional Edges

response = requests.post(
    "https://api.promptlayer.com/rest/workflows",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "name": "routing-workflow",
        "nodes": [
            {
                "name": "router",
                "node_type": "PROMPT_TEMPLATE",
                "is_output_node": False,
                "configuration": {"template": {"prompt_name": "router"}},
                "dependencies": ["query"]
            },
            {
                "name": "sales_handler",
                "node_type": "PROMPT_TEMPLATE",
                "is_output_node": True,
                "configuration": {"template": {"prompt_name": "sales-response"}},
                "dependencies": ["router", "query"]
            },
            {
                "name": "support_handler",
                "node_type": "PROMPT_TEMPLATE",
                "is_output_node": True,
                "configuration": {"template": {"prompt_name": "support-response"}},
                "dependencies": ["router", "query"]
            }
        ],
        "required_input_variables": {"query": "string"},
        "edges": [
            {
                "source_node_name": "router",
                "target_node_name": "sales_handler",
                "is_and": True,
                "conditionals": [{
                    "position": 0,
                    "operator": "=",
                    "left_config": {"type": "source", "source": {"name": "router"}},
                    "right_config": {"type": "static_value", "static_value": "sales"}
                }]
            },
            {
                "source_node_name": "router",
                "target_node_name": "support_handler",
                "is_and": True,
                "conditionals": [{
                    "position": 0,
                    "operator": "=",
                    "left_config": {"type": "source", "source": {"name": "router"}},
                    "right_config": {"type": "static_value", "static_value": "support"}
                }]
            }
        ]
    }
)

​
Create a New Version of an Existing Workflow

# By workflow ID
response = requests.post(
    "https://api.promptlayer.com/rest/workflows",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "workflow_id": 123,
        "commit_message": "Updated configuration",
        "nodes": [...],
        "release_labels": ["staging"]
    }
)

# By workflow name
response = requests.post(
    "https://api.promptlayer.com/rest/workflows",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "workflow_name": "my-workflow",
        "commit_message": "v2 updates",
        "nodes": [...],
        "release_labels": ["production"]
    }
)

​
Error Responses

Status CodeError
400Invalid request body, duplicate name, validation errors
401Missing or invalid API key
404Workflow not found (when using workflow_id or workflow_name)

Headers

​
X-API-KEY
string
required

Your API key for authentication.

Body

application/json

Request body for creating a new workflow or workflow version.

​
nodes
object[]
required

The nodes in the workflow.

​
name
string | null

The name for a new workflow. If not provided, a name will be auto-generated.

Required string length: 1 - 255
​
workflow_id
integer | null

The ID of an existing workflow to create a new version for.

​
workflow_name
string | null

The name of an existing workflow to create a new version for.

​
folder_id
integer | null

The folder ID to place the workflow in.

​
commit_message
string | null

A message describing the changes in this version.

​
required_input_variables
object

A mapping of variable names to their types.

​
edges
object[] | null

Conditional edges between nodes.

​
release_labels
string[] | null

Labels to attach to this version.

Response

Workflow created successfully

Response after creating or patching a workflow.

​
success
boolean
required

Indicates if the request was successful.

​
workflow_id
integer
required

The ID of the workflow.

​
workflow_name
string
required

The name of the workflow.

​
workflow_version_id
integer
required

The ID of the created workflow version.

​
version_number
integer
required

The version number.

​
base_version
integer | null

The base version this was created from (PATCH only).

​
release_labels
string[] | null

Labels attached to this version.

​
nodes
object[]

Summary of nodes in the workflow.

​
required_input_variables
object

Required input variables for the workflow.