Skip to main content
PATCH
/
v1
/
workflows
/
{workflow_id}
Update Workflow
curl --request PATCH \
  --url https://api.xpander.ai/v1/workflows/{workflow_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "organization_id": "<string>",
  "agent_id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "icon": "<string>",
  "avatar": "<string>",
  "model_name": "<string>",
  "llm_api_base": "<string>",
  "llm_credentials_key": "<string>",
  "llm_credentials": {
    "name": "<string>",
    "value": "<string>",
    "description": "<string>"
  },
  "llm_extra_headers": {},
  "instructions": {
    "role": [],
    "goal": [],
    "general": ""
  },
  "expected_output": "<string>",
  "output_schema": {},
  "orchestration_nodes": [
    {
      "definition": {
        "code": "<string>"
      },
      "id": "<string>",
      "next_node_ids": [
        "<string>"
      ],
      "name": "<string>",
      "description": "<string>",
      "condition": {
        "term": "<string>",
        "group_id": "<string>",
        "path": "<string>",
        "value": null
      },
      "retry_strategy": {
        "enabled": false,
        "max_retries": 3
      },
      "iterative_strategy": {
        "enabled": false,
        "max_iterations": 3,
        "end_condition": {
          "term": "<string>",
          "group_id": "<string>",
          "path": "<string>",
          "value": null
        }
      },
      "stop_strategy": {
        "enabled": false,
        "stop_on_failure": true,
        "stop_on_condition": {
          "term": "<string>",
          "group_id": "<string>",
          "path": "<string>",
          "value": null
        }
      },
      "input_type": "text",
      "input_schema": {},
      "input_instructions": "<string>",
      "agentic_context_input_instructions": "<string>",
      "agentic_context_output_instructions": "<string>",
      "return_this": false
    }
  ],
  "task_level_strategies": {
    "retry_strategy": {
      "enabled": false,
      "max_retries": 3
    },
    "iterative_strategy": {
      "enabled": false,
      "max_iterations": 3,
      "end_condition": {
        "term": "<string>",
        "group_id": "<string>",
        "path": "<string>",
        "value": null
      }
    },
    "stop_strategy": {
      "enabled": false,
      "stop_on_failure": true,
      "stop_on_condition": {
        "term": "<string>",
        "group_id": "<string>",
        "path": "<string>",
        "value": null
      }
    },
    "max_runs_per_day": 123,
    "agentic_context_enabled": false,
    "duplication_prevention": {
      "selectors": [
        "<string>"
      ],
      "enabled": false,
      "ttl_minutes": 10
    }
  },
  "notification_settings": {
    "on_success": {},
    "on_error": {}
  },
  "source_nodes": [
    {
      "id": "<string>",
      "targets": [
        "<string>"
      ],
      "metadata": {}
    }
  ],
  "environment_id": "<string>",
  "using_nemo": true,
  "on_prem_event_streaming": true,
  "use_oidc_pre_auth": true,
  "pre_auth_audiences": [
    "<string>"
  ],
  "use_oidc_pre_auth_token_for_llm": true,
  "oidc_pre_auth_token_llm_audience": "<string>",
  "oidc_pre_auth_token_mcp_audience": "<string>"
}
'
{
  "name": "<string>",
  "organization_id": "<string>",
  "webhook_url": "<string>",
  "id": "<string>",
  "unique_name": "<string>",
  "origin_template": "<string>",
  "environment_id": "<string>",
  "deployment_type": "serverless",
  "prompts": [],
  "is_latest": false,
  "has_pending_changes": false,
  "deep_planning": false,
  "enforce_deep_planning": false,
  "connectivity_details": {},
  "framework": "agno",
  "description": "",
  "tools": [],
  "icon": "🚀",
  "avatar": "male-avatar",
  "source_nodes": [],
  "attached_tools": [],
  "access_scope": "personal",
  "instructions": {
    "role": [],
    "goal": [],
    "general": ""
  },
  "oas": {},
  "graph": [],
  "status": "ACTIVE",
  "knowledge_bases": [],
  "version": 1,
  "created_by": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "using_nemo": false,
  "deletable": true,
  "model_provider": "anthropic",
  "model_name": "claude-sonnet-4-6",
  "llm_reasoning_effort": "medium",
  "llm_api_base": "<string>",
  "output_format": "markdown",
  "voice_id": "<string>",
  "output_schema": {},
  "llm_credentials_key": "<string>",
  "llm_credentials_key_type": "xpander",
  "llm_credentials": {
    "name": "<string>",
    "value": "<string>",
    "description": "<string>"
  },
  "llm_extra_headers": {},
  "expected_output": "",
  "agno_settings": {
    "session_storage": true,
    "learning": false,
    "agent_memories": false,
    "agentic_culture": false,
    "user_memories": false,
    "agentic_memory": false,
    "session_summaries": false,
    "num_history_runs": 10,
    "max_tool_calls_from_history": 0,
    "tool_call_limit": 0,
    "coordinate_mode": true,
    "pii_detection_enabled": false,
    "pii_detection_mask": true,
    "prompt_injection_detection_enabled": false,
    "openai_moderation_enabled": false,
    "reasoning_tools_enabled": false,
    "tool_calls_compression": {
      "enabled": false,
      "instructions": "",
      "threshold": 3
    },
    "max_plan_retries": 15,
    "plan_retry_strategy": "tiered"
  },
  "on_prem_event_streaming": true,
  "is_supervised": false,
  "orchestration_nodes": [],
  "notification_settings": {},
  "task_level_strategies": {
    "retry_strategy": {
      "enabled": false,
      "max_retries": 3
    },
    "iterative_strategy": {
      "enabled": false,
      "max_iterations": 3,
      "end_condition": {
        "term": "<string>",
        "group_id": "<string>",
        "path": "<string>",
        "value": null
      }
    },
    "stop_strategy": {
      "enabled": false,
      "stop_on_failure": true,
      "stop_on_condition": {
        "term": "<string>",
        "group_id": "<string>",
        "path": "<string>",
        "value": null
      }
    },
    "max_runs_per_day": 123,
    "agentic_context_enabled": false,
    "duplication_prevention": {
      "selectors": [
        "<string>"
      ],
      "enabled": false,
      "ttl_minutes": 10
    }
  },
  "use_oidc_pre_auth": false,
  "pre_auth_audiences": [],
  "use_oidc_pre_auth_token_for_llm": false,
  "oidc_pre_auth_token_llm_audience": "<string>",
  "oidc_pre_auth_token_mcp_audience": "<string>"
}
Modify a workflow’s configuration — update its node graph, instructions, model settings, or notification rules. Only provided fields will be updated.

