Replace a flow's draft

PUT

/flows/{id}/draft

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const flowDraft = await mv.flows.updateDraft("flow_7Hk2Lm9Qp", {
  base_rev: 17,
  graph: {
    nodes: [
      {
        key: "start",
        start: {
          greeting: "Hello!",
        },
        transitions: [
          {
            condition: {
              kind: "always",
            },
            next: "bye",
          },
        ],
        type: "start",
      },
      {
        end: {
          message: "Goodbye.",
        },
        key: "bye",
        type: "end",
      },
    ],
  },
});
console.log(flowDraft);

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

flow_draft = client.flows.update_draft("flow_7Hk2Lm9Qp", {
    "base_rev": 17,
    "graph": {
        "nodes": [
            {
                "key": "start",
                "start": {
                    "greeting": "Hello!",
                },
                "transitions": [
                    {
                        "condition": {
                            "kind": "always",
                        },
                        "next": "bye",
                    },
                ],
                "type": "start",
            },
            {
                "end": {
                    "message": "Goodbye.",
                },
                "key": "bye",
                "type": "end",
            },
        ],
    },
})
print(flow_draft)

curl -X PUT https://api.morevoice.ai/v1/flows/flow_7Hk2Lm9Qp/draft \
  -H "Authorization: Bearer $MOREVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "base_rev": 17,
  "graph": {
    "nodes": [
      {
        "key": "start",
        "start": {
          "greeting": "Hello!"
        },
        "transitions": [
          {
            "condition": {
              "kind": "always"
            },
            "next": "bye"
          }
        ],
        "type": "start"
      },
      {
        "end": {
          "message": "Goodbye."
        },
        "key": "bye",
        "type": "end"
      }
    ]
  }
}'

Replaces the draft graph. Nodes are matched to the stored ones by id: what the v1 schema does not carry (groups, notes, editor state) is kept, and internal nodes stay exactly as stored. base_rev must be the draft’s current revision, else 409 (details.draft_rev) and nothing is written — read the draft again and retry. Calls keep running the published version until you publish.

Try it in the API playground with a test-mode key.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string

<= 200 characters /^flow_[0-9A-Za-z]+$/

A flow ID (flow_…).

Header Parameters

MoreVoice-Version

string

/^\d{4}-\d{2}-\d{2}$/

The API version to use for this request. Defaults to the version the API key is pinned to.

Example

2026-11-01

Request Body^required

application/json

The new draft, with optimistic concurrency.

object

base_rev

required

The draft rev you read: a newer draft (changed elsewhere) answers 409 and nothing is written.

integer

<= 9007199254740991

graph

required

A whole graph to write. Nodes are matched to the stored draft by key.

object

kind

Must be the flow’s kind (default: the flow’s).

string

Allowed values: voice agent_script ivr

nodes

required

Array<object>

<= 2000 items

A flow node to write (v1 node schema). Settings you leave out keep their stored values, or the type’s defaults for a new node.

object

ai_agent

Type ai_agent: A free conversation step with a goal: the AI talks until a transition matches.

object

allowed_tools

The assistant’s tools usable in this step (by name).

Array<string>

<= 50 items

collect

Variables the AI gathers in this step.

Array<object>

<= 50 items

object

required

required

boolean

var

required

string

<= 120 characters

goal

string

<= 4000 characters

instructions

string

<= 20000 characters

Answer from these knowledge-base documents.

object

document_ids

required

Array<string>

<= 200 items

min_score

number

<= 1

max_turns

integer

>= 1 <= 100

opening

string

<= 4000 characters

api

Type api: Call an HTTP API during the call; map the response to variables.

object

auth

How the request authenticates. Reference credentials as {{secrets.NAME}} rather than in clear.

object

header

Api_key / hmac (required): the header name.

string

<= 200 characters

password

Basic (required).

string

<= 4000 characters

secret

Hmac (required): the signing secret.

string

<= 4000 characters

token

Bearer (required).

string

<= 4000 characters

type

required

string

Allowed values: none bearer basic api_key hmac

username

Basic (required).

string

<= 500 characters

value

Api_key (required).

string

<= 4000 characters

body

The body template ({{templates}} JSON-escaped when body_type is json).

string

<= 100000 characters

body_type

string

Allowed values: json form none

headers

Array<object>

<= 100 items

object

key

required

string

<= 200 characters

value

required

string

<= 4000 characters

method

string

Allowed values: GET POST PUT PATCH DELETE

query

Array<object>

<= 100 items

object

key

required

string

<= 200 characters

value

required

string

<= 4000 characters

response_map

Response fields → variables.

Array<object>

<= 100 items

object

path

required

E.g. data.items[0].name

string

<= 500 characters

var

required

string

<= 120 characters

retries

integer

<= 5

success_when

When the response counts as a success (default: any 2xx).

object

mode

required

string

Allowed values: all any

rules

required

Array<object>

<= 50 items

A rule on a variable.

object

required

string

Allowed values: eq neq gt gte lt lte contains not_contains matches exists empty in not_in

value

Any of:

string

<= 2000 characters

var

required

A variable key, e.g. budget, contact.city, api.status.

string

<= 120 characters

timeout_ms

integer

>= 100 <= 60000

url

The URL ({{templates}} allowed).

string

<= 4000 characters

wait_text

Said while waiting.

string

<= 1000 characters

decision

Type decision: Branch by rules on variables (no AI).

object

note

string

<= 2000 characters

disabled

boolean

dtmf_menu

Type dtmf_menu: A keypad menu.

object

also_speech

Callers may say the option instead of pressing it.

boolean

audio_id

A audio asset ID (aud_…).

string

<= 200 characters /^aud_[0-9A-Za-z]+$/

invalid_prompt

string

<= 2000 characters

no_input_prompt

string

<= 2000 characters

options

Array<object>

<= 40 items

object

digit

required

string

<= 8 characters

keywords

Array<string>

<= 50 items

label

required

Also the spoken choice.

string

<= 200 characters

prompt

string

<= 4000 characters

retries

integer

<= 10

timeout_seconds

number

>= 1 <= 120

end

Type end: End the call.

object

disposition

string

<= 120 characters

message

string

<= 4000 characters

notes

string

<= 2000 characters

reason

string

<= 200 characters

global

Any of:

object
null

Makes the node reachable from anywhere in the call when its condition matches.

object

after

required

Return: back to where the caller was; stay: continue here; goto: follow this node’s transitions.

string

Allowed values: return stay goto

condition

required

Intent, keyword or dtmf.

object

after_seconds

No_response (required): seconds of silence.

number

>= 1 <= 600

description

Intent (required): what the caller means.

string

<= 2000 characters

digits

Dtmf (required): keypad digits — 1, *, # or a range 1-3.

string

<= 20 characters

examples

Intent: example phrasings.

Array<string>

<= 50 items

kind

required

Intent: the AI decides what the caller means · keyword · variable rules (no AI) · dtmf keys · always (right after the node) · no_response · outcome of an action · else (the fallback, last).

string

Allowed values: intent keyword variable dtmf always no_response outcome else

match

Keyword: any (default) or all of the phrases.

string

Allowed values: any all

mode

Variable (required): all or any of the rules.

string

Allowed values: all any

outcome

Outcome (required): the result of an action or collect node.

string

Allowed values: success error timeout collected max_retries invalid busy no_answer returned transferred failed sent answered not_found scheduled done open closed holiday recorded no_message

phrases

Keyword (required): phrases the caller says; a trailing * matches a prefix.

Array<string>

<= 100 items

rules

Variable (required): the rules.

Array<object>

<= 50 items

A rule on a variable.

object

required

string

Allowed values: eq neq gt gte lt lte contains not_contains matches exists empty in not_in

value

Any of:

string

<= 2000 characters

var

required

A variable key, e.g. budget, contact.city, api.status.

string

<= 120 characters

times

No_response: in a row (default 1).

integer

>= 1 <= 10

max_per_call

required

integer

>= 1 <= 100

priority

required

Higher wins when several global nodes match.

number

scope

required

Where in the call the trigger listens.

object

node_keys

Only / except: the nodes it applies to (or not).

Array<string>

type

required

string

Allowed values: everywhere only except

hours

Type hours: Branch on opening hours: open, closed or holiday.

object

closed_dates

Extra closed days, YYYY-MM-DD.

Array<string>

<= 400 items

holidays

Closed on Israeli holidays (the holiday outcome).

boolean

open_dates

Exceptional open days, YYYY-MM-DD.

Array<string>

<= 400 items

shabbat

Closed on Shabbat (Israel).

boolean

timezone

IANA time zone (default: the flow’s).

string

<= 60 characters

windows

Array<object>

<= 50 items

object

days

required

0 = Sunday … 6 = Saturday.

Array<integer>

end

required

HH:MM

string

<= 5 characters

start

required

HH:MM

string

<= 5 characters

integration

Type integration: Run a connected CRM or calendar action during the call (look the caller up, add a note, create a task): success, not found or error.

object

action

The action, e.g. crm.lookup_contact, crm.add_note, crm.create_task.

string

<= 120 characters

args

The action’s arguments by name ({{templates}} allowed).

object

key

additional properties

string

<= 4000 characters

integration_connection_id

The connected integration account (Settings › Integrations). Integration connections have no API object (and no public ID prefix) yet: the id is the dashboard’s.

string

<= 64 characters

result_map

Result fields → variables (e.g. contacts[0].name → customer_name).

Array<object>

<= 100 items

object

path

required

E.g. data.items[0].name

string

<= 500 characters

var

required

string

<= 120 characters

wait_text

Said while the action runs.

string

<= 1000 characters

internal

Type internal: a node of a type outside the v1 schema (SMS, e-mail, voicemail, callbacks, agent-script steps…). Read-only: when you write the draft, the stored node is kept; only its transitions’ next may change.

object

raw

object

key

additional properties

type

string

<= 64 characters

kb_answer

Type kb_answer: Answer from the knowledge base.

object

answer_style

string

<= 1000 characters

document_ids

Empty: the whole knowledge base.

Array<string>

<= 200 items

min_score

number

<= 1

not_found_text

string

<= 4000 characters

key

required

The node’s key: your stable identifier, unique in the graph.

string

/^[A-Za-z0-9_.:-]{1,64}$/

position

Default: laid out automatically.

object

required

number

required

number

post_api

Type post_api: Call an HTTP API after the call.

object

auth

How the request authenticates. Reference credentials as {{secrets.NAME}} rather than in clear.

object

header

Api_key / hmac (required): the header name.

string

<= 200 characters

password

Basic (required).

string

<= 4000 characters

secret

Hmac (required): the signing secret.

string

<= 4000 characters

token

Bearer (required).

string

<= 4000 characters

type

required

string

Allowed values: none bearer basic api_key hmac

username

Basic (required).

string

<= 500 characters

value

Api_key (required).

string

<= 4000 characters

body

The body template ({{templates}} JSON-escaped when body_type is json).

string

<= 100000 characters

body_type

string

Allowed values: json form none

headers

Array<object>

<= 100 items

object

key

required

string

<= 200 characters

value

required

string

<= 4000 characters

method

string

Allowed values: GET POST PUT PATCH DELETE

query

Array<object>

<= 100 items

object

key

required

string

<= 200 characters

value

required

string

<= 4000 characters

response_map

Response fields → variables.

Array<object>

<= 100 items

object

path

required

E.g. data.items[0].name

string

<= 500 characters

var

required

string

<= 120 characters

retries

integer

<= 5

success_when

When the response counts as a success (default: any 2xx).

object

mode

required

string

Allowed values: all any

rules

required

Array<object>

<= 50 items

A rule on a variable.

object

required

string

Allowed values: eq neq gt gte lt lte contains not_contains matches exists empty in not_in

value

Any of:

string

<= 2000 characters

var

required

A variable key, e.g. budget, contact.city, api.status.

string

<= 120 characters

timeout_ms

integer

>= 100 <= 60000

url

The URL ({{templates}} allowed).

string

<= 4000 characters

wait_text

Said while waiting.

string

<= 1000 characters

post_integration

Type post_integration: Run a connected CRM action after the call (add a note, create a follow-up task).

object

action

The action, e.g. crm.lookup_contact, crm.add_note, crm.create_task.

string

<= 120 characters

args

The action’s arguments by name ({{templates}} allowed).

object

key

additional properties

string

<= 4000 characters

integration_connection_id

The connected integration account (Settings › Integrations). Integration connections have no API object (and no public ID prefix) yet: the id is the dashboard’s.

string

<= 64 characters

result_map

Result fields → variables (e.g. contacts[0].name → customer_name).

Array<object>

<= 100 items

object

path

required

E.g. data.items[0].name

string

<= 500 characters

var

required

string

<= 120 characters

question

Type question: Ask for one detail, validate it and store it in a variable.

object

audio_id

A audio asset ID (aud_…).

string

<= 200 characters /^aud_[0-9A-Za-z]+$/

confirm

Read the answer back for confirmation.

boolean

dtmf_input

Accept the answer on the keypad too.

object

inter_digit_ms

integer

>= 500 <= 15000

log_digits

boolean

max_digits

required

integer

>= 1 <= 40

terminator

string

<= 2 characters

max_retries

integer

<= 10

prompt

string

<= 4000 characters

reask_prompts

Array<string>

<= 10 items

validation

object

options

Array<string>

<= 200 items

pattern

string

<= 400 characters

type

string

Allowed values: text number boolean date phone email enum json

var

The variable the answer is stored in.

string

<= 120 characters

say

Type say: Say an exact line, or one the AI rephrases.

object

audio_id

An uploaded prompt played instead of speech.

string

<= 200 characters /^aud_[0-9A-Za-z]+$/

interruptible

boolean

mode

string

Allowed values: verbatim rephrase

style

string

<= 500 characters

text

string

<= 4000 characters

set_variable

Type set_variable: Set variables.

object

assignments

Array<object>

<= 100 items

object

value

required

A literal or a {{template}}.

string

<= 4000 characters

var

required

string

<= 120 characters

start

Type start: Where every call begins: the greeting.

object

first_message_mode

string

Allowed values: speak wait generate

greeting

string

<= 4000 characters

interruptible

boolean

title

string

<= 200 characters

transfer

Type transfer: Transfer the call to a queue, a number, another flow or a SIP address.

object

announce_text

string

<= 1000 characters

assistant_id

A assistant ID (asst_…).

string

<= 200 characters /^asst_[0-9A-Za-z]+$/

destination

A phone number, or a SIP URI for mode sip.

string

<= 200 characters

flow_id

A flow ID (flow_…).

string

<= 200 characters /^flow_[0-9A-Za-z]+$/

mode

string

Allowed values: queue number flow sip participant

queue_id

A queue ID (q_…).

string

<= 200 characters /^q_[0-9A-Za-z]+$/

screen_pop_vars

Array<string>

<= 50 items

timeout_seconds

integer

>= 1 <= 600

whisper_summary

Warm transfer: whisper an AI summary to the receiving side first.

boolean

transitions

The node’s outputs, in priority order. Default: the type’s standard outputs (a new node) or the stored ones.

Array<object>

<= 60 items

A node output: when its condition matches, the call moves to next.

object

condition

required

When a transition is taken: kind and that kind’s fields.

object

after_seconds

No_response (required): seconds of silence.

number

>= 1 <= 600

description

Intent (required): what the caller means.

string

<= 2000 characters

digits

Dtmf (required): keypad digits — 1, *, # or a range 1-3.

string

<= 20 characters

examples

Intent: example phrasings.

Array<string>

<= 50 items

kind

required

Intent: the AI decides what the caller means · keyword · variable rules (no AI) · dtmf keys · always (right after the node) · no_response · outcome of an action · else (the fallback, last).

string

Allowed values: intent keyword variable dtmf always no_response outcome else

match

Keyword: any (default) or all of the phrases.

string

Allowed values: any all

mode

Variable (required): all or any of the rules.

string

Allowed values: all any

outcome

Outcome (required): the result of an action or collect node.

string

Allowed values: success error timeout collected max_retries invalid busy no_answer returned transferred failed sent answered not_found scheduled done open closed holiday recorded no_message

phrases

Keyword (required): phrases the caller says; a trailing * matches a prefix.

Array<string>

<= 100 items

rules

Variable (required): the rules.

Array<object>

<= 50 items

A rule on a variable.

object

required

string

Allowed values: eq neq gt gte lt lte contains not_contains matches exists empty in not_in

value

Any of:

string

<= 2000 characters

var

required

A variable key, e.g. budget, contact.city, api.status.

string

<= 120 characters

times

No_response: in a row (default 1).

integer

>= 1 <= 10

key

The transition’s key (an output port), unique in the node. Default: a new key.

string

>= 1 characters <= 64 characters

label

string

<= 200 characters

next

Any of:

string
null

The node’s key: your stable identifier, unique in the graph.

string

/^[A-Za-z0-9_.:-]{1,64}$/

type

required

The node type. Its settings are under the property of the same name (type: "say" → say: {…}).

string

Allowed values: start say question ai_agent kb_answer api post_api integration post_integration set_variable decision dtmf_menu hours transfer end internal

schema_version

number

Allowed value: 1

settings

Merged with the stored settings.

object

classifier_model

Any of:

string
null

string

<= 60 characters

fallback_node_key

Any of:

string
null

The node’s key: your stable identifier, unique in the graph.

string

/^[A-Za-z0-9_.:-]{1,64}$/

global_prompt

Persona and global instructions, combined with the assistant’s prompt.

string

<= 20000 characters

ivr

Any of:

object
null

object

inter_digit_ms

integer

>= 500 <= 15000

max_invalid_total

integer

>= 1 <= 50

no_input_seconds

number

>= 1 <= 60

operator

Any of:

object
null

object

announce_text

string

<= 1000 characters

destination

string

<= 200 characters

mode

required

string

Allowed values: queue number

queue_id

Any of:

string
null

A queue ID (q_…).

string

<= 200 characters /^q_[0-9A-Za-z]+$/

operator_key

string

<= 2 characters

repeat_key

string

<= 2 characters

speech

Off: keypad only; keywords: spoken choices matched to the options; smart: keywords, then an AI routing check.

string

Allowed values: off keywords smart

timezone

string

<= 60 characters

voice

object

language_code

required

string

<= 10 characters

model

required

string

<= 80 characters

style

required

string

<= 500 characters

voice_name

required

string

<= 120 characters

language

string

<= 10 characters

max_chain_steps

integer

>= 1 <= 500

max_transitions

integer

>= 1 <= 5000

max_turns_per_node

integer

>= 1 <= 100

max_visits_per_node

integer

>= 1 <= 100

on_pre_call_fail

string

Allowed values: continue end

pre_call_timeout_ms

integer

>= 200 <= 20000

style_field

string

Allowed values: auto off

transition_model

Inline: the reply decides the transition; classifier: a separate fast check.

string

Allowed values: inline classifier

variables

Default: the stored variables.

Array<object>

<= 500 items

object

default

string

<= 2000 characters

description

string

<= 1000 characters

key

required

string

>= 1 characters <= 80 characters

label

required

string

<= 120 characters

options

Array<string>

<= 200 items

pattern

string

<= 400 characters

sample

A sample value for simulations and tests.

string

<= 2000 characters

sensitive

Redacted in logs, metrics and analytics.

boolean

source

required

Where its value comes from: the contact, a pre-call API, collected in the call, an API, set by a node, the system, or extracted after the call.

string

Allowed values: contact precall collected api set system extracted

type

required

string

Allowed values: text number boolean date phone email enum json

Example

{
  "base_rev": 17,
  "graph": {
    "nodes": [
      {
        "key": "start",
        "start": {
          "greeting": "Hello!"
        },
        "transitions": [
          {
            "condition": {
              "kind": "always"
            },
            "next": "bye"
          }
        ],
        "type": "start"
      },
      {
        "end": {
          "message": "Goodbye."
        },
        "key": "bye",
        "type": "end"
      }
    ]
  }
}

Responses

200

application/json

A flow’s editable draft.

object

flow_id

required

A flow ID (prefix flow_).

string

/^flow_[0-9A-Za-z]+$/

graph

required

A flow’s graph: nodes (v1 node schema) wired by their transitions’ next, variables and settings.

object

kind

required

string

Allowed values: voice agent_script ivr

nodes

required

Array<object>

A flow node (v1 node schema): type and its settings under the property of the same name.

object

ai_agent

Type ai_agent: A free conversation step with a goal: the AI talks until a transition matches.

object

allowed_tools

required

The assistant’s tools usable in this step (by name).

Array<string>

<= 50 items

collect

required

Variables the AI gathers in this step.

Array<object>

<= 50 items

object

required

required

boolean

var

required

string

<= 120 characters

goal

required

string

<= 4000 characters

instructions

required

string

<= 20000 characters

Answer from these knowledge-base documents.

object

document_ids

required

Array<string>

<= 200 items

min_score

number

<= 1

max_turns

integer

>= 1 <= 100

opening

string

<= 4000 characters

api

Type api: Call an HTTP API during the call; map the response to variables.

object

auth

required

How the request authenticates. Reference credentials as {{secrets.NAME}} rather than in clear.

object

header

Api_key / hmac (required): the header name.

string

<= 200 characters

password

Basic (required).

string

<= 4000 characters

secret

Hmac (required): the signing secret.

string

<= 4000 characters

token

Bearer (required).

string

<= 4000 characters

type

required

string

Allowed values: none bearer basic api_key hmac

username

Basic (required).

string

<= 500 characters

value

Api_key (required).

string

<= 4000 characters

body

required

The body template ({{templates}} JSON-escaped when body_type is json).

string

<= 100000 characters

body_type

required

string

Allowed values: json form none

headers

required

Array<object>

<= 100 items

object

key

required

string

<= 200 characters

value

required

string

<= 4000 characters

method

required

string

Allowed values: GET POST PUT PATCH DELETE

query

required

Array<object>

<= 100 items

object

key

required

string

<= 200 characters

value

required

string

<= 4000 characters

response_map

required

Response fields → variables.

Array<object>

<= 100 items

object

path

required

E.g. data.items[0].name

string

<= 500 characters

var

required

string

<= 120 characters

retries

required

integer

<= 5

success_when

When the response counts as a success (default: any 2xx).

object

mode

required

string

Allowed values: all any

rules

required

Array<object>

<= 50 items

A rule on a variable.

object

required

string

Allowed values: eq neq gt gte lt lte contains not_contains matches exists empty in not_in

value

Any of:

string

<= 2000 characters

var

required

A variable key, e.g. budget, contact.city, api.status.

string

<= 120 characters

timeout_ms

required

integer

>= 100 <= 60000

url

required

The URL ({{templates}} allowed).

string

<= 4000 characters

wait_text

Said while waiting.

string

<= 1000 characters

decision

Type decision: Branch by rules on variables (no AI).

object

note

string

<= 2000 characters

disabled

required

boolean

dtmf_menu

Type dtmf_menu: A keypad menu.

object

also_speech

required

Callers may say the option instead of pressing it.

boolean

audio_id

A audio asset ID (prefix aud_).

string

/^aud_[0-9A-Za-z]+$/

invalid_prompt

string

<= 2000 characters

no_input_prompt

string

<= 2000 characters

options

required

Array<object>

<= 40 items

object

digit

required

string

<= 8 characters

keywords

Array<string>

<= 50 items

label

required

Also the spoken choice.

string

<= 200 characters

prompt

required

string

<= 4000 characters

retries

required

integer

<= 10

timeout_seconds

required

number

>= 1 <= 120

end

Type end: End the call.

object

disposition

string

<= 120 characters

message

required

string

<= 4000 characters

notes

string

<= 2000 characters

reason

string

<= 200 characters

global

required

Any of:

object
null

Makes the node reachable from anywhere in the call when its condition matches.

object

after

required

Return: back to where the caller was; stay: continue here; goto: follow this node’s transitions.

string

Allowed values: return stay goto

condition

required

Intent, keyword or dtmf.

object

after_seconds

No_response (required): seconds of silence.

number

>= 1 <= 600

description

Intent (required): what the caller means.

string

<= 2000 characters

digits

Dtmf (required): keypad digits — 1, *, # or a range 1-3.

string

<= 20 characters

examples

Intent: example phrasings.

Array<string>

<= 50 items

kind

required

Intent: the AI decides what the caller means · keyword · variable rules (no AI) · dtmf keys · always (right after the node) · no_response · outcome of an action · else (the fallback, last).

string

Allowed values: intent keyword variable dtmf always no_response outcome else

match

Keyword: any (default) or all of the phrases.

string

Allowed values: any all

mode

Variable (required): all or any of the rules.

string

Allowed values: all any

outcome

Outcome (required): the result of an action or collect node.

string

Allowed values: success error timeout collected max_retries invalid busy no_answer returned transferred failed sent answered not_found scheduled done open closed holiday recorded no_message

phrases

Keyword (required): phrases the caller says; a trailing * matches a prefix.

Array<string>

<= 100 items

rules

Variable (required): the rules.

Array<object>

<= 50 items

A rule on a variable.

object

required

string

Allowed values: eq neq gt gte lt lte contains not_contains matches exists empty in not_in

value

Any of:

string

<= 2000 characters

var

required

A variable key, e.g. budget, contact.city, api.status.

string

<= 120 characters

times

No_response: in a row (default 1).

integer

>= 1 <= 10

max_per_call

required

integer

>= 1 <= 100

priority

required

Higher wins when several global nodes match.

number

scope

required

Where in the call the trigger listens.

object

node_keys

Only / except: the nodes it applies to (or not).

Array<string>

type

required

string

Allowed values: everywhere only except

hours

Type hours: Branch on opening hours: open, closed or holiday.

object

closed_dates

required

Extra closed days, YYYY-MM-DD.

