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

# Update workflow

> Updates an existing workflow. The workflow must already exist and belong to the workspace associated with your API key.

This endpoint updates the workflow metadata and creates a **new version** with the provided nodes, edges, and configuration. If the workflow ID does not match an existing workflow in your workspace, the request will return a 404 error.

**Versioning**: Every call to this endpoint creates a new workflow version. Versions are immutable and auto-increment. Use `GET /workflows/{workflow_id}/versions` to list version history, and `GET /workflows/{workflow_id}/versions/{version_number}` to fetch the full JSON of any prior version (e.g., to inspect, diff, or roll back by re-submitting it via this endpoint).

**Typical usage**:
1. `GET /workflows/{workflow_id}` to fetch the current workflow definition
2. Modify the `nodes`, `edges`, or other fields as needed
3. `PUT /workflows/{workflow_id}` with the full updated payload to save a new version

**Important**: This endpoint requires the full workflow definition. Partial updates are not supported — you must include all required fields (nodes, edges, schemas) even if they haven't changed.



## OpenAPI

````yaml workflow-api/workflow-api.yaml put /workflows/{workflow_id}
openapi: 3.0.0
info:
  title: Workflow API
  version: 1.0.0
  description: API for managing workflows and their metadata
servers:
  - url: https://api.cloudcruise.com
    description: CloudCruise Platform Production API Server
security:
  - AuthScheme: []
paths:
  /workflows/{workflow_id}:
    put:
      summary: Update workflow
      description: >-
        Updates an existing workflow. The workflow must already exist and belong
        to the workspace associated with your API key.


        This endpoint updates the workflow metadata and creates a **new
        version** with the provided nodes, edges, and configuration. If the
        workflow ID does not match an existing workflow in your workspace, the
        request will return a 404 error.


        **Versioning**: Every call to this endpoint creates a new workflow
        version. Versions are immutable and auto-increment. Use `GET
        /workflows/{workflow_id}/versions` to list version history, and `GET
        /workflows/{workflow_id}/versions/{version_number}` to fetch the full
        JSON of any prior version (e.g., to inspect, diff, or roll back by
        re-submitting it via this endpoint).


        **Typical usage**:

        1. `GET /workflows/{workflow_id}` to fetch the current workflow
        definition

        2. Modify the `nodes`, `edges`, or other fields as needed

        3. `PUT /workflows/{workflow_id}` with the full updated payload to save
        a new version


        **Important**: This endpoint requires the full workflow definition.
        Partial updates are not supported — you must include all required fields
        (nodes, edges, schemas) even if they haven't changed.
      operationId: updateWorkflow
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The ID of the workflow to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowUpdatePayload'
      responses:
        '200':
          description: >-
            Workflow updated successfully. Returns the full workflow with the
            new version number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowFull'
        '400':
          description: Bad request - Missing required fields or invalid payload
        '401':
          description: Unauthorized - Invalid or missing authentication
        '404':
          description: Workflow not found in workspace
        '500':
          description: Internal server error
