Create playbook

curl --request POST \
  --url https://realtime-api.voiceflow.com/v1/stable/playbook \
  --header 'Authorization: Bearer <token>'
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "description": "<string>",
  "instructions": "<string>",
  "endTool": {
    "enabled": true,
    "messages": null,
    "toolSound": null,
    "description": "<string>"
  },
  "cardTool": {
    "enabled": true,
    "messages": null,
    "description": "<string>"
  },
  "buttonTool": {
    "enabled": true,
    "messages": null,
    "description": "<string>"
  },
  "carouselTool": {
    "enabled": true,
    "messages": null,
    "description": "<string>"
  },
  "skipTurnTool": {
    "enabled": true,
    "description": "<string>"
  },
  "webSearchTool": {
    "enabled": true,
    "messages": null,
    "toolSound": null,
    "description": "<string>",
    "allowedDomains": [
      "<string>"
    ],
    "sourceUrlsCount": 0
  },
  "callForwardTool": {
    "enabled": true,
    "address": [
      "<string>"
    ],
    "messages": null,
    "extension": "<Markup>",
    "toolSound": null,
    "description": "<string>",
    "addressType": "phone",
    "callerIDPassthrough": true
  },
  "knowledgeBaseTool": {
    "query": "<Markup>",
    "enabled": true,
    "filters": [
      "<AgentKnowledgeBaseMetadataKeyFilter>"
    ],
    "messages": null,
    "toolSound": null,
    "chunkLimit": 0,
    "description": "<string>",
    "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
    "sourceUrlsCount": 0
  },
  "settings": {}
}'

const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/playbook?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "<string>",
    "description": "<string>",
    "instructions": "<string>",
    "endTool": {
      "enabled": true,
      "messages": null,
      "toolSound": null,
      "description": "<string>"
    },
    "cardTool": {
      "enabled": true,
      "messages": null,
      "description": "<string>"
    },
    "buttonTool": {
      "enabled": true,
      "messages": null,
      "description": "<string>"
    },
    "carouselTool": {
      "enabled": true,
      "messages": null,
      "description": "<string>"
    },
    "skipTurnTool": {
      "enabled": true,
      "description": "<string>"
    },
    "webSearchTool": {
      "enabled": true,
      "messages": null,
      "toolSound": null,
      "description": "<string>",
      "allowedDomains": [
        "<string>"
      ],
      "sourceUrlsCount": 0
    },
    "callForwardTool": {
      "enabled": true,
      "address": [
        "<string>"
      ],
      "messages": null,
      "extension": "<Markup>",
      "toolSound": null,
      "description": "<string>",
      "addressType": "phone",
      "callerIDPassthrough": true
    },
    "knowledgeBaseTool": {
      "query": "<Markup>",
      "enabled": true,
      "filters": [
        "<AgentKnowledgeBaseMetadataKeyFilter>"
      ],
      "messages": null,
      "toolSound": null,
      "chunkLimit": 0,
      "description": "<string>",
      "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
      "sourceUrlsCount": 0
    },
    "settings": {}
  }),
});
const data = await response.json();

import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/playbook?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "name": "<string>",
      "description": "<string>",
      "instructions": "<string>",
      "endTool": {
        "enabled": True,
        "messages": None,
        "toolSound": None,
        "description": "<string>"
      },
      "cardTool": {
        "enabled": True,
        "messages": None,
        "description": "<string>"
      },
      "buttonTool": {
        "enabled": True,
        "messages": None,
        "description": "<string>"
      },
      "carouselTool": {
        "enabled": True,
        "messages": None,
        "description": "<string>"
      },
      "skipTurnTool": {
        "enabled": True,
        "description": "<string>"
      },
      "webSearchTool": {
        "enabled": True,
        "messages": None,
        "toolSound": None,
        "description": "<string>",
        "allowedDomains": [
          "<string>"
        ],
        "sourceUrlsCount": 0
      },
      "callForwardTool": {
        "enabled": True,
        "address": [
          "<string>"
        ],
        "messages": None,
        "extension": "<Markup>",
        "toolSound": None,
        "description": "<string>",
        "addressType": "phone",
        "callerIDPassthrough": True
      },
      "knowledgeBaseTool": {
        "query": "<Markup>",
        "enabled": True,
        "filters": [
          "<AgentKnowledgeBaseMetadataKeyFilter>"
        ],
        "messages": None,
        "toolSound": None,
        "chunkLimit": 0,
        "description": "<string>",
        "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
        "sourceUrlsCount": 0
      },
      "settings": {}
    },
)
data = response.json()