Array<string>

<= 400 items

holidays

required

Closed on Israeli holidays (the holiday outcome).

boolean

open_dates

required

Exceptional open days, YYYY-MM-DD.

Array<string>

<= 400 items

shabbat

required

Closed on Shabbat (Israel).

boolean

timezone

IANA time zone (default: the flow’s).

string

<= 60 characters

windows

required

Array<object>

<= 50 items

object

days

required

0 = Sunday … 6 = Saturday.

Array<integer>

end

required

HH:MM

string

<= 5 characters

start

required

HH:MM

string

<= 5 characters

integration

Type integration: Run a connected CRM or calendar action during the call (look the caller up, add a note, create a task): success, not found or error.

object

action

required

The action, e.g. crm.lookup_contact, crm.add_note, crm.create_task.

string

<= 120 characters

args

required

The action’s arguments by name ({{templates}} allowed).

object

key

additional properties

string

<= 4000 characters

integration_connection_id

required

The connected integration account (Settings › Integrations). Integration connections have no API object (and no public ID prefix) yet: the id is the dashboard’s.

string

<= 64 characters

result_map

required

Result fields → variables (e.g. contacts[0].name → customer_name).

Array<object>

<= 100 items

object

path

required

E.g. data.items[0].name

string

<= 500 characters

var

required

string

<= 120 characters

wait_text

Said while the action runs.

string

<= 1000 characters

internal

object

raw

required

The node as stored. Read-only: send it back unchanged.

object

key

additional properties

type

required

The internal node type (not part of the v1 schema).

string

kb_answer

Type kb_answer: Answer from the knowledge base.

object

answer_style

string

<= 1000 characters

document_ids

required

Empty: the whole knowledge base.

Array<string>

<= 200 items

min_score

number

<= 1

not_found_text

required

string

<= 4000 characters

key

required

The node’s key: your stable identifier, unique in the graph.

string

/^[A-Za-z0-9_.:-]{1,64}$/

position

required

The node’s place on the editor canvas.

object

required

number

required

number

post_api

Type post_api: Call an HTTP API after the call.

object

auth

required

How the request authenticates. Reference credentials as {{secrets.NAME}} rather than in clear.

object

header

Api_key / hmac (required): the header name.

string

<= 200 characters

password

Basic (required).

string

<= 4000 characters

secret

Hmac (required): the signing secret.

string

<= 4000 characters

token

Bearer (required).

string

<= 4000 characters

type

required

string

Allowed values: none bearer basic api_key hmac

username

Basic (required).

string

<= 500 characters

value

Api_key (required).

string

<= 4000 characters

body

required

The body template ({{templates}} JSON-escaped when body_type is json).

string

<= 100000 characters

body_type

required

string

Allowed values: json form none

headers

required

Array<object>

<= 100 items

object

key

required

string

<= 200 characters

value

required

string

<= 4000 characters

method

required

string

Allowed values: GET POST PUT PATCH DELETE

query

required

Array<object>

<= 100 items

object

key

required

string

<= 200 characters

value

required

string

<= 4000 characters

response_map

required

Response fields → variables.

Array<object>

<= 100 items

object

path

required

E.g. data.items[0].name

string

<= 500 characters

var

required

string

<= 120 characters

retries

required

integer

<= 5

success_when

When the response counts as a success (default: any 2xx).

object

mode

required

string

Allowed values: all any

rules

required

Array<object>

<= 50 items

A rule on a variable.

object

required

string

Allowed values: eq neq gt gte lt lte contains not_contains matches exists empty in not_in

value

Any of:

string

<= 2000 characters

var

required

A variable key, e.g. budget, contact.city, api.status.

string

<= 120 characters

timeout_ms

required

integer

>= 100 <= 60000

url

required

The URL ({{templates}} allowed).

string

<= 4000 characters

wait_text

Said while waiting.

string

<= 1000 characters

post_integration

Type post_integration: Run a connected CRM action after the call (add a note, create a follow-up task).

object

action

required

The action, e.g. crm.lookup_contact, crm.add_note, crm.create_task.

string

<= 120 characters

args

required

The action’s arguments by name ({{templates}} allowed).

object

key

additional properties

string

<= 4000 characters

integration_connection_id

required

The connected integration account (Settings › Integrations). Integration connections have no API object (and no public ID prefix) yet: the id is the dashboard’s.

string

<= 64 characters

result_map

required

Result fields → variables (e.g. contacts[0].name → customer_name).

Array<object>

<= 100 items

object

path

required

E.g. data.items[0].name

string

<= 500 characters

var

required

string

<= 120 characters

question

Type question: Ask for one detail, validate it and store it in a variable.

object

audio_id

A audio asset ID (prefix aud_).

string

/^aud_[0-9A-Za-z]+$/

confirm

required

Read the answer back for confirmation.

boolean

dtmf_input

Accept the answer on the keypad too.

object

inter_digit_ms

integer

>= 500 <= 15000

log_digits

boolean

max_digits

required

integer

>= 1 <= 40

terminator

string

<= 2 characters

max_retries

required

integer

<= 10

prompt

required

string

<= 4000 characters

reask_prompts

required

Array<string>

<= 10 items

validation

object

options

Array<string>

<= 200 items

pattern

string

<= 400 characters

