Get playbook

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

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

import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>?projectID=<projectID>&environmentAlias=<environmentAlias>&includeInstructions=<includeInstructions>',
    headers={'Authorization': 'Bearer <token>'},
)
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
    },
    "instructionsLineCount": 0
  }
}

Get playbook

Returns a single playbook by ID, with the fields that define it. A playbook is a set of instructions that drives an agent toward a goal, calling tools as it needs them.

GET

/v1/stable/playbook/{playbookID}

Get playbook

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

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

import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>?projectID=<projectID>&environmentAlias=<environmentAlias>&includeInstructions=<includeInstructions>',
    headers={'Authorization': 'Bearer <token>'},
)
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
    },
    "instructionsLineCount": 0
  }
}

Authorizations

Authorization

string

header

required

Voiceflow bearer token

Path Parameters

playbookID

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

includeInstructions

boolean

default:false

Instructions can be tens of thousands of lines. Leave this off and use read_instructions to page through them only when you need the text.

Response

200 - application/json

Returns a single playbook, including its instructions, its tool ordering, and the system tool settings configured on it.

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

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.

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

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

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

callerIDPassthrough

boolean

knowledgeBaseTool

object

required

Show child attributes

query

object

Show child attributes

enabled

boolean

required

filters

object[]

Show child attributes

description

string

defaultValue

object

object · 0 attributes:

key

string

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

chunkLimit

number

description

string

required

queryMode

object

Show child attributes

sourceUrlsCount

number

instructionsLineCount

integer

required

How many lines the instructions have, so a caller can decide whether to page through them.

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks

Get playbook

Authorizations

Path Parameters

Query Parameters

Response

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks