---
title: "Update Workflow Draft"
method: PATCH
path: "/v3/workflows/{workflow_id}"
tags: ["Durable Workflows"]
---

# Update Workflow Draft

`PATCH /v3/workflows/{workflow_id}`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v3/workflows/{workflow_id}`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Replaces the mutable draft product graph. Rejected (409) if `expected_revision` is stale, and 422 `graph_invalid` if the graph uses node types not available for authoring — the draft is left unchanged in both cases.

## Path parameters

- `workflow_id` string, required

## Request body

- UpdateWorkflowDraftRequest: Request body for PATCH /v3/workflows/{workflow_id}.
  - `product_graph` WorkflowProductGraph, required: An authored workflow product graph: nodes, their bindings, and the run-level inputs/outputs.
    - `schema_version` string, required: Graph schema version; currently "1.0.0".
    - `inputs` object: Workflow inputs supplied at run start, keyed by input name.
    - `nodes` WorkflowGraphNode[]: Nodes in the graph.
      - `id` string, required: Node id, unique within the graph.
      - `type` string, required: Node family, as listed by the node-type catalog.
      - `variant` string, nullable: Variant within the family; omit for a single-variant family.
      - `config` object: Authored configuration, validated against the node type's config schema.
      - `depends_on` string[]: Ids of nodes that must complete before this one, beyond binding-implied edges.
      - `bindings` object: Where each input port's value comes from, keyed by port name.
    - `outputs` object: Node outputs surfaced as run results, keyed by output name.
  - `expected_revision` integer, required: draft_revision the client last read; the update is rejected (409) if stale.

## Response `200`

Successful response

- object
  - `data` WorkflowDefinitionResponse: Response body for a single workflow definition (mutable draft).
    - `id` string, required: Workflow definition id (def_…).
    - `name` string, required: Workflow name.
    - `status` 'draft' | 'active' | 'archived', required
    - `draft_revision` integer, required: Monotonic draft revision; supply as expected_revision when updating the draft.
    - `draft_product_graph` WorkflowProductGraphView: The same graph shape as stored and returned on read surfaces. A separate schema from the request-side graph so the published contract can describe what a stored graph may contain (including node types that are no longer available for new authoring) independently of what a new request may submit.
      - `schema_version` string, required: Graph schema version; currently "1.0.0".
      - `inputs` object: Workflow inputs supplied at run start, keyed by input name.
      - `nodes` WorkflowGraphNode[]: Nodes in the graph.
        - `id` string, required: Node id, unique within the graph.
        - `type` string, required: Node family, as listed by the node-type catalog.
        - `variant` string, nullable: Variant within the family; omit for a single-variant family.
        - `config` object: Authored configuration, validated against the node type's config schema.
        - `depends_on` string[]: Ids of nodes that must complete before this one, beyond binding-implied edges.
        - `bindings` object: Where each input port's value comes from, keyed by port name.
      - `outputs` object: Node outputs surfaced as run results, keyed by output name.
    - `meta` object, nullable: Caller-supplied metadata stored with the workflow, if any.
    - `latest_version` WorkflowVersionRef: Compact reference to a published workflow version.
      - `id` string, required: Version id (dwv_…).
      - `version_number` integer, required: Monotonic version number within the workflow.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `404`: Resource not found
- `409`: Conflict — `error.code` is one of: `stale_workflow_draft`, `workflow_archived`.
- `422`: Graph invalid — the request parsed but the workflow graph is semantically invalid; `error.errors[]` lists every issue found.
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/workflows/:workflow_id/patch.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)