components:
  schemas:
    WorkflowUpdatePayload:
      type: object
      description: >-
        Payload for updating an existing workflow via PUT. The workflow ID is
        provided in the URL path.

        The recommended approach is to first fetch the current workflow via `GET
        /workflows/{workflow_id}`,

        modify the desired fields, and then submit the full payload here.
      properties:
        name:
          type: string
          description: Display name of the workflow
        description:
          type: string
          nullable: true
          description: Optional description of the workflow
        nodes:
          type: array
          description: >-
            Array of workflow step nodes. Each node represents an action in the
            workflow (e.g., click,

            type text, navigate, extract data). Pass an empty array `[]` to
            clear all nodes.
          items:
            $ref: '#/components/schemas/Node'
        edges:
          type: object
          description: >-
            Map of edges connecting workflow nodes. Keys are source node IDs,
            values define the outgoing

            connections. Pass an empty object `{}` to clear all edges.
          additionalProperties:
            $ref: '#/components/schemas/Edge'
        input_schema:
          type: object
          description: JSON Schema defining the workflow's input variables
          example:
            type: object
            properties:
              SEARCH_TERM:
                type:
                  - string
                  - 'null'
            required:
              - SEARCH_TERM
        output_schema:
          type: object
          description: JSON Schema defining the workflow's output variables
          example:
            type: object
            properties: {}
        max_retries:
          type: integer
          description: Maximum number of retry attempts for failed workflow steps
          example: 0
        version_note:
          type: string
          description: Optional note describing what changed in this version
          example: Updated login selectors
        use_native_actions:
          type: boolean
          nullable: true
          description: Whether to use native browser actions instead of simulated events
        video_record_session:
          type: boolean
          nullable: true
          description: Whether to record a video of the workflow execution
        extract_network_urls:
          type: array
          nullable: true
          items:
            type: string
          description: URL patterns to extract from network traffic during execution
        encrypted_keys:
          type: array
          nullable: true
          items:
            type: string
          description: References to encrypted vault keys used by this workflow
        popup_xpaths:
          type: array
          nullable: true
          items:
            type: string
          description: XPath selectors for popups that should be automatically dismissed
        vault_schema:
          type: object
          nullable: true
          description: Schema defining vault credentials required by this workflow
          additionalProperties:
            type: object
            properties:
              type:
                type: string
                enum:
                  - credential
              domain:
                type: string
                description: Domain associated with the credential
              example:
                type: string
                description: Example permissioned_user_id for this credential
          example:
            USER:
              type: credential
              domain: https://example.com
              example: 11223344-5566-7788-9900-112233445566
        proxy_setting:
          type: string
          nullable: true
          description: Proxy configuration setting
        proxy_value:
          type: string
          nullable: true
          description: Proxy value (e.g., proxy URL or region)
        enable_popup_handling:
          type: boolean
          description: Whether popup handling is enabled
        enable_action_timing_recovery:
          type: boolean
          description: Whether action timing recovery is enabled
        enable_xpath_recovery:
          type: boolean
          description: Whether XPath recovery is enabled
        enable_node_description_enrichment:
          type: boolean
          description: >-
            Whether node descriptions are auto-enriched for reliability
            improvements
        enable_error_code_generation:
          type: boolean
          description: Whether error code generation is enabled
        enable_service_unavailable_recovery:
          type: boolean
          description: Whether service unavailable recovery is enabled
        enable_incorrect_form_input_recovery:
          type: boolean
          description: Whether incorrect form input recovery is enabled
        enable_password_update_recovery:
          type: boolean
          description: >-
            Whether password update recovery is enabled. When a site forces a
            password change, the Maintenance Agent classifies the error and
            sends a notification.
        enable_tfa_setup_recovery:
          type: boolean
          description: >-
            Whether automatic TFA setup recovery is enabled. When a site
            requires two-factor authentication setup during login, the
            Maintenance Agent can autonomously complete the enrollment and
            update the vault credential.
        enable_network_listener:
          type: boolean
          description: Whether the network listener is enabled
        skip_udp_proxying:
          type: boolean
          description: Whether UDP proxying is skipped during workflow execution
        origin_catalog_workflow_version_id:
          type: string
          format: uuid
          nullable: true
          description: Specific origin catalog workflow version ID used as the base
        origin_base_version_number:
          type: integer
          nullable: true
          description: Base version number used when deriving from a catalog workflow
      required:
        - name
        - nodes
        - edges
        - input_schema
        - output_schema
        - max_retries
    WorkflowFull:
      type: object
      description: Full workflow definition including nodes and edges
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the workflow
        name:
          type: string
          description: Name of the workflow
        description:
          type: string
          nullable: true
          description: Description of the workflow
        created_at:
          type: string
          format: date-time
          description: Timestamp when the workflow was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the workflow was last updated
        workspace_id:
          type: string
          format: uuid
          description: ID of the workspace this workflow belongs to
        created_by:
          type: string
          format: uuid
          description: ID of the user who created the workflow
        version_number:
          type: integer
          description: Current version number of the workflow
        version_id:
          type: string
          format: uuid
          description: ID of the current workflow version
        nodes:
          type: array
          description: Array of workflow step nodes
          items:
            type: object
        edges:
          type: object
          description: Map of edges connecting workflow nodes
          additionalProperties:
            type: object
        input_schema:
          type: object
          nullable: true
          description: JSON schema defining the workflow's input variables
        vault_schema:
          type: object
          nullable: true
          description: Schema defining vault credentials and their configuration
        enable_popup_handling:
          type: boolean
          description: Whether popup handling is enabled for this workflow
        enable_xpath_recovery:
          type: boolean
          description: Whether XPath recovery is enabled for this workflow
        enable_node_description_enrichment:
          type: boolean
          description: >-
            Whether node descriptions are auto-enriched for reliability
            improvements
        enable_error_code_generation:
          type: boolean
          description: Whether error code generation is enabled for this workflow
        enable_service_unavailable_recovery:
          type: boolean
          description: Whether service unavailable recovery is enabled for this workflow
        enable_incorrect_form_input_recovery:
          type: boolean
          description: Whether incorrect form input recovery is enabled
        enable_password_update_recovery:
          type: boolean
          description: >-
            Whether password update recovery is enabled. When a site forces a
            password change, the Maintenance Agent classifies the error and
            sends a notification.
        enable_tfa_setup_recovery:
          type: boolean
          description: >-
            Whether automatic TFA setup recovery is enabled. When a site
            requires two-factor authentication setup during login, the
            Maintenance Agent can autonomously complete the enrollment and
            update the vault credential.
        enable_action_timing_recovery:
          type: boolean
          description: Whether action timing recovery is enabled
        origin_catalog_workflow_id:
          type: string
          format: uuid
          nullable: true
          description: ID of the catalog workflow this was forked from (if applicable)
        origin_catalog_version_number:
          type: integer
          nullable: true
          description: Version number of the catalog workflow this was forked from
        origin_catalog_workflow_version_id:
          type: string
          format: uuid
          nullable: true
          description: Specific origin catalog workflow version ID used as the base
        origin_base_version_number:
          type: integer
          nullable: true
          description: Base version number used when deriving from a catalog workflow
        track_updates_from_catalog:
          type: boolean
          description: Whether to track updates from the origin catalog workflow
        enable_network_listener:
          type: boolean
          description: >-
            Whether network listener capture is enabled for this workflow
            version
        skip_udp_proxying:
          type: boolean
          description: Whether UDP proxying is skipped for this workflow version
      required:
        - id
        - name
        - created_at
        - updated_at
        - workspace_id
        - created_by
        - nodes
        - edges
    Node:
      type: object
      description: >-
        A workflow step node. Each node has an `action` type and `parameters`
        specific to that action.

        Common action types include: START, END, CLICK, INPUT_TEXT,
        INPUT_SELECT, NAVIGATE,

        EXTRACT_DATAMODEL, BOOL_CONDITION, LOOP, DELAY, SCREENSHOT, SCROLL,
        TAB_MANAGEMENT,

        FILE_DOWNLOAD, FILE_UPLOAD, TFA, USER_INTERACTION, APP_ACTION,
        EXTRACT_NETWORK,

        TRANSFORM.
      properties:
        id:
          type: string
          description: Unique identifier for the node within the workflow
        name:
          type: string
          description: Display name of the node
        action:
          type: string
          description: The action type this node performs
          enum:
            - START
            - END
            - CLICK
            - INPUT_TEXT
            - INPUT_SELECT
            - NAVIGATE
            - EXTRACT_DATAMODEL
            - BOOL_CONDITION
            - LOOP
            - DELAY
            - SCREENSHOT
            - SCROLL
            - TAB_MANAGEMENT
            - FILE_DOWNLOAD
            - FILE_UPLOAD
            - TFA
            - USER_INTERACTION
            - APP_ACTION
            - EXTRACT_NETWORK
            - TRANSFORM
        parameters:
          type: object
          description: >-
            Action-specific parameters. The shape of this object depends on the
            `action` type.

            Refer to the workflow builder or an existing workflow's GET response
            for the parameter

            structure of each action type.
        description:
          type: string
          description: Optional description of what this node does
      required:
        - id
        - name
        - action
        - parameters
    Edge:
      type: object
      description: >-
        Defines outgoing connections from a node. The type of edge depends on
        the source node's action:

        - Most nodes use `to` for a single next node

        - BOOL_CONDITION nodes use `true` and `false` for branching

        - LOOP nodes use `loop_done` and `loop_not_done` for iteration control
      properties:
        to:
          type: string
          nullable: true
          description: ID of the next node (for non-branching nodes)
        'true':
          type: string
          nullable: true
          description: >-
            ID of the node to execute when condition is true (BOOL_CONDITION
            nodes)
        'false':
          type: string
          nullable: true
          description: >-
            ID of the node to execute when condition is false (BOOL_CONDITION
            nodes)
        loop_done:
          type: string
          nullable: true
          description: ID of the node to execute when loop completes (LOOP nodes)
        loop_not_done:
          type: string
          nullable: true
          description: ID of the node to execute for the next loop iteration (LOOP nodes)
  securitySchemes:
    AuthScheme:
      type: apiKey
      name: cc-key
      in: header
      description: >-
        API key-based authentication. Provide your CloudCruise API key in the
        cc-key header.

````