​
Path Parameters

​
workflow_id
string
required
Unique identifier of the workflow (UUID)

​
Query Parameters

​
deploy
boolean
default:false
Automatically deploy the workflow after updating to apply changes immediately. Without this, changes are staged but not active until a PUT deploy call.

​
Request Body

All fields are optional. Only provided fields will be updated.
​
name
string
Display name
​
description
string
Workflow description
​
instructions
object
System instructions for the orchestrator
​
orchestration_nodes
array
Updated node graph — the full canvas definition with node types, instructions, and connections
​
model_provider
string
LLM provider
​
model_name
string
Model version
​
task_level_strategies
object
Task-level strategies for retry, stop, and iteration
​
notification_settings
object
Notification configuration
​
output_format
string
Output format: text or json
​
output_schema
object
JSON schema for structured output
​
status
string
Workflow status: ACTIVE or INACTIVE

​
Response

Returns the updated WorkflowResponse object.

​
Example Request

curl -X PATCH -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Workflow Name", "description": "New description"}' \
  "https://api.xpander.ai/v1/workflows/<workflow-id>?deploy=true"

​
Notes

  • Use deploy=true to immediately apply changes
  • Without deploy=true, changes are staged and require a separate Deploy Workflow call

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
workflow_id
string
required

Query Parameters

​
deploy
boolean
default:false

