---
title: "Update Workflow"
method: PATCH
path: "/v1/workflows/{workflow_id}"
tags: ["workflows"]
---

# Update Workflow

`PATCH /v1/workflows/{workflow_id}`

Update a workflow's prompts.

The current version will be saved to the version history.
Only the fields provided in the request body will be updated.
The workflow must belong to the authenticated organization.

## Path parameters

- `workflow_id` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- WorkflowUpdate — Schema for updating a workflow
  - `name` string, nullable
  - `main_prompt` string, nullable
  - `input_schema` string, nullable — JSON schema for validating merged run inputs. Sensitive root keys are exposed with a '$' prefix in schema validation (for example sensitive_input_values.api_key -> '$api_key').
  - `output_schema` string, nullable — JSON schema for output data transformation
  - `includes_file_exports` boolean, nullable — Enable AI-based file export detection
  - `is_webhooks_enabled` boolean, nullable — Send webhook on run completion
  - `terminal_command_allowlist` string[], nullable — Optional workflow-level allowlist for execute_terminal_command. Set to an empty list or null to clear the allowlist.
  - `model_metadata` WorkflowModelMetadata — JSONB-backed workflow model configuration metadata. Stored on the Workflow row as `model_metadata` to avoid adding many FK columns. All fields are optional; when missing/null, the system falls back to Cyberdesk defaults.
    - `main_agent_model_id` string, uuid, nullable — ModelConfiguration.id used for the main agent. Null → Cyberdesk default.
    - `cache_detection_model_id` string, uuid, nullable — ModelConfiguration.id used for cache detection. Null → Cyberdesk default.
    - `fallback_model_1_id` string, uuid, nullable — ModelConfiguration.id used as fallback 1 (global across agents).
    - `fallback_model_2_id` string, uuid, nullable — ModelConfiguration.id used as fallback 2 (global across agents).
  - `post_run_check_failure_cleanup_prompt` string, nullable — Optional workflow-level cleanup prompt that runs when any post-run check fails during a session or chain. Set null to clear it.
  - `workflow_metadata` WorkflowInternalMetadataUpdate — Patchable workflow metadata fields for internal workflow maintenance.
    - `has_unaddressed_error` boolean, nullable — Set to false when workflow errors have been addressed.
    - `last_errored_run_start` string, date-time, nullable — Start timestamp of the most recent errored/task_failed run.
    - `last_errored_run_uuid` string, uuid, nullable — Run UUID of the most recent errored/task_failed run.
  - `post_run_checks` WorkflowPostRunCheckUpsert[], nullable — Workflow-managed post-run checks, reconciled on save when present.
    - `name` string, required
    - `description` string, nullable
    - `type` 'run_attachment_exists' | 'run_attachment_image_check' | 'output_data_passes_schema_validation' | 'output_data_agentic_check', required
    - `file_target_mode` 'exact' | 'regex' | 'loop_items'
    - `file_names` string[], nullable
    - `file_name_regex` string, nullable
    - `expected_match_count` integer, nullable
    - `expected_match_count_ref` string, nullable
    - `loop_input` string, nullable
    - `loop_item_filename_template` string, nullable
    - `allow_missing_attachments` boolean
    - `check_prompt` string, nullable
    - `model` string, uuid, nullable — Optional ModelConfiguration id override for agentic post-run checks.
    - `id` string, uuid, nullable

## Response `200`

Successful Response

- WorkflowResponse — Workflow response schema
  - `name` string, nullable
  - `main_prompt` string, required
  - `input_schema` string, nullable — JSON schema for validating merged run inputs. Sensitive root keys are exposed with a '$' prefix in schema validation (for example sensitive_input_values.api_key -> '$api_key').
  - `output_schema` string, nullable — JSON schema for output data transformation
  - `includes_file_exports` boolean — Enable AI-based file export detection
  - `is_webhooks_enabled` boolean — Send webhook on run completion
  - `terminal_command_allowlist` string[], nullable — Optional workflow-level allowlist for execute_terminal_command. When set, the agent may only run commands that exactly match one of the approved command templates.
  - `model_metadata` WorkflowModelMetadata — JSONB-backed workflow model configuration metadata. Stored on the Workflow row as `model_metadata` to avoid adding many FK columns. All fields are optional; when missing/null, the system falls back to Cyberdesk defaults.
    - `main_agent_model_id` string, uuid, nullable — ModelConfiguration.id used for the main agent. Null → Cyberdesk default.
    - `cache_detection_model_id` string, uuid, nullable — ModelConfiguration.id used for cache detection. Null → Cyberdesk default.
    - `fallback_model_1_id` string, uuid, nullable — ModelConfiguration.id used as fallback 1 (global across agents).
    - `fallback_model_2_id` string, uuid, nullable — ModelConfiguration.id used as fallback 2 (global across agents).
  - `post_run_check_failure_cleanup_prompt` string, nullable — Optional workflow-level cleanup prompt that runs when any post-run check fails during a session or chain.
  - `id` string, uuid, required
  - `user_id` string, uuid, nullable
  - `organization_id` string, nullable
  - `includes_input_variables` boolean
  - `workflow_metadata` WorkflowInternalMetadata — Backend workflow metadata exposed read-only for internal observability.
    - `has_unaddressed_error` boolean, nullable — True when at least one run has failed and remains unaddressed.
    - `last_errored_run_start` string, date-time, nullable — Start timestamp of the most recent errored/task_failed run.
    - `last_errored_run_uuid` string, uuid, nullable — Run UUID of the most recent errored/task_failed run.
  - `old_versions` object[], nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `tags` WorkflowTagResponse[], nullable — Tags assigned to this workflow
    - `name` string, required
    - `description` string, nullable
    - `emoji` string, nullable
    - `color` string, nullable
    - `group_id` string, uuid, nullable — Optional group for mutual exclusivity
    - `id` string, uuid, required
    - `organization_id` string, required
    - `order` integer, required
    - `is_archived` boolean
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `workflow_count` integer, nullable — Number of workflows with this tag (returned in list endpoint)
    - `group` WorkflowTagGroupResponse — Workflow tag group response schema
      - `name` string, required
      - `description` string, nullable
      - `emoji` string, nullable
      - `color` string, nullable
      - `id` string, uuid, required
      - `organization_id` string, required
      - `order` integer, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
  - `post_run_checks` WorkflowPostRunCheckResponse[], nullable — Post-run checks assigned to this workflow.
    - `name` string, required
    - `description` string, nullable
    - `type` 'run_attachment_exists' | 'run_attachment_image_check' | 'output_data_passes_schema_validation' | 'output_data_agentic_check', required
    - `file_target_mode` 'exact' | 'regex' | 'loop_items'
    - `file_names` string[], nullable
    - `file_name_regex` string, nullable
    - `expected_match_count` integer, nullable
    - `expected_match_count_ref` string, nullable
    - `loop_input` string, nullable
    - `loop_item_filename_template` string, nullable
    - `allow_missing_attachments` boolean
    - `check_prompt` string, nullable
    - `model` string, uuid, nullable — Optional ModelConfiguration id override for agentic post-run checks.
    - `id` string, uuid, required
    - `organization_id` string, required
    - `user_id` string, uuid, nullable
    - `order` integer, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/cyberdesk-hq/apis/cyberdesk-cloud.md) · [All operations](https://skmtc.net/cyberdesk-hq/apis/cyberdesk-cloud/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cyberdesk-hq/cyberdesk-cloud/versions/830d2f48963d/schema)