Get workflow

curl --request GET \
  --url https://realtime-api.voiceflow.com/v1/stable/workflow/<workflowID> \
  --header 'Authorization: Bearer <token>'

const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/workflow/<workflowID>?projectID=<projectID>&environmentAlias=<environmentAlias>&cursor=<cursor>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/workflow/<workflowID>?projectID=<projectID>&environmentAlias=<environmentAlias>&cursor=<cursor>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()

{
  "workflow": {
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "counts": {
      "blocks": 0,
      "steps": 0,
      "unreachableBlocks": 0,
      "danglingLinks": 0
    }
  },
  "entry": {
    "stepID": "<string>",
    "name": "<string>",
    "next": "<string>",
    "actions": [
      {
        "id": "<string>",
        "kind": "<StableWorkflowStepKind>",
        "content": "<StableWorkflowStepContent>",
        "warnings": [
          "<StableWorkflowDiagnostic>"
        ]
      }
    ]
  },
  "blocks": [
    {
      "id": "<string>",
      "name": "<string>",
      "inboundFrom": [
        "<StableWorkflowInbound>"
      ],
      "steps": [
        "<StableWorkflowStep>"
      ]
    }
  ],
  "orphanSteps": [
    {
      "id": "<string>",
      "kind": "message",
      "exitClass": "sequential",
      "content": "<StableWorkflowStepMessageContent>",
      "fallsThroughTo": "<string>",
      "suppressedPorts": [
        "<string>"
      ],
      "links": [
        "<StableWorkflowLink>"
      ],
      "reconciledPorts": "<StableWorkflowReconciledPorts>",
      "warnings": [
        "<StableWorkflowDiagnostic>"
      ]
    }
  ],
  "warnings": [
    {
      "code": "BRANCH_NOT_LAST",
      "detail": "<string>"
    }
  ],
  "truncated": {
    "blocks": 0,
    "returned": 0,
    "nextCursor": "<string>"
  }
}

Get workflow

Reads a workflow as blocks of steps, each with its kind, content and links. Messages and prompts appear as IDs, not their text. Read it before any edit to get the block and step IDs.

GET

/v1/stable/workflow/{workflowID}

Get workflow

curl --request GET \
  --url https://realtime-api.voiceflow.com/v1/stable/workflow/<workflowID> \
  --header 'Authorization: Bearer <token>'

const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/workflow/<workflowID>?projectID=<projectID>&environmentAlias=<environmentAlias>&cursor=<cursor>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/workflow/<workflowID>?projectID=<projectID>&environmentAlias=<environmentAlias>&cursor=<cursor>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()

{
  "workflow": {
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "counts": {
      "blocks": 0,
      "steps": 0,
      "unreachableBlocks": 0,
      "danglingLinks": 0
    }
  },
  "entry": {
    "stepID": "<string>",
    "name": "<string>",
    "next": "<string>",
    "actions": [
      {
        "id": "<string>",
        "kind": "<StableWorkflowStepKind>",
        "content": "<StableWorkflowStepContent>",
        "warnings": [
          "<StableWorkflowDiagnostic>"
        ]
      }
    ]
  },
  "blocks": [
    {
      "id": "<string>",
      "name": "<string>",
      "inboundFrom": [
        "<StableWorkflowInbound>"
      ],
      "steps": [
        "<StableWorkflowStep>"
      ]
    }
  ],
  "orphanSteps": [
    {
      "id": "<string>",
      "kind": "message",
      "exitClass": "sequential",
      "content": "<StableWorkflowStepMessageContent>",
      "fallsThroughTo": "<string>",
      "suppressedPorts": [
        "<string>"
      ],
      "links": [
        "<StableWorkflowLink>"
      ],
      "reconciledPorts": "<StableWorkflowReconciledPorts>",
      "warnings": [
        "<StableWorkflowDiagnostic>"
      ]
    }
  ],
  "warnings": [
    {
      "code": "BRANCH_NOT_LAST",
      "detail": "<string>"
    }
  ],
  "truncated": {
    "blocks": 0,
    "returned": 0,
    "nextCursor": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Voiceflow bearer token

Path Parameters

workflowID

string

required

Query Parameters

projectID

string

required

The ID of the project to operate on.

environmentAlias

string

required

The alias of the environment to operate on (e.g. main).

cursor

string

The truncated.nextCursor of the previous page. Leave it out for the first page. Pages are counted on the workflow as it is at each call, so an edit between pages can repeat or skip a block.

Response

200 - application/json

Returns the workflow's name, description and counts, then a page of its blocks. When there are more blocks, truncated.nextCursor holds the value to send as cursor for the next page.

workflow

object

required

Show child attributes

string

required

name

string

required

description

string

required

counts

object

required

Show child attributes

blocks

integer

required

steps

integer

required

unreachableBlocks

integer

required

danglingLinks

integer

required

entry

object

required

Show child attributes

stepID

string

required

The start node.

name

string

required

string

required

The block the workflow starts in, or null. With actions, the block reached after the last action, or null when they end the path.

actions

object[]

The port actions the start runs before next, in run order. Absent when there are none.

Show child attributes

string

required

The action ID. Use it with the step operations to read, change or delete this action.

kind

object

required

What the step does. api, function, integration and mcp are Tool steps. playbook and operator are Agent steps. goToBlock jumps to a block or a workflow start and ends the path. callForward transfers a phone call and ends the path. legacy is a step these operations show but cannot change.

Available options: message, end, set, workflow, listen, condition, buttons, card, carousel, code, api, function, integration, mcp, playbook, operator, crew, handoff, legacy, goToBlock, callForward

content

object

required

The step's settings, shaped by its kind. A step these operations cannot show reads as readOnly.

Show child attributes

Option 1 · StableWorkflowStepMessageContent

Show child attributes

Option 1

object · 3 attributes: responseType, messageID, waitForUserResponse

Option 2

object · 3 attributes: responseType, promptID, waitForUserResponse

Option 2 · StableWorkflowStepEndContent

Show child attributes

Option 1

object · 3 attributes: responseType, messageID, responseEnabled

Option 2

object · 3 attributes: responseType, promptID, responseEnabled

Option 3 · StableWorkflowStepSetContent

Show child attributes

assignments

object[]

required

Show child attributes

Option 1

object · 5 attributes: id, type, variableID, label, value

Option 2

object · 5 attributes: id, type, variableID, label, promptID

parallelExecution

boolean

required

Whether the assignments run at the same time instead of in order.

transcriptProperties

object[]

required

object · 5 attributes: id, operationType, propertyID, label, value

Option 4 · StableWorkflowStepWorkflowContent

Show child attributes

targetWorkflowID

string

required

The workflow this step runs, by the ID the workflow list returns, or null.

targetWorkflowName

string

required

Read-only. The name of that workflow.

variableMap

object

required

object · 2 attributes: inputs, outputs

Option 5 · StableWorkflowStepListenContent

Show child attributes

variableID

string

required

The variable that receives the user's reply.

noReply

object

required

object · 3 attributes: enabled, repromptID, inactivityTime

listenForOtherTriggers

boolean

required

Option 6 · StableWorkflowStepConditionContent

Show child attributes

items

object[]

required

object · 4 attributes: id, label, matchAll, assertions

elsePath

boolean

required

Whether the else port is on: a reply that matches no branch leaves through it.

elseReprompt

object

required

object · 1 attribute: repromptID

Option 7 · StableWorkflowStepButtonsContent

Show child attributes

items

object[]

required

object · 4 attributes: id, label, url, openInNewTab

noMatch

object

required

object · 2 attributes: enabled, repromptID

noReply

object

required

object · 3 attributes: enabled, repromptID, inactivityTime

listenForOtherTriggers

boolean

required

Option 8 · StableWorkflowStepCardContent

Show child attributes

title

object

required

object · 0 attributes:

description

object

required

object · 0 attributes:

imageUrl

object

required

object · 0 attributes:

buttons

object[]

required

object · 4 attributes: id, label, url, openInNewTab

noMatch

object

required

object · 2 attributes: enabled, repromptID

noReply

object

required

object · 3 attributes: enabled, repromptID, inactivityTime

Option 9 · StableWorkflowStepCarouselContent

Show child attributes

layout

enum<string>

required

Available options: List, Carousel

cards

object[]

required

object · 5 attributes: id, title, description, imageUrl, buttons

noMatch

object

required

object · 2 attributes: enabled, repromptID

noReply

object

required

object · 3 attributes: enabled, repromptID, inactivityTime

Option 10 · StableWorkflowStepCodeContent

Show child attributes

code

object

required

object · 0 attributes:

paths

object[]

required

object · 2 attributes: id, label

fallback

boolean

required

Whether the fail port is on: an error in the code leaves through it.

Option 11 · StableWorkflowStepApiContent

Show child attributes

apiToolID

string

required

apiToolName

string

required

Read-only.

description

string

required

inputs

object[]

required

object · 6 attributes: id, description, defaultValue, apiToolInputVariableID, captureType, required

captureResponse

object[]

required

object · 4 attributes: id, path, variableOrEntityID, captureType

failPath

boolean

required

Whether the fail port is on: a failed call leaves through it.

asyncExecution

boolean

required

Read-only. When true, the path continues without waiting for the call to finish.

Option 12 · StableWorkflowStepFunctionContent

Show child attributes

functionID

string

required

functionName

string

required

Read-only.

paths

object[]

required

Read-only. The function's paths; each is also a port key of this step.

object · 2 attributes: id, label

description

string

required

inputs

object[]

required

object · 6 attributes: id, description, defaultValue, functionInputVariableID, captureType, required

captureResponse

object[]

required

object · 4 attributes: id, variableOrEntityID, functionOutputVariableID, captureType

failPath

boolean

required

Whether the fail port is on: a failed call leaves through it.

asyncExecution

boolean

required

Read-only. When true, the path continues without waiting for the call to finish.

Option 13 · StableWorkflowStepIntegrationContent

Show child attributes

integrationToolID

string

required

integrationToolName

string

required

Read-only.

description

string

required

inputs

object[]

required

object · 6 attributes: id, description, defaultValue, integrationToolVariableName, captureType, required

captureResponse

object[]

required

object · 4 attributes: id, path, variableOrEntityID, captureType

Option 14 · StableWorkflowStepMcpContent

Show child attributes

mcpToolID

string

required

mcpToolName

string

required

Read-only.

description

string

required

inputs

object[]

required

object · 6 attributes: id, description, defaultValue, mcpIntegrationVariableName, captureType, required

captureResponse

object[]

required

object · 4 attributes: id, path, variableOrEntityID, captureType

Option 15 · StableWorkflowStepOperatorContent

Show child attributes

agentID

string

required

agentName

string

required

Read-only.

paths

object[]

required

Read-only. The agent's paths; each is also a port key of this step.

object · 2 attributes: id, label

exitEveryConversationalTurn

boolean

required

listenForOtherTriggers

boolean

required

useAsRoutingAgent

boolean

required

Option 16 · StableWorkflowStepPlaybookContent

Show child attributes

agentID

string

required

agentName

string

required

Read-only.

paths

object[]

required

Read-only. The agent's paths; each is also a port key of this step.

object · 2 attributes: id, label

exitEveryConversationalTurn

boolean

required

listenForOtherTriggers

boolean

required

waitForUserResponse

boolean

required

Read-only. True: the step waits for the user to speak first. False: the Playbook talks first, the canvas default.

Option 17 · StableWorkflowStepCrewContent

Show child attributes

rootAgent

object

required

object · 4 attributes: agentID, description, condition, requiredVariables

subAgents

object[]

required

object · 4 attributes: agentID, description, condition, requiredVariables

subFlows

object[]

required

object · 4 attributes: flowID, description, condition, requiredVariables

exitPaths

object[]

required

object · 6 attributes: id, name, description, requiredVariables, messages, delayMessageSeconds

listenForOtherTriggers

boolean

required

waitForUserResponse

boolean

required

Option 18 · StableWorkflowStepHandoffContent

Show child attributes

config

object

required

object · 0 attributes:

handoffContext

object

required

object · 2 attributes: type, variableID

returnPath

boolean

required

Whether the step continues through its next port when the agent hands the conversation back.

failPath

boolean

required

Whether the step continues through its fail port when the handoff cannot start.

Option 19 · StableWorkflowStepGoToBlockContent

Show child attributes

targetWorkflowID

string

required

The workflow the path jumps to, by its workflow ID. It is this workflow when the target is in it. Null when that workflow no longer exists; the step then carries a GO_TO_TARGET_MISSING warning.

targetWorkflowName

string

required

Read-only. The name of that workflow.

targetBlockID

string

required

The block the path jumps to, or the target workflow's start step ID.

Option 20 · StableWorkflowStepCallForwardContent

Show child attributes

addressType

enum<string>

required

Whether address is a phone number or a SIP address.

Available options: phone, sip

address

object

required

Plain text; markdown is not interpreted. {variable_name} inserts a variable or entity, {variable_name.path} a field of a variable. Escape a literal { or \ with a backslash. A name matching neither is stored as literal text and reported in unresolvedReferences; secrets are not available here.

extension

object

required

object · 0 attributes:

callerIDPassthrough

boolean

required

Whether the forwarded call shows the caller's own number.

Option 21 · StableWorkflowStepReadOnlyContent

Show child attributes

readOnly

enum<boolean>

required

Available options: true

storedType

string

required

The stored step type.

reason

string

required

Why these operations do not show or change this step's content.

warnings

object[]

Show child attributes

code

object

required

Available options: BRANCH_NOT_LAST, TERMINAL_NOT_LAST, HIDDEN_LINK, UNREACHABLE_BLOCK, DANGLING_LINK, ORPHAN_STEP, GO_TO_TARGET_MISSING

detail

string

required

What is wrong, in one or two sentences, naming the step, block and port.

blocks

object[]

required

At most 50 blocks: breadth-first from the start, then blocks nothing reaches.

Show child attributes

string

required

name

string

required

inboundFrom

object[]

required

Every step port that links to this block.

Show child attributes

stepID

string

required

port

string

required

steps

object[]

required

The steps in the order they run.

Show child attributes

string

required

kind

object

required

StableWorkflowStepKind — see its attributes above

exitClass

object

required

How the step leaves. sequential: it continues to the step below it, or through next when it is last. branch: it leaves through one of its links, so it must be last. async-branch: a Card or Carousel, whose linked buttons run from any position. terminal: it ends the path.

Available options: sequential, branch, async-branch, terminal

content

object

required

The step's settings, shaped by its kind. A step these operations cannot show reads as readOnly.

StableWorkflowStepContent — see its attributes above

fallsThroughTo

string

required

When the step is not the last of its block: the step it continues to. Otherwise null.

suppressedPorts

string[]

required

Ports that run into the next step instead of their link, because the step is not last.

links

object[]

required

Show child attributes

port

string

required

The port key: next, else, fail, no-reply, conversation-turn, or the ID of a branch or path.

label

string

required

string

required

The block this port reaches. With actions, the block after the last action. Null when it points nowhere, or when its actions end the path.

actions

object[]

The port actions this exit runs, in order, before it reaches to.

StableWorkflowPortAction — see its attributes above

overridden

enum<boolean>

Present when this link does not run, because the step is not the last of its block.

Available options: true

effectiveTo

string

With overridden: the step that runs instead.

reconciledPorts

object

Show child attributes

added

string[]

required

Paths that exist on the agent or function but had no port on this step.

removed

string[]

required

Ports whose path no longer exists. They are not shown.

warnings

object[]

StableWorkflowDiagnostic — see its attributes above

orphanSteps

object[]

required

Steps that no block lists. They never run.

StableWorkflowStep — see its attributes above

warnings

object[]

required

StableWorkflowDiagnostic — see its attributes above

truncated

object

Present when more blocks follow. Send nextCursor as cursor to read the next page.

Show child attributes

blocks

integer

required

returned

integer

required

nextCursor

string

required

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks

Get workflow

Authorizations

Path Parameters

Query Parameters

Response

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks