Update Agent (PATCH)

Partially update an Agent by creating a new version with merged changes. This endpoint allows you to modify specific nodes without resending the entire configuration. The PATCH operation:

Fetches the specified base version (or latest if not specified)
Merges your node updates with existing nodes
Creates a new version with the merged configuration

Please note that this feature was previously called “Workflows” and is now called “Agents”. Some references to “Workflows” remain in our SDK and will be updated before the feature exits beta.

HTTP Request

PATCH /rest/workflows/{workflow_id_or_name}

Path Parameters

workflow_id_or_name (string, required): The ID or name of the Agent to update.

Request Body

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

Schema

{
  "base_version": "integer (optional)",
  "commit_message": "string (optional)",
  "nodes": {
    "node_name": {
      "node_type": "string (optional)",
      "configuration": "object (optional)",
      "dependencies": ["string"] "(optional)",
      "is_output_node": "boolean (optional)"
    },
    "node_to_remove": null
  },
  "required_input_variables": {
    "variable_name": "type"
  },
  "edges": [...],
  "release_labels": ["string"]
}

Parameters

Version Control

base_version (integer, optional): The version number to base changes on. Defaults to the latest version.
commit_message (string, optional): A message describing the changes.

Node Updates

The nodes object is keyed by node name:

Updating a node: Provide the node name with an object containing the fields to update. Unspecified fields are preserved from the base version.
Removing a node: Set the node name to null.
Adding a node: Provide a node name that doesn’t exist in the base version with node_type and configuration (required for new nodes). See Node & Column Types for available node types.

Other Fields

required_input_variables (object, optional): If provided, replaces the input variables entirely.
edges (array, optional): If provided, replaces edges entirely. If not provided, edges are copied from the base version (excluding edges referencing removed nodes).
release_labels (array of strings, optional): Labels to attach to the new version.

Response

Status Code: 201 (Created)

{
  "success": true,
  "message": "Workflow version created successfully",
  "workflow_id": 123,
  "workflow_name": "my-agent",
  "workflow_version_id": 789,
  "version_number": 3,
  "base_version": 2,
  "release_labels": ["staging"],
  "nodes": [
    {
      "id": "uuid",
      "name": "updated_node",
      "node_type": "VARIABLE",
      "is_output_node": true
    }
  ],
  "required_input_variables": {
    "user_input": "string"
  }
}

Examples

Update a Single Node’s Configuration

Update just the configuration of one node while preserving everything else:

import requests

response = requests.patch(
    "https://api.promptlayer.com/rest/workflows/my-agent",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "commit_message": "Updated prompt template version",
        "nodes": {
            "response_generator": {
                "configuration": {
                    "template": {
                        "prompt_name": "response-v2",
                        "label": "production"
                    }
                }
            }
        }
    }
)

Add a New Node

Add a new node to an existing agent:

response = requests.patch(
    "https://api.promptlayer.com/rest/workflows/my-agent",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "commit_message": "Added logging node",
        "nodes": {
            "logger": {
                "node_type": "CODE_EXECUTION",
                "configuration": {
                    "code": "print(f'Processing: {input_data}')",
                    "language": "PYTHON"
                },
                "dependencies": ["input_data"],
                "is_output_node": False
            }
        }
    }
)

Remove a Node

Remove a node from the agent:

response = requests.patch(
    "https://api.promptlayer.com/rest/workflows/my-agent",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "commit_message": "Removed deprecated node",
        "nodes": {
            "old_processor": None  # This removes the node
        }
    }
)

Branch from a Specific Version

Create a new version based on an older version (not the latest):

response = requests.patch(
    "https://api.promptlayer.com/rest/workflows/my-agent",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "base_version": 5,  # Branch from version 5
        "commit_message": "Hotfix based on v5",
        "nodes": {
            "output": {
                "configuration": {
                    "value": {"type": "string", "value": "fixed"}
                }
            }
        }
    }
)

Update Multiple Nodes at Once

response = requests.patch(
    "https://api.promptlayer.com/rest/workflows/my-agent",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "commit_message": "Major update",
        "nodes": {
            "node_a": {
                "configuration": {"value": {"type": "string", "value": "updated_a"}}
            },
            "node_b": {
                "dependencies": ["node_a", "new_input"]
            },
            "old_node": None,  # Remove this node
            "new_node": {      # Add this node
                "node_type": "VARIABLE",
                "configuration": {"value": {"type": "string", "value": "new"}},
                "dependencies": [],
                "is_output_node": False
            }
        },
        "required_input_variables": {
            "original_input": "string",
            "new_input": "string"
        },
        "release_labels": ["staging"]
    }
)

Update and Deploy to Production

response = requests.patch(
    "https://api.promptlayer.com/rest/workflows/123",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "commit_message": "Production deploy",
        "nodes": {
            "response": {
                "configuration": {
                    "template": {"prompt_name": "prod-response", "label": "production"}
                }
            }
        },
        "release_labels": ["production"]  # Move production label to this version
    }
)

Merge Behavior

Field	Merge Behavior
`nodes`	Merge by name - update matching, keep unmentioned, remove null
`nodes[name].configuration`	Deep merge with existing config
`nodes[name].dependencies`	Full replace (not merged)
`nodes[name].is_output_node`	Update if specified
`required_input_variables`	Full replace if specified
`edges`	Full replace if specified, otherwise copied from base
`release_labels`	Move labels to new version

Error Responses

Status Code	Error
400	Validation error, no output nodes, invalid dependencies
401	Missing or invalid API key
404	Workflow not found, base version not found

Headers

X-API-KEY

string

required

Your API key for authentication.

Path Parameters

workflow_id_or_name

string

required

The ID or name of the workflow to update.

Body

application/json

Request body for partially updating a workflow.

base_version

integer | null

The version number to base changes on. Defaults to the latest version.

commit_message

string | null

A message describing the changes.

nodes

object

Node updates keyed by node name. Use null to remove a node.

Show child attributes

required_input_variables

object

If provided, replaces the input variables entirely.

Show child attributes

edges

object[] | null

If provided, replaces edges entirely.

Show child attributes

release_labels

string[] | null

Labels to attach to the new version.

Response

Workflow version 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.

Show child attributes

required_input_variables

object

Required input variables for the workflow.

Show child attributes

Get Started

Languages & Environments

Usage Documentation

Why PromptLayer?

Reference

HTTP Request

Path Parameters

Request Body

Schema

Parameters

Version Control

Node Updates

Other Fields

Response

Examples

Update a Single Node’s Configuration

Add a New Node

Remove a Node

Branch from a Specific Version

Update Multiple Nodes at Once

Update and Deploy to Production

Merge Behavior

Error Responses

Headers

Path Parameters

Body

Response

Get Started

Languages & Environments

Usage Documentation

Why PromptLayer?

Reference

​HTTP Request

​Path Parameters

​Request Body

​Schema

​Parameters

​Version Control

​Node Updates

​Other Fields

​Response

​Examples

​Update a Single Node’s Configuration

​Add a New Node

​Remove a Node

​Branch from a Specific Version

​Update Multiple Nodes at Once

​Update and Deploy to Production

​Merge Behavior

​Error Responses

Headers

Path Parameters

Body

Response

HTTP Request

Path Parameters

Request Body

Schema

Parameters

Version Control

Node Updates

Other Fields

Response

Examples

Update a Single Node’s Configuration

Add a New Node

Remove a Node

Branch from a Specific Version

Update Multiple Nodes at Once

Update and Deploy to Production

Merge Behavior

Error Responses