Create Workflow

POST /v1/workflows

Creates an organization-scoped workflow draft. Send the complete graph using nodes, edges, and optional global_edges.

name

string

required

Workflow name (max 255 characters).

description

string

Optional workflow description.

nodes

array

required

Graph nodes, each with id, type, and data.

edges

array

required

Local graph edges.

global_edges

array

Conditional transitions considered before local edges.

variables_schema

object

Declared workflow variables.

ui_state

object

Canvas nodes, edges, and viewport for the dashboard.

compliance_plan

object

Workflow recording, consent, and retention configuration.

analysis_enabled

boolean

Enable post-call analysis.

analysis_profile_id

integer

Organization analysis profile ID.

Graph Reference

Nodes

Each node is { "id": string, "type": string, "data": object }. Node types

Type	Purpose
`start`	Entry point of the graph. `data` may set `first_message_mode` and `start_speaking_plan`
`say`	Plays fixed text to the caller
`conversation`	Free-form conversation turn
`agent`	Runs an agent with prompt, model, voice, and transcriber
`subagent`	Loads an existing assistant (by `assistant_id`) with optional per-node overrides
`task` / `data`	Typed data collection task (`data` is a compatibility alias)
`function`	HTTP API request node
`logic`	Conditional routing with named branches
`end` / `endCall`	Terminates the call (`endCall` is a compatibility alias)
`transferCall`	Warm or cold transfer to a human agent
`googleSheets`, `googleCalendar`, `googleGmailSend`	Google workspace integrations
`apiRequest`	Frontend editor alias for the function node
`global`	Global transition node

endCall and data are accepted compatibility aliases; new API payloads should use end and task. Node data fields

Field	Type	Applies to	Description
`label`	string	all	Editor label
`first_message_mode`	string	start	`assistant-speaks-first` or `user-speaks-first`
`start_speaking_plan`	object	start	Session override for inherited assistant endpointing: `wait_seconds`, `smart_endpointing_mode` (`off`/`livekit`), and turn-detection fields
`prompt`	string	agent, conversation	System prompt / instructions
`firstMessage`	string	agent, conversation	First message of the turn
`generate_from_model`	boolean	say	Generate text from the model instead of fixed text
`text`	string	say	Fixed text to speak
`end_call_message`	string	say, end	Message spoken before the call ends
`allowInterruptions`	boolean	say	Whether the caller may interrupt playback
`addToChatCtx`	boolean	say	Append the message to the chat context
`max_retries`	integer	agent, function	Retry count on failure
`loop_fallback_node`	string	agent, conversation	Node id to route to on repeated failure
`file_ids`	array	agent, subagent, knowledge	Knowledge-base file UUIDs
`tool_ids`	array	agent, subagent	Tool IDs
`query`	string	knowledge	Search query; supports workflow variable templates
`top_k`	integer	knowledge	Number of knowledge chunks to return (1–20)
`completion`	object	agent, task	Completion criteria: `instruction`, `minimum_user_turns`, `max_user_turns`, `timeout_enabled`, `timeout_seconds`, `on_timeout` (`closing`/`continue`), `require_reason`
`avatar`	object	agent	Avatar behavior profile
`voice`	object	agent	Voice override using the Assistant provider contract
`model`	object	agent	LLM override using the Assistant provider contract
`transcriber`	object	agent	STT override, including `vocabulary` and fallbacks, using the Assistant provider contract
`assistant_id`	string	subagent	Source assistant UUID
`assistant_name`	string	subagent	Source assistant name
`assistant_overrides`	object	subagent	Per-node overrides applied on top of the source assistant
`extraction_type`	string	task	`custom`, `prebuilt`, or `choice`
`prebuilt_config`	object	task	Prebuilt task configuration (name, email, phone, address, dob, credit_card, dtmf)
`extract_variables`	array	task	Fields to collect: `{ "name", "type", "description", "required", "require_confirmation", "enum_values" }`. For `choice` fields, `enum_values` maps stored keys to spoken aliases, e.g. `{ "yo": ["Yoruba", "Yorùbá"], "en": ["English"] }`
`conditions`	array	logic	Conditional branches
`branches`	array	logic	Named branch definitions: `{ "id", "label" }`
`url`	string	function	HTTP endpoint
`method`	string	function	HTTP method (GET, POST, PUT, PATCH, DELETE)
`headers`	object	function	Request headers
`body_template`	string	function	Request body template
`output_key`	string	function, knowledge, Google nodes	Variable key where the node response is stored; defaults to the node ID
`timeout_ms`	integer	function	Default `5000`
`retries`	integer	function	Default `2`
`idempotency_key`	string	function	Stable retry key
`allowed_domains`	array	function	Domain allowlist
`on_error`	string	function	Error handling strategy
`auth_method`	string	function	`bearer`, `basic`, or `none`
`server_credential_id`	string	function	Server credential UUID for auth
`transferCall`	object	transferCall	Transfer configuration (warm/cold, destination)
`googleSheets`, `googleCalendar`, `googleGmail`, `googleGmailSend`	object	google nodes	Integration configuration
`apiRequest`	object	apiRequest	Function node configuration (editor alias)