{
  "playbook": {
    "id": "<string>",
    "name": "<string>",
    "settings": {
      "model": "<AIModel>",
      "realtime": {
        "voice": "<string>",
        "eagerness": "<string>"
      },
      "maxTokens": 0,
      "temperature": 0,
      "reasoningEffort": "<AIReasoningEffort>"
    },
    "createdAt": "2026-09-10T00:00:00.000Z",
    "updatedAt": "2026-09-10T00:00:00.000Z",
    "description": "<string>",
    "instructions": "<string>",
    "pathToolOrder": [
      "<string>"
    ],
    "endTool": {
      "enabled": true,
      "messages": null,
      "toolSound": null,
      "description": "<string>"
    },
    "cardTool": {
      "enabled": true,
      "messages": null,
      "description": "<string>"
    },
    "buttonTool": {
      "enabled": true,
      "messages": null,
      "description": "<string>"
    },
    "carouselTool": {
      "enabled": true,
      "messages": null,
      "description": "<string>"
    },
    "skipTurnTool": {
      "enabled": true,
      "description": "<string>"
    },
    "webSearchTool": {
      "enabled": true,
      "messages": null,
      "toolSound": null,
      "description": "<string>",
      "allowedDomains": [
        "<string>"
      ],
      "sourceUrlsCount": 0
    },
    "callForwardTool": {
      "enabled": true,
      "address": "<Markup>",
      "messages": null,
      "extension": "<Markup>",
      "toolSound": null,
      "description": "<string>",
      "addressType": "<CallForwardAddressType>",
      "callerIDPassthrough": true
    },
    "knowledgeBaseTool": {
      "query": "<Markup>",
      "enabled": true,
      "filters": [
        "<AgentKnowledgeBaseMetadataKeyFilter>"
      ],
      "messages": null,
      "toolSound": null,
      "chunkLimit": 0,
      "description": "<string>",
      "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
      "sourceUrlsCount": 0
    }
  },
  "unresolvedReferences": "<string>"
}

Create playbook

Adds a playbook to the environment, a set of instructions that drives an agent toward a goal, calling tools as it needs them. The response carries the ID that later calls address it by.

POST

/v1/stable/playbook

Create playbook

curl --request POST \
  --url https://realtime-api.voiceflow.com/v1/stable/playbook \
  --header 'Authorization: Bearer <token>'
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "description": "<string>",
  "instructions": "<string>",
  "endTool": {
    "enabled": true,
    "messages": null,
    "toolSound": null,
    "description": "<string>"
  },
  "cardTool": {
    "enabled": true,
    "messages": null,
    "description": "<string>"
  },
  "buttonTool": {
    "enabled": true,
    "messages": null,
    "description": "<string>"
  },
  "carouselTool": {
    "enabled": true,
    "messages": null,
    "description": "<string>"
  },
  "skipTurnTool": {
    "enabled": true,
    "description": "<string>"
  },
  "webSearchTool": {
    "enabled": true,
    "messages": null,
    "toolSound": null,
    "description": "<string>",
    "allowedDomains": [
      "<string>"
    ],
    "sourceUrlsCount": 0
  },
  "callForwardTool": {
    "enabled": true,
    "address": [
      "<string>"
    ],
    "messages": null,
    "extension": "<Markup>",
    "toolSound": null,
    "description": "<string>",
    "addressType": "phone",
    "callerIDPassthrough": true
  },
  "knowledgeBaseTool": {
    "query": "<Markup>",
    "enabled": true,
    "filters": [
      "<AgentKnowledgeBaseMetadataKeyFilter>"
    ],
    "messages": null,
    "toolSound": null,
    "chunkLimit": 0,
    "description": "<string>",
    "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
    "sourceUrlsCount": 0
  },
  "settings": {}
}'

const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/playbook?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "<string>",
    "description": "<string>",
    "instructions": "<string>",
    "endTool": {
      "enabled": true,
      "messages": null,
      "toolSound": null,
      "description": "<string>"
    },
    "cardTool": {
      "enabled": true,
      "messages": null,
      "description": "<string>"
    },
    "buttonTool": {
      "enabled": true,
      "messages": null,
      "description": "<string>"
    },
    "carouselTool": {
      "enabled": true,
      "messages": null,
      "description": "<string>"
    },
    "skipTurnTool": {
      "enabled": true,
      "description": "<string>"
    },
    "webSearchTool": {
      "enabled": true,
      "messages": null,
      "toolSound": null,
      "description": "<string>",
      "allowedDomains": [
        "<string>"
      ],
      "sourceUrlsCount": 0
    },
    "callForwardTool": {
      "enabled": true,
      "address": [
        "<string>"
      ],
      "messages": null,
      "extension": "<Markup>",
      "toolSound": null,
      "description": "<string>",
      "addressType": "phone",
      "callerIDPassthrough": true
    },
    "knowledgeBaseTool": {
      "query": "<Markup>",
      "enabled": true,
      "filters": [
        "<AgentKnowledgeBaseMetadataKeyFilter>"
      ],
      "messages": null,
      "toolSound": null,
      "chunkLimit": 0,
      "description": "<string>",
      "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
      "sourceUrlsCount": 0
    },
    "settings": {}
  }),
});
const data = await response.json();

import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/playbook?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "name": "<string>",
      "description": "<string>",
      "instructions": "<string>",
      "endTool": {
        "enabled": True,
        "messages": None,
        "toolSound": None,
        "description": "<string>"
      },
      "cardTool": {
        "enabled": True,
        "messages": None,
        "description": "<string>"
      },
      "buttonTool": {
        "enabled": True,
        "messages": None,
        "description": "<string>"
      },
      "carouselTool": {
        "enabled": True,
        "messages": None,
        "description": "<string>"
      },
      "skipTurnTool": {
        "enabled": True,
        "description": "<string>"
      },
      "webSearchTool": {
        "enabled": True,
        "messages": None,
        "toolSound": None,
        "description": "<string>",
        "allowedDomains": [
          "<string>"
        ],
        "sourceUrlsCount": 0
      },
      "callForwardTool": {
        "enabled": True,
        "address": [
          "<string>"
        ],
        "messages": None,
        "extension": "<Markup>",
        "toolSound": None,
        "description": "<string>",
        "addressType": "phone",
        "callerIDPassthrough": True
      },
      "knowledgeBaseTool": {
        "query": "<Markup>",
        "enabled": True,
        "filters": [
          "<AgentKnowledgeBaseMetadataKeyFilter>"
        ],
        "messages": None,
        "toolSound": None,
        "chunkLimit": 0,
        "description": "<string>",
        "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
        "sourceUrlsCount": 0
      },
      "settings": {}
    },
)
data = response.json()

{
  "playbook": {
    "id": "<string>",
    "name": "<string>",
    "settings": {
      "model": "<AIModel>",
      "realtime": {
        "voice": "<string>",
        "eagerness": "<string>"
      },
      "maxTokens": 0,
      "temperature": 0,
      "reasoningEffort": "<AIReasoningEffort>"
    },
    "createdAt": "2026-09-10T00:00:00.000Z",
    "updatedAt": "2026-09-10T00:00:00.000Z",
    "description": "<string>",
    "instructions": "<string>",
    "pathToolOrder": [
      "<string>"
    ],
    "endTool": {
      "enabled": true,
      "messages": null,
      "toolSound": null,
      "description": "<string>"
    },
    "cardTool": {
      "enabled": true,
      "messages": null,
      "description": "<string>"
    },
    "buttonTool": {
      "enabled": true,
      "messages": null,
      "description": "<string>"
    },
    "carouselTool": {
      "enabled": true,
      "messages": null,
      "description": "<string>"
    },
    "skipTurnTool": {
      "enabled": true,
      "description": "<string>"
    },
    "webSearchTool": {
      "enabled": true,
      "messages": null,
      "toolSound": null,
      "description": "<string>",
      "allowedDomains": [
        "<string>"
      ],
      "sourceUrlsCount": 0
    },
    "callForwardTool": {
      "enabled": true,
      "address": "<Markup>",
      "messages": null,
      "extension": "<Markup>",
      "toolSound": null,
      "description": "<string>",
      "addressType": "<CallForwardAddressType>",
      "callerIDPassthrough": true
    },
    "knowledgeBaseTool": {
      "query": "<Markup>",
      "enabled": true,
      "filters": [
        "<AgentKnowledgeBaseMetadataKeyFilter>"
      ],
      "messages": null,
      "toolSound": null,
      "chunkLimit": 0,
      "description": "<string>",
      "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
      "sourceUrlsCount": 0
    }
  },
  "unresolvedReferences": "<string>"
}

