Sign in

v3

OpenAPI 3.1.02026-07-31350397683.8 KB
Scenario Builder

Create Workflow V2

Create a workflows_v2 row with a React Flow graph definition.

post/v1/scenario

Headers

X-API-Keystring required

API key required to authenticate requests.

Request body

namestring required

Name of the workflow

agent_idsinteger[] nullable

Owning agents (must belong to your organization). Omit or null for org-only workflow.

descriptionstring nullable

Human-readable description of the workflow

definitionobject required

React Flow graph. Omitted nodes / edges default to []. Each node must have a non-empty string id on the node object (not only inside data). Each edge must have a non-empty string id, unique across all edges. With no single or options nodes, the graph is stored as a draft (only multiple-start is rejected). Once there is content, export rules apply (paths, branch_options, etc.).

Example request

{
  "agent_ids": [],
  "definition": {
    "edges": [
      {
        "id": "e-wf-start-n-greet",
        "source": "wf-start",
        "target": "n-greet"
      }
    ],
    "nodes": [
      {
        "data": {
          "id": "wf-start"
        },
        "deletable": false,
        "draggable": true,
        "id": "wf-start",
        "position": {
          "x": 100,
          "y": 50
        },
        "type": "start"
      },
      {
        "data": {
          "criteria": "Greet the caller and offer help",
          "id": "n-greet",
          "speaker": "agent",
          "turn": 0,
          "type": "message"
        },
        "id": "n-greet",
        "position": {
          "x": 200,
          "y": 180
        },
        "type": "single"
      }
    ]
  },
  "description": "Password reset IVR",
  "name": "Support reset flow"
}

Response

Successful Response

idstring required

Workflow ID

organization_idstring nullable

Owning organization ID (set by middleware on create)

agent_idsinteger[]

Linked agent ids when the workflow is agent-scoped

namestring required

Name of the workflow

descriptionstring nullable

Description

definitionobject required

Stored React Flow graph (start / single / options nodes). Nodes and edges use top-level string id fields; edge id values are unique within the graph.

created_atstring date-time required

Creation timestamp

dh_sync_summaryobject nullable

Present on PUT responses when the definition was updated. Keys: updated, created, marked_stale, skipped, errors.

warningsstring[]

Non-blocking lint warnings emitted at save time (e.g. node text referencing an unknown {{trait_name}}). Empty when the definition is clean or no agents are linked.