Edges

Each edge is { "id": string, "source": string, "source_handle": string?, "target": string, "condition": object? }.

condition.variable

string

Session variable to evaluate.

condition.operator

string

Comparison operator: eq, neq, gt, gte, lt, lte, contains, exists.

condition.value

string

Value to compare against.

Logic evaluates outgoing edges in order — put specific conditions first and leave one unconditional edge as the fallback. Legacy payloads can nest the condition inside data.condition/data.conditions; the API normalizes these into condition.

Variables Schema

variables_schema maps variable names to their typed definitions.

Field	Type	Description
`type`	string	`string`, `number`, `boolean`, `datetime`, or `object`
`source_node`	string	Node id that populates the variable
`required`	boolean	Whether the variable must be set before routing
`pii`	boolean	Mark as personally identifiable information (drives redaction and retention behavior)

"variables_schema": {
  "language": { "type": "string", "source_node": "language", "required": true, "pii": false },
  "phone_number": { "type": "string", "source_node": "collect", "required": true, "pii": true }
}

Compliance Plan

Workflows accept the same compliance_plan structure as assistants, including audio_redaction. The plan is inert unless enabled is true. The published version snapshot controls runtime disclosure, consent, retention, redaction, and whether post-call artifacts can be emitted. Workflows accept the same compliance_plan structure as assistants: enabled, ai_disclosure, recording_consent (with max_attempts 1–3 and end_call_on_decline), transcript_retention, and sensitive_data (with up to 10 custom regex patterns). The plan is inert unless enabled is true.

"compliance_plan": {
  "enabled": true,
  "ai_disclosure": { "enabled": true, "message": "This call is recorded for quality purposes." },
  "recording_consent": {
    "enabled": true,
    "message": "Do you agree to this conversation being recorded?",
    "max_attempts": 2,
    "end_call_on_decline": true
  },
  "transcript_retention": { "enabled": false },
  "sensitive_data": { "enabled": true, "custom_patterns": [] }
}

Inheritance and overrides

The workflow global configuration establishes the default prompt, providers, compliance policy, and analysis selection. A Start node’s start_speaking_plan overrides the inherited speaking plan for the workflow session. Each Agent node can then override model, voice, and transcriber for its scoped handoff; Conversation nodes keep the active Agent configuration. Provider objects use the same canonical snake_case structures as Create Assistant.

Full graph payload

curl -X POST https://api.vonative.com/v1/workflows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @workflow.json

{
  "name": "Multilingual support",
  "description": "Collect a language, route it, and resolve the request.",
  "nodes": [
    {"id":"start","type":"start","data":{"label":"Start","first_message_mode":"assistant-speaks-first"}},
    {"id":"welcome","type":"say","data":{"label":"Welcome","text":"Which language do you prefer: Yoruba or English?"}},
    {"id":"language","type":"task","data":{"label":"Language","extraction_type":"custom","extract_variables":[{"name":"language","type":"choice","description":"Caller language","required":true,"require_confirmation":false,"enum_values":{"yo":["Yoruba","Yorùbá"],"en":["English"]}}],"completion":{"instruction":"Collect the configured fields.","minimum_user_turns":1,"max_user_turns":6,"timeout_enabled":true,"timeout_seconds":30,"on_timeout":"closing","require_reason":false}}},
    {"id":"route-language","type":"logic","data":{"label":"Route language","branches":[{"id":"yo","label":"Yoruba"},{"id":"en","label":"English"}]}},
    {"id":"yoruba-agent","type":"agent","data":{"label":"Yoruba Agent","prompt":"Speak Yoruba and resolve the caller's support request. Return resolution_status and needs_human.","model":{"provider":"openai","model":"gpt-4o-mini"},"voice":{"provider":"spitch","voiceId":"segun","language":"yo"},"transcriber":{"provider":"spitch","language":"yo"},"tool_ids":[],"file_ids":[],"completion":{"instruction":"Complete after resolving the request and provide a reason.","minimum_user_turns":1,"max_user_turns":8,"timeout_enabled":true,"timeout_seconds":180,"on_timeout":"closing","require_reason":true}}},
    {"id":"english-agent","type":"agent","data":{"label":"English Agent","prompt":"Resolve the caller's support request. Return resolution_status and needs_human.","model":{"provider":"openai","model":"gpt-4o-mini"},"voice":{"provider":"spitch","voiceId":"lucy","language":"en"},"transcriber":{"provider":"spitch","language":"en"},"tool_ids":[],"file_ids":[],"completion":{"instruction":"Complete after resolving the request and provide a reason.","minimum_user_turns":1,"max_user_turns":8,"timeout_enabled":true,"timeout_seconds":180,"on_timeout":"closing","require_reason":true}}},
    {"id":"closing","type":"say","data":{"label":"Closing","text":"Thank you for contacting support."}},
    {"id":"end","type":"endCall","data":{"label":"End Call"}}
  ],
  "edges": [
    {"id":"e-start-welcome","source":"start","target":"welcome"},
    {"id":"e-welcome-language","source":"welcome","target":"language"},
    {"id":"e-language-route","source":"language","target":"route-language"},
    {"id":"e-route-yo","source":"route-language","source_handle":"yo","target":"yoruba-agent","condition":{"variable":"language","operator":"eq","value":"yo"}},
    {"id":"e-route-en","source":"route-language","source_handle":"en","target":"english-agent","condition":{"variable":"language","operator":"eq","value":"en"}},
    {"id":"e-route-default","source":"route-language","target":"english-agent"},
    {"id":"e-yo-close","source":"yoruba-agent","target":"closing"},
    {"id":"e-en-close","source":"english-agent","target":"closing"},
    {"id":"e-close-end","source":"closing","target":"end"}
  ],
  "global_edges": [],
  "variables_schema": {"language":{"type":"string","source_node":"language","required":true,"pii":false}},
  "ui_state": {"viewport":{"x":0,"y":0,"zoom":1}},
  "compliance_plan": {"transcript_retention":{"enabled":true}},
  "analysis_enabled": false,
  "analysis_profile_id": null
}

Errors

Status	Description
`422`	Invalid node type, edge reference, or condition schema
`409`	Workflow name conflict within the organization

Authentication

Introduction

Assistants

Phone Numbers

Workflows

Calls

Meets

Files

Tools

Server Credentials

Sessions

Call Logs

Webhooks

Campaigns

Create Workflow

Create Workflow

Graph Reference

Nodes

Edges

Variables Schema

Compliance Plan

Inheritance and overrides

Full graph payload

Errors

​Create Workflow

​Graph Reference

​Nodes

​Edges

​Variables Schema

​Compliance Plan

​Inheritance and overrides

​Full graph payload

​Errors

Create Workflow

Graph Reference

Nodes

Edges

Variables Schema

Compliance Plan

Inheritance and overrides

Full graph payload

Errors