Authorizations

Authorization

string

header

required

Voiceflow bearer token

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).

Body

name

string

required

description

string

A human-readable description of what the playbook does.

instructions

string

Markdown text. Backticked Name resolves to a tool, playbook, or workflow reference; braced {name} resolves to a variable or entity reference. Tokens that do not resolve are stored as literal text and reported back in the response.

endTool

object

Show child attributes

enabled

boolean

required

messages

object

Show child attributes

generative

object

Show child attributes

delay

object

object · 2 attributes: enabled, examples

failure

object

object · 2 attributes: enabled, examples

execution

object

object · 2 attributes: enabled, examples

completion

object

object · 2 attributes: enabled, examples

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

toolSound

object

Show child attributes

ref

string

required

volume

number

default:0.75

description

string

required

cardTool

object

Show child attributes

enabled

boolean

required

messages

object

Show child attributes

generative

object

Show child attributes

delay

object

object · 2 attributes: enabled, examples

failure

object

object · 2 attributes: enabled, examples

execution

object

object · 2 attributes: enabled, examples

completion

object

object · 2 attributes: enabled, examples

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

description

string

required

buttonTool

object

Show child attributes

enabled

boolean

required

messages

object

Show child attributes

generative

object

Show child attributes

delay

object

object · 2 attributes: enabled, examples

failure

object

object · 2 attributes: enabled, examples

execution

object

object · 2 attributes: enabled, examples

completion

object

object · 2 attributes: enabled, examples

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

description

string

required

carouselTool

object

Show child attributes

enabled

boolean

required

messages

object

Show child attributes

generative

object

Show child attributes

delay

object

object · 2 attributes: enabled, examples

failure

object

object · 2 attributes: enabled, examples

execution

object

object · 2 attributes: enabled, examples

completion

object

object · 2 attributes: enabled, examples

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

description

string

required

skipTurnTool

object

Show child attributes

enabled

boolean

required

description

string

required

webSearchTool

object

Show child attributes

enabled

boolean

required

messages

object

Show child attributes

generative

object

Show child attributes

delay

object

object · 2 attributes: enabled, examples

failure

object

object · 2 attributes: enabled, examples

execution

object

object · 2 attributes: enabled, examples

completion

object

object · 2 attributes: enabled, examples

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

toolSound

object

Show child attributes

ref

string

required

volume

number

default:0.75

description

string

allowedDomains

string[]

sourceUrlsCount

number

callForwardTool

object

Show child attributes

enabled

boolean

required

address

object

required

Show child attributes

Option 1

string

Option 2 · MarkupSpan

Show child attributes

text

object

required

Markup (see above)

Markup — see its attributes above

attributes

object

Option 3 · MarkupToolReference

Show child attributes

resourceID

string

required

referenceType

object

required

Available options: function, api-call, integration, mcp-integration, flow, agent, path-tool, system-tool

Option 4 · MarkupSecretReference

Show child attributes

secretID

string

required

Option 5 · MarkupEntityReference

Show child attributes

entityID

string

required

Option 6 · MarkupVariableReference

Show child attributes

variableID

string

required

path

string

messages

object

Show child attributes

generative

object

Show child attributes

delay

object

object · 2 attributes: enabled, examples

failure

object

object · 2 attributes: enabled, examples

execution

object

object · 2 attributes: enabled, examples

completion

object

object · 2 attributes: enabled, examples

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

extension

object

Show child attributes

toolSound

object

Show child attributes

ref

string

required

volume

number

default:0.75

description

string

required

addressType

object

required

Available options: phone, sip

callerIDPassthrough

boolean

knowledgeBaseTool

object

Show child attributes

query

object

Show child attributes

enabled

boolean

required

filters

object[]

Show child attributes

description

string

defaultValue

object

Show child attributes

key

string

required

messages

object

Show child attributes

generative

object

Show child attributes

delay

object

object · 2 attributes: enabled, examples

failure

object

object · 2 attributes: enabled, examples

execution

object

object · 2 attributes: enabled, examples

completion

object

object · 2 attributes: enabled, examples

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

toolSound

object

Show child attributes

ref

string

required

volume

number

default:0.75

chunkLimit

number

description

string

required

queryMode

object

Show child attributes

sourceUrlsCount

number

settings

object

Show child attributes

model

object

Show child attributes

realtime

object

Show child attributes

voice

string

eagerness

string

maxTokens

number

temperature

number

reasoningEffort

object

Show child attributes

Response

201 - application/json

Returns the newly created playbook in full, including the ID assigned to it and the instructions it was created with.

playbook

object

required

Show child attributes

string

required

name

string

required

settings

object

required

Show child attributes

model

object

Show child attributes

realtime

object

Show child attributes

voice

string

eagerness

string

maxTokens

number

temperature

number

reasoningEffort

object

Show child attributes

createdAt

string

required

updatedAt

string

required

description

string

required

A human-readable description of what the playbook does.

instructions

string

required

pathToolOrder

string[]

required

The IDs of the playbook's path tools, in display order.

endTool

object

required

Show child attributes

enabled

boolean

required

messages

object

Show child attributes

generative

object

object · 4 attributes: delay, failure, execution, completion

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

toolSound

object

Show child attributes

ref

string

required

volume

number

default:0.75

description

string

required

cardTool

object

required

Show child attributes

enabled

boolean

required

messages

object

Show child attributes

generative

object

object · 4 attributes: delay, failure, execution, completion

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

description

string

required

buttonTool

object

required

Show child attributes

enabled

boolean

required

messages

object

Show child attributes

generative

object

object · 4 attributes: delay, failure, execution, completion

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

description

string

required

carouselTool

object

required

Show child attributes

enabled

boolean

required

messages

object

Show child attributes

generative

object

object · 4 attributes: delay, failure, execution, completion

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

description

string

required

skipTurnTool

object

required

Show child attributes

enabled

boolean

required

description

string

required

webSearchTool

object

required

Show child attributes

enabled

boolean

required

messages

object

Show child attributes

generative

object

object · 4 attributes: delay, failure, execution, completion

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

toolSound

object

Show child attributes

ref

string

required

volume

number

default:0.75

description

string

allowedDomains

string[]

sourceUrlsCount

number

callForwardTool

object

required

Show child attributes

enabled

boolean

required

address

object

required

Markup — see its attributes above

messages

object

Show child attributes

generative

object

object · 4 attributes: delay, failure, execution, completion

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

extension

object

Show child attributes

toolSound

object

Show child attributes

ref

string

required

volume

number

default:0.75

description

string

required

addressType

object

required

Available options: phone, sip

CallForwardAddressType — see its attributes above

callerIDPassthrough

boolean

knowledgeBaseTool

object

required

Show child attributes

query

object

Show child attributes

enabled

boolean

required

filters

object[]

AgentKnowledgeBaseMetadataKeyFilter — see its attributes above

messages

object

Show child attributes

generative

object

object · 4 attributes: delay, failure, execution, completion

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

toolSound

object

Show child attributes

ref

string

required

volume

number

default:0.75

chunkLimit

number

description

string

required

queryMode

object

Show child attributes

sourceUrlsCount

number

unresolvedReferences

string

Advisory naming any references in the submitted markdown that did not resolve.

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks

Create playbook

Authorizations

Query Parameters

Body

Response

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks