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

# Update a Workflow

> Replace a workflow's definition and mint a new version

Replace the workflow with the definition in the body and mint a new version.

Requires the **Workflow: Full** permission on the workflow.

<Warning>
  **This is a replace, not a merge.** Nodes and edges absent from the body are removed from the new version — so send the whole workflow, not just the parts you changed.

  Fetch the current definition with [Get Workflow Details](/api-reference/v1-workflow-generation/get-workflow-details) first, modify it, then send it back in full.
</Warning>

The change is recorded as a single API-update entry in the workflow's version history. Earlier versions are untouched and stay retrievable by version number or ID.

## Path Parameters

<ParamField path="workflowId" type="string" required>
  The ID of the workflow to update
</ParamField>

## Headers

<ParamField header="x-service-key" type="string" required>
  Your API authentication key
</ParamField>

## Body Parameters

<ParamField body="name" type="string" required>
  Workflow name
</ParamField>

<ParamField body="description" type="string">
  Workflow description
</ParamField>

<ParamField body="nodes" type="object">
  Workflow nodes keyed by node ID, in the same shape as [Create a Workflow](/api-reference/v1-workflow-generation/create-workflow#body-parameters). Each map key must equal the `id` of the node it holds.

  Replaces the existing set — a node absent from this map is removed from the new version.

  A node's `handler_class` determines the shape of its `process` — see [Node Process Types](/api-reference/v1-workflow-generation/node-process-types). For `input_schema` and `output_schema`, see [Variable Schemas](/api-reference/v1-workflow-generation/variable-schemas).
</ParamField>

<ParamField body="edges" type="object">
  Workflow edges keyed by edge ID, in the same shape as [Create a Workflow](/api-reference/v1-workflow-generation/create-workflow#body-parameters). Each map key must equal the `id` of the edge it holds, and `from_node_id` and `to_node_id` must name nodes present in `nodes`.

  Replaces the existing set — an edge absent from this map is removed from the new version.
</ParamField>

<ParamField body="activeStatus" type="string">
  Workflow active status. One of `active` or `inactive`.
</ParamField>

<ParamField body="validityStatus" type="string">
  Workflow validity status. One of `valid` or `invalid`.
</ParamField>

## Response

<ResponseField name="workflowVersionId" type="string" required>
  The ID of the version this update created
</ResponseField>

<ResponseField name="workflowVersionNumber" type="number" required>
  The version number this update created
</ResponseField>

<ResponseField name="majorVersion" type="number">
  Major component of the new version. `null` if the workflow is not semantically versioned.
</ResponseField>

<ResponseField name="minorVersion" type="number">
  Minor component of the new version. `null` if the workflow is not semantically versioned.
</ResponseField>

<ResponseField name="versionLabel" type="string">
  How the version was classified. One of `major` or `minor`.

  An API update always classifies as `major`, because a single call can rewrite the whole workflow.
</ResponseField>

## Errors

<ResponseField name="400" type="Bad Request">
  The workflow definition is malformed.
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Missing, invalid, or expired API key.
</ResponseField>

<ResponseField name="403" type="Forbidden">
  No access to this workflow.
</ResponseField>

<ResponseField name="404" type="Not Found">
  The workflow does not exist.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request PUT \
    --url https://operator.opus.com/api/v1/workflow/{YOUR_WORKFLOW_ID} \
    --header 'x-service-key: {YOUR_SERVICE_KEY}' \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "Quarterly Report Processor",
      "description": "Summarizes quarterly financial reports",
      "activeStatus": "active",
      "nodes": { "...": "the complete node map" },
      "edges": { "...": "the complete edge map" }
    }'
  ```

  ```python Python theme={null}
  import requests

  BASE = "https://operator.opus.com/api/v1/workflow/{YOUR_WORKFLOW_ID}"
  headers = {"x-service-key": "{YOUR_SERVICE_KEY}"}

  # Read the current definition, change one thing, send the whole thing back.
  current = requests.get(BASE, headers=headers).json()

  response = requests.put(
      BASE,
      headers=headers,
      json={
          "name": "Quarterly Report Processor (v2)",
          "description": current["description"],
          "nodes": current["nodes"],
          "edges": current["edges"],
          "activeStatus": "active",
      },
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const base = "https://operator.opus.com/api/v1/workflow/{YOUR_WORKFLOW_ID}";
  const headers = { "x-service-key": "{YOUR_SERVICE_KEY}" };

  // Read the current definition, change one thing, send the whole thing back.
  const current = await (await fetch(base, { headers })).json();

  const response = await fetch(base, {
    method: "PUT",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Quarterly Report Processor (v2)",
      description: current.description,
      nodes: current.nodes,
      edges: current.edges,
      activeStatus: "active",
    }),
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "workflowVersionId": "{WORKFLOW_VERSION_ID}",
    "workflowVersionNumber": 4,
    "majorVersion": 2,
    "minorVersion": 0,
    "versionLabel": "major"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.