---
title: "Create Workflow"
method: POST
path: "/v3/workflows"
tags: ["Durable Workflows"]
---

# Create Workflow

`POST /v3/workflows`

## Request

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

Creates a workflow and publishes its graph as version 1 in one step, ready to run. An invalid graph returns 422 `graph_invalid` and a duplicate name returns 409 `conflict`; neither creates anything. With an Idempotency-Key, a retry of the same request within 24 hours replays a snapshot of the original body with HTTP 200. Unlike run creation, this is not durable.

## Headers

- `Idempotency-Key` string

## Request body

- CreateWorkflowRequest: Request body for POST /v3/workflows.
  - `name` string, required: Human-readable workflow name (unique per space). Creating a workflow with a name that already exists in this space fails with 409 conflict.
  - `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.
  - `meta` object, nullable: Optional caller-supplied metadata stored with the workflow.

## Response `200`

Idempotency-key replay of a previously created workflow.

- 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

- `201`: Created.
- `400`: Invalid request parameters
- `401`: Authentication failed
- `409`: Conflict — `error.code` is one of: `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

## Changes

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

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