---
title: "Publish Workflow Version"
method: POST
path: "/v3/workflows/{workflow_id}/versions"
tags: ["Durable Workflows"]
---

# Publish Workflow Version

`POST /v3/workflows/{workflow_id}/versions`

## Request

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

Publishes the graph in the body as the workflow's next immutable version: 201 when new, 200 when it matches the latest. Roll back by republishing an earlier graph. An invalid graph returns 422 `graph_invalid`. With an Idempotency-Key, a retry within 24 hours replays a snapshot of the original body with HTTP 200, and reuse with a different graph returns 409 `conflict`. Unlike run creation, this is not durable.

## Path parameters

- `workflow_id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- PublishVersionRequest: Request body for POST /v3/workflows/{workflow_id}/versions.
  - `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.

## Response `200`

Existing identical version returned, or an idempotency-key replay.

- object
  - `data` WorkflowVersionResponse: Response body for a single immutable, compiled workflow version.
    - `id` string, required: Version id (dwv_…).
    - `definition_id` string, required: Parent workflow definition id.
    - `version_number` integer, required: Monotonic version number within the definition.
    - `checksum` string, required: Deterministic checksum of the frozen graph + plan.
    - `compiler_version` string, required: Compiler version that produced the plan.
    - `adapter_manifest_digest` string, required: Digest of the per-node adapter-version manifest.
    - `product_graph` WorkflowProductGraphView, required: 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.
    - `plan_summary` CompiledNodeSummary[], required: Compact per-node summary of the compiled plan (no internal node dumps).
      - `node_id` string, required: Node id within the graph.
      - `family` string, required: Node family, as authored in the product graph.
      - `variant` string, nullable: Variant within the family; null for a single-variant family.
      - `contract_version` string, required: NodeType contract version pinned in the plan.
      - `adapter_version` string, required: Adapter version pinned for this node.
      - `parents` string[]: Upstream node ids this node depends on.

## Other responses

- `201`: Created.
- `400`: Invalid request parameters
- `401`: Authentication failed
- `404`: Resource not found
- `409`: Conflict — `error.code` is one of: `workflow_archived`, `conflict`, `request_in_progress`.
- `422`: Graph invalid — the request parsed but the workflow graph is semantically invalid; `error.errors[]` lists every issue found.
- `429`: Rate limit exceeded
- `503`: Temporarily unavailable — the request did not complete and is safe to retry.

## Changes

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

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/workflows/:workflow_id/versions/post.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)