Automatically deploy the workflow after updating to apply changes immediately. Without this, changes are staged but not active until a PUT deploy call.

Body

application/json

Request model for updating an existing workflow.

All fields are optional — only provide the fields you want to change. At least one field must be provided. The workflow type remains 'orchestration' and cannot be changed.

​
organization_id
string | null
​
agent_id
string | null
​
name
string | null

Workflow name.

​
description
string | null

Workflow description.

​
icon
string | null

Emoji icon.

​
avatar
string | null

Avatar identifier.

​
status
enum<string> | null

Workflow status: 'ACTIVE' or 'INACTIVE'.

Available options:
DRAFT,
ACTIVE,
INACTIVE
​
model_provider
enum<string> | null

Default LLM provider.

Available options:
openai,
nim,
amazon_bedrock,
azure_ai_foundary,
huggingFace,
friendlyAI,
anthropic,
gemini,
fireworks,
google_ai_studio,
helicone,
bytedance,
tzafon_lightcone,
open_router,
nebius,
cloudflare_ai_gw
​
model_name
string | null

Default model name.

​
llm_reasoning_effort
enum<string> | null

Reasoning depth.

Available options:
low,
medium,
high,
xhigh
​
llm_api_base
string | null

Custom LLM API base URL.

​
llm_credentials_key
string | null

LLM credentials key.

​
llm_credentials_key_type
enum<string> | null

Credential type.

Available options:
xpander,
custom
​
llm_credentials
LLMCredentials · object

Direct LLM credentials.

​
llm_extra_headers
Llm Extra Headers · object

Extra LLM headers.

​
instructions
AIAgentInstructions · object

Workflow instructions.

​
expected_output
string | null

Expected output description.

​
output_format
enum<string> | null

Output format.

Available options:
text,
markdown,
json,
voice
​
output_schema
Output Schema · object

JSON Schema for output.

​
orchestration_nodes
OrchestrationNode · object[] | null

Updated workflow DAG nodes.

​
task_level_strategies
TaskLevelStrategies · object

Execution strategies.

​
notification_settings
NotificationSettings · object

Notification settings.

​
source_nodes
AIAgentSourceNode · object[] | null

Trigger source nodes.

​
deployment_type
enum<string> | null

Deployment type.

Available options:
serverless,
container
​
access_scope
enum<string> | null

Access scope.

Available options:
personal,
organizational
​
environment_id
string | null

Target environment.

​
using_nemo
boolean | null

NeMo guardrails.

​
on_prem_event_streaming
boolean | null

Event streaming.

​
use_oidc_pre_auth
boolean | null

OIDC pre-auth.

​
pre_auth_audiences
string[] | null

OIDC audiences.

​
use_oidc_pre_auth_token_for_llm
boolean | null

Forward OIDC to LLM.

​
oidc_pre_auth_token_llm_audience
string | null

OIDC LLM audience.

​
oidc_pre_auth_token_mcp_audience
string | null

OIDC MCP audience.

Response

Successful Response

Response model for workflow endpoints.

Inherits from AIAgent but excludes agent-specific fields that are not relevant to workflows (orchestrations). This provides a clean API surface for workflow consumers without exposing confusing agent-only concepts.

The workflow's execution logic is defined in orchestration_nodes — a DAG of typed nodes. Agent-specific fields like graph, attached_tools, delegation_*, framework, and agno_settings are hidden.

​
name
string
required
​
organization_id
string
required
​
webhook_url
string
required
read-only
​
id
string | null
​
unique_name
string | null
​
origin_template
string | null
​
environment_id
string | null
​
deployment_type
enum<string> | null
default:serverless
Available options:
serverless,
container
​
prompts
string[] | null
​
is_latest
boolean | null
default:false
​
has_pending_changes
boolean | null
default:false
​
deep_planning
boolean | null
default:false
​
enforce_deep_planning
boolean | null
default:false
​
connectivity_details
AIAgentConnectivityDetailsA2A · object
​
framework
string | null
default:agno
​
description
string | null
default:""
​
tools
any[] | null
​
icon
string | null
default:🚀
​
avatar
string | null
default:male-avatar
​
source_nodes
AIAgentSourceNode · object[] | null
​
attached_tools
Connector · object[] | null
​
access_scope
enum<string> | null
default:personal
Available options:
personal,
organizational
​
instructions
AIAgentInstructions · object
​
oas
Oas · object
​
graph
AIAgentGraphItem · object[] | null
​
status
enum<string> | null
default:ACTIVE