type

string

Allowed values: text number boolean date phone email enum json

var

required

The variable the answer is stored in.

string

<= 120 characters

say

Type say: Say an exact line, or one the AI rephrases.

object

audio_id

An uploaded prompt played instead of speech.

string

/^aud_[0-9A-Za-z]+$/

interruptible

required

boolean

mode

required

string

Allowed values: verbatim rephrase

style

string

<= 500 characters

text

required

string

<= 4000 characters

set_variable

Type set_variable: Set variables.

object

assignments

required

Array<object>

<= 100 items

object

value

required

A literal or a {{template}}.

string

<= 4000 characters

var

required

string

<= 120 characters

start

Type start: Where every call begins: the greeting.

object

first_message_mode

required

string

Allowed values: speak wait generate

greeting

required

string

<= 4000 characters

interruptible

required

boolean

title

required

string

transfer

Type transfer: Transfer the call to a queue, a number, another flow or a SIP address.

object

announce_text

string

<= 1000 characters

assistant_id

A assistant ID (prefix asst_).

string

/^asst_[0-9A-Za-z]+$/

destination

A phone number, or a SIP URI for mode sip.

string

<= 200 characters

flow_id

A flow ID (prefix flow_).

string

/^flow_[0-9A-Za-z]+$/

mode

required

string

Allowed values: queue number flow sip participant

queue_id

A queue ID (prefix q_).

string

/^q_[0-9A-Za-z]+$/

screen_pop_vars

Array<string>

<= 50 items

timeout_seconds

required

integer

>= 1 <= 600

whisper_summary

required

Warm transfer: whisper an AI summary to the receiving side first.

boolean

transitions

required

Array<object>

A node output: when its condition matches, the call moves to next.

object

condition

required

When a transition is taken: kind and that kind’s fields.

object

after_seconds

No_response (required): seconds of silence.

number

>= 1 <= 600

description

Intent (required): what the caller means.

string

<= 2000 characters

digits

Dtmf (required): keypad digits — 1, *, # or a range 1-3.

string

<= 20 characters

examples

Intent: example phrasings.

Array<string>

<= 50 items

kind

required

Intent: the AI decides what the caller means · keyword · variable rules (no AI) · dtmf keys · always (right after the node) · no_response · outcome of an action · else (the fallback, last).

string

Allowed values: intent keyword variable dtmf always no_response outcome else

match

Keyword: any (default) or all of the phrases.

string

Allowed values: any all

mode

Variable (required): all or any of the rules.

string

Allowed values: all any

outcome

Outcome (required): the result of an action or collect node.

string

Allowed values: success error timeout collected max_retries invalid busy no_answer returned transferred failed sent answered not_found scheduled done open closed holiday recorded no_message

phrases

Keyword (required): phrases the caller says; a trailing * matches a prefix.

Array<string>

<= 100 items

rules

Variable (required): the rules.

Array<object>

<= 50 items

A rule on a variable.

object

required

string

Allowed values: eq neq gt gte lt lte contains not_contains matches exists empty in not_in

value

Any of:

string

<= 2000 characters

var

required

A variable key, e.g. budget, contact.city, api.status.

string

<= 120 characters

times

No_response: in a row (default 1).

integer

>= 1 <= 10

key

required

The transition’s key (an output port), unique in the node.

string

label

required

string

next

required

Any of:

string
null

The node’s key: your stable identifier, unique in the graph.

string

/^[A-Za-z0-9_.:-]{1,64}$/

type

required

The node type. Its settings are under the property of the same name (type: "say" → say: {…}).

string

Allowed values: start say question ai_agent kb_answer api post_api integration post_integration set_variable decision dtmf_menu hours transfer end internal

schema_version

required

The node schema version (1).

number

Allowed value: 1

settings

required

object

classifier_model

required

Any of:

string
null

string

<= 60 characters

fallback_node_key

required

Any of:

string
null

The node’s key: your stable identifier, unique in the graph.

string

/^[A-Za-z0-9_.:-]{1,64}$/

global_prompt

required

Persona and global instructions, combined with the assistant’s prompt.

string

<= 20000 characters

ivr

required

Any of:

object
null

object

inter_digit_ms

required

integer

>= 500 <= 15000

max_invalid_total

required

integer

>= 1 <= 50

no_input_seconds

required

number

>= 1 <= 60

operator

Any of:

object
null

object

announce_text

string

<= 1000 characters

destination

string

<= 200 characters

mode

required

string

Allowed values: queue number

queue_id

Any of:

string
null

A queue ID (prefix q_).

string

/^q_[0-9A-Za-z]+$/

operator_key

required

string

<= 2 characters

repeat_key

required

string

<= 2 characters

speech

required

Off: keypad only; keywords: spoken choices matched to the options; smart: keywords, then an AI routing check.

string

Allowed values: off keywords smart

timezone

required

string

<= 60 characters

voice

required

object

language_code

required

string

<= 10 characters

model

required

string

<= 80 characters

style

required

string

<= 500 characters

voice_name

required

string

<= 120 characters

language

required

string

<= 10 characters

max_chain_steps

required

integer

>= 1 <= 500

max_transitions

required

integer

>= 1 <= 5000

max_turns_per_node

required

integer

>= 1 <= 100

max_visits_per_node

required

integer

>= 1 <= 100

on_pre_call_fail

required

string

Allowed values: continue end

pre_call_timeout_ms

required

integer

>= 200 <= 20000

style_field

required

string

Allowed values: auto off

transition_model

required

Inline: the reply decides the transition; classifier: a separate fast check.

string

Allowed values: inline classifier

variables

required

Array<object>

object

default

string

<= 2000 characters

description

string

<= 1000 characters

key

required

string

>= 1 characters <= 80 characters

label

required

string

<= 120 characters

options

Array<string>

<= 200 items

pattern

string

<= 400 characters

sample

A sample value for simulations and tests.

string

<= 2000 characters

sensitive

Redacted in logs, metrics and analytics.

boolean

source

required

Where its value comes from: the contact, a pre-call API, collected in the call, an API, set by a node, the system, or extracted after the call.

string

Allowed values: contact precall collected api set system extracted

type

required

string

Allowed values: text number boolean date phone email enum json

livemode

required

true in live mode, false in test mode.

boolean

object

required

string

Allowed value: flow_draft

rev

required

Send as base_rev on the next write.

integer

>= -9007199254740991 <= 9007199254740991

updated

required

An ISO-8601 timestamp in UTC.

string format: date-time

Example

{
  "flow_id": "flow_7Kp1Ns4Vy6Ab9Dg2Hj5Lm8",
  "graph": {
    "kind": "voice",
    "nodes": [
      {
        "disabled": false,
        "global": null,
        "key": "start",
        "position": {
          "x": 0,
          "y": 0
        },
        "start": {
          "first_message_mode": "speak",
          "greeting": "Hello, you've reached Acme.",
          "interruptible": true
        },
        "title": "Start",
        "transitions": [
          {
            "condition": {
              "kind": "always"
            },
            "key": "t_next",
            "label": "Next",
            "next": "ask_id"
          }
        ],
        "type": "start"
      },
      {
        "disabled": false,
        "global": null,
        "key": "ask_id",
        "position": {
          "x": 320,
          "y": 0
        },
        "question": {
          "confirm": true,
          "max_retries": 2,
          "prompt": "What is your ID number?",
          "reask_prompts": [],
          "var": "customer_id"
        },
        "title": "Ask for the ID",
        "transitions": [
          {
            "condition": {
              "kind": "outcome",
              "outcome": "collected"
            },
            "key": "t_ok",
            "label": "Collected",
            "next": "bye"
          },
          {
            "condition": {
              "kind": "outcome",
              "outcome": "max_retries"
            },
            "key": "t_fail",
            "label": "Couldn't collect",
            "next": "bye"
          }
        ],
        "type": "question"
      },
      {
        "disabled": false,
        "end": {
          "message": "Thank you, goodbye."
        },
        "global": null,
        "key": "bye",
        "position": {
          "x": 640,
          "y": 0
        },
        "title": "Goodbye",
        "transitions": [],
        "type": "end"
      }
    ],
    "schema_version": 1,
    "settings": {
      "classifier_model": null,
      "fallback_node_key": null,
      "global_prompt": "You are Acme's friendly receptionist.",
      "ivr": null,
      "language": "en",
      "max_chain_steps": 25,
      "max_transitions": 200,
      "max_turns_per_node": 8,
      "max_visits_per_node": 5,
      "on_pre_call_fail": "continue",
      "pre_call_timeout_ms": 2500,
      "style_field": "auto",
      "transition_model": "inline"
    },
    "variables": [
      {
        "key": "customer_id",
        "label": "Customer ID",
        "source": "collected",
        "type": "text"
      }
    ]
  },
  "livemode": true,
  "object": "flow_draft",
  "rev": 17,
  "updated": "2026-11-03T09:14:22.000Z"
}

400

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#parameter-missing",
    "message": "Missing required parameter: to.",
    "param": "to",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "invalid_request_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

401

No valid API key was sent.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "invalid_api_key",
    "doc_url": "https://docs.morevoice.ai/api/errors#invalid-api-key",
    "message": "Invalid API key.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "authentication_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

403

The key may not do this (a missing scope, a plan limit, or a compliance block).

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "missing_scope",
    "doc_url": "https://docs.morevoice.ai/api/errors#missing-scope",
    "message": "This API key lacks the calls:write scope.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "permission_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

404

No object with this ID exists in this organisation and mode.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "resource_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#resource-missing",
    "message": "No such object: 'call_4Gk2'.",
    "param": "id",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "not_found"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

429

Too many requests, or no call capacity right now. Retry after the Retry-After delay.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "rate_limited",
    "doc_url": "https://docs.morevoice.ai/api/errors#rate-limited",
    "message": "Too many requests. Retry after 1 second.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "rate_limit_error"
  }
}

Headers

Retry-After

integer

Seconds to wait before retrying.

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

500

Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "internal_error",
    "doc_url": "https://docs.morevoice.ai/api/errors#internal-error",
    "message": "Something went wrong on MoreVoice's side.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "api_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

Replace a flow's draft

Authorizations

Parameters

Path Parameters

Header Parameters

Example

Request Bodyrequired

Example

Responses

200

Example

400

Example

Headers

401

Example

Headers

403

Example

Headers

404

Example

Headers

429

Example

Headers

500

Example

Headers

Request Body^required