Enumeration of possible agent statuses.

Attributes: DRAFT: Agent is in a draft state. ACTIVE: Agent is active and operational. INACTIVE: Agent is inactive and not operational.

Available options:
DRAFT,
ACTIVE,
INACTIVE
​
knowledge_bases
AgentKnowledgeBase · object[] | null
​
version
integer | null
default:1
​
created_by
string | null
​
created_at
string<date-time> | null
​
type
enum<string> | null

Enumeration of the agent types.

Attributes: Manager: marks the agent as a Managing agent. Regular: marks the agent as a regular agent. A2A: marks the agent as an external agent used via A2A protocol. Curl: marks the agent as an external agent used via a CURL. Orchestration: marks the agent as an Orchestration object.

Available options:
manager,
regular,
a2a,
curl,
orchestration
​
using_nemo
boolean | null
default:false
​
deletable
boolean | null
default:true
​
model_provider
enum<string> | null
default:anthropic
Available options:
openai,
nim,
amazon_bedrock,
azure_ai_foundary,
huggingFace,
friendlyAI,
anthropic,
gemini,
fireworks,
google_ai_studio,
helicone,
bytedance,
tzafon_lightcone,
open_router,
nebius,
cloudflare_ai_gw
​
model_name
string | null
default:claude-sonnet-4-6
​
llm_reasoning_effort
enum<string> | null
default:medium
Available options:
low,
medium,
high,
xhigh
​
llm_api_base
string | null
​
output_format
enum<string> | null
default:markdown
Available options:
text,
markdown,
json,
voice
​
voice_id
string | null
​
output_schema
Output Schema · object
​
llm_credentials_key
string | null
​
llm_credentials_key_type
enum<string> | null
default:xpander
Available options:
xpander,
custom
​
llm_credentials
LLMCredentials · object
​
llm_extra_headers
Llm Extra Headers · object
​
expected_output
string | null
default:""
​
agno_settings
AgnoSettings · object
​
on_prem_event_streaming
boolean | null
default:true
​
is_supervised
boolean | null
default:false
​
orchestration_nodes
OrchestrationNode · object[] | null
​
notification_settings
NotificationSettings · object

Configuration for event-based notifications.

Attributes: on_success: Notifications to send when an operation succeeds. Maps notification types to a list of notification configurations. on_error: Notifications to send when an operation fails. Maps notification types to a list of notification configurations.

​
task_level_strategies
TaskLevelStrategies · object

Configuration object for task-level execution strategies.

This model groups optional strategy configurations that control how a task is executed and managed over time, including retries, iterative execution, stopping conditions, and daily run limits.

Attributes: retry_strategy: Optional retry policy configuration that defines how the task should behave when execution fails (e.g., max attempts, backoff rules).

iterative_strategy:
    Optional iterative execution configuration for tasks that may run in
    repeated cycles/steps until completion or a stop condition is met.

stop_strategy:
    Optional stopping policy configuration that defines when the task
    should stop running (e.g., timeout, max iterations, success criteria).

max_runs_per_day:
    Optional limit on how many times the task is allowed to run within a
    24-hour period. If not set, no explicit daily limit is enforced.

agentic_context_enabled:
    if agentic memory is enabled and accesible to the executor.
​
use_oidc_pre_auth
boolean | null
default:false
​
pre_auth_audiences
string[] | null
​
use_oidc_pre_auth_token_for_llm
boolean | null
default:false
​
oidc_pre_auth_token_llm_audience
string | null
​
oidc_pre_auth_token_mcp_audience
string | null