> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Playbooks

API operations for playbooks. Browse the routes below for parameters, request examples, and responses.

API version: Selected per operation

## List playbooks

Returns every playbook in the environment. A playbook is a set of instructions that drives an agent toward a goal, calling tools as it needs them. The call takes no paging parameters, so one request yields the whole set, with each playbook's instructions as a plain Markdown string.

### Endpoint

```http
GET /v2/stable/playbook
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `includeInstructions`

Optional · boolean

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.

```json
{
  "default": false,
  "description": "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.",
  "type": "boolean"
}
```

### Responses

#### 200

Returns every playbook in the project environment, each with its name, description, instructions, model settings, and its own system tool configuration.

Schema:

```json
{
  "$ref": "#/components/schemas/StablePlaybookReadListResponseV2"
}
```

Example:

```json
{
  "playbooks": [
    {
      "id": "<string>",
      "name": "<string>",
      "settings": {
        "model": "<AIModel>",
        "realtime": {
          "voice": "<string>",
          "eagerness": "<string>"
        },
        "maxTokens": 0,
        "temperature": 0,
        "reasoningEffort": "<AIReasoningEffort>",
        "serviceTier": "<AIParamsServiceTier>"
      },
      "createdAt": "2026-09-10T00:00:00.000Z",
      "updatedAt": "2026-09-10T00:00:00.000Z",
      "description": "<string>",
      "instructions": "<MarkdownText>",
      "pathToolOrder": [
        "<string>"
      ],
      "endTool": "<StableEndTool>",
      "cardTool": "<StableCardTool>",
      "buttonTool": "<StableButtonTool>",
      "carouselTool": "<StableCardTool>",
      "webSearchTool": "<StableWebSearchTool>",
      "callForwardTool": "<StableCallForwardTool>",
      "knowledgeBaseTool": "<StableKnowledgeBaseTool>",
      "skipTurnTool": "<AgentSkipTurnTool>",
      "instructionsLineCount": 0
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v2/stable/playbook?projectID=<projectID>&environmentAlias=<environmentAlias>&includeInstructions=<includeInstructions>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

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

#### Python

```python
import requests

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

#### Voiceflow CLI

```bash
vf playbook list --project-id <projectID> --environment-alias <environmentAlias> --include-instructions <includeInstructions>
```


## 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 instructions are sent as a plain Markdown string, and the response carries the ID that later calls address the playbook by.

### Endpoint

```http
POST /v2/stable/playbook
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StablePlaybookCreateRequestV2"
      }
    }
  }
}
```

### Responses

#### 201

Returns the newly created playbook in full, including the ID assigned to it, and lists any references or mentions in its text that did not resolve.

Schema:

```json
{
  "$ref": "#/components/schemas/StablePlaybookResponseV2"
}
```

Example:

```json
{
  "playbook": {
    "id": "<string>",
    "name": "<string>",
    "settings": {
      "model": "<AIModel>",
      "realtime": {
        "voice": "<string>",
        "eagerness": "<string>"
      },
      "maxTokens": 0,
      "temperature": 0,
      "reasoningEffort": "<AIReasoningEffort>",
      "serviceTier": "<AIParamsServiceTier>"
    },
    "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>"
    },
    "webSearchTool": {
      "enabled": true,
      "messages": null,
      "toolSound": null,
      "description": "<string>",
      "allowedDomains": [
        "<string>"
      ],
      "sourceUrlsCount": 0
    },
    "callForwardTool": {
      "enabled": true,
      "address": "<VariableReferenceString>",
      "messages": null,
      "extension": "<VariableReferenceString>",
      "toolSound": null,
      "description": "<string>",
      "addressType": "<CallForwardAddressType>",
      "callerIDPassthrough": true
    },
    "knowledgeBaseTool": {
      "query": "<VariableReferenceString>",
      "enabled": true,
      "filters": [
        "<StableKBFilter>"
      ],
      "messages": null,
      "toolSound": null,
      "chunkLimit": 0,
      "description": "<string>",
      "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
      "sourceUrlsCount": 0
    },
    "skipTurnTool": {
      "enabled": true,
      "description": "<string>"
    }
  },
  "unresolvedReferences": [
    {
      "path": "<string>",
      "token": "<string>",
      "reason": "unknown"
    }
  ],
  "unresolvedMentions": [
    {
      "path": "<string>",
      "mention": "<string>"
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v2/stable/playbook?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --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": "<VariableReferenceString>",
    "toolSound": null,
    "description": "<string>",
    "addressType": "phone",
    "callerIDPassthrough": true
  },
  "knowledgeBaseTool": {
    "query": "<VariableReferenceString>",
    "enabled": true,
    "filters": [
      "<StableKBFilter>"
    ],
    "messages": null,
    "toolSound": null,
    "chunkLimit": 0,
    "description": "<string>",
    "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
    "sourceUrlsCount": 0
  },
  "settings": {}
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/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": "<VariableReferenceString>",
      "toolSound": null,
      "description": "<string>",
      "addressType": "phone",
      "callerIDPassthrough": true
    },
    "knowledgeBaseTool": {
      "query": "<VariableReferenceString>",
      "enabled": true,
      "filters": [
        "<StableKBFilter>"
      ],
      "messages": null,
      "toolSound": null,
      "chunkLimit": 0,
      "description": "<string>",
      "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
      "sourceUrlsCount": 0
    },
    "settings": {}
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v2/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": "<VariableReferenceString>",
        "toolSound": None,
        "description": "<string>",
        "addressType": "phone",
        "callerIDPassthrough": True
      },
      "knowledgeBaseTool": {
        "query": "<VariableReferenceString>",
        "enabled": True,
        "filters": [
          "<StableKBFilter>"
        ],
        "messages": None,
        "toolSound": None,
        "chunkLimit": 0,
        "description": "<string>",
        "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
        "sourceUrlsCount": 0
      },
      "settings": {}
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf playbook create --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "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": "<VariableReferenceString>",
    "toolSound": null,
    "description": "<string>",
    "addressType": "phone",
    "callerIDPassthrough": true
  },
  "knowledgeBaseTool": {
    "query": "<VariableReferenceString>",
    "enabled": true,
    "filters": [
      "<StableKBFilter>"
    ],
    "messages": null,
    "toolSound": null,
    "chunkLimit": 0,
    "description": "<string>",
    "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
    "sourceUrlsCount": 0
  },
  "settings": {}
}
JSON
```


## Create many playbooks

Adds several playbooks to the environment in one request, each taking the fields the single-create call takes. The response carries the created playbooks in the same shape the list call returns.

### Endpoint

```http
POST /v2/stable/playbook/batch
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StablePlaybookCreateManyRequestV2"
      }
    }
  }
}
```

### Responses

#### 201

Returns the playbooks the request created, as an array, each complete with the ID assigned to it, and lists any references or mentions in their text that did not resolve.

Schema:

```json
{
  "$ref": "#/components/schemas/StablePlaybookListResponseV2"
}
```

Example:

```json
{
  "playbooks": [
    {
      "id": "<string>",
      "name": "<string>",
      "settings": {
        "model": "<AIModel>",
        "realtime": {
          "voice": "<string>",
          "eagerness": "<string>"
        },
        "maxTokens": 0,
        "temperature": 0,
        "reasoningEffort": "<AIReasoningEffort>",
        "serviceTier": "<AIParamsServiceTier>"
      },
      "createdAt": "2026-09-10T00:00:00.000Z",
      "updatedAt": "2026-09-10T00:00:00.000Z",
      "description": "<string>",
      "instructions": "<MarkdownText>",
      "pathToolOrder": [
        "<string>"
      ],
      "endTool": "<StableEndTool>",
      "cardTool": "<StableCardTool>",
      "buttonTool": "<StableButtonTool>",
      "carouselTool": "<StableCardTool>",
      "webSearchTool": "<StableWebSearchTool>",
      "callForwardTool": "<StableCallForwardTool>",
      "knowledgeBaseTool": "<StableKnowledgeBaseTool>",
      "skipTurnTool": "<AgentSkipTurnTool>"
    }
  ],
  "unresolvedReferences": [
    {
      "path": "<string>",
      "token": "<string>",
      "reason": "unknown"
    }
  ],
  "unresolvedMentions": [
    {
      "path": "<string>",
      "mention": "<string>"
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v2/stable/playbook/batch?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "playbooks": [
    {
      "name": "<string>",
      "description": "<string>",
      "instructions": "<MarkdownText>",
      "endTool": "<StableEndTool>",
      "cardTool": "<StableCardTool>",
      "buttonTool": "<StableButtonTool>",
      "carouselTool": "<StableCardTool>",
      "skipTurnTool": "<AgentSkipTurnTool>",
      "webSearchTool": "<StableWebSearchTool>",
      "callForwardTool": "<StableCallForwardTool>",
      "knowledgeBaseTool": "<StableKnowledgeBaseTool>",
      "settings": {}
    }
  ]
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/stable/playbook/batch?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "playbooks": [
      {
        "name": "<string>",
        "description": "<string>",
        "instructions": "<MarkdownText>",
        "endTool": "<StableEndTool>",
        "cardTool": "<StableCardTool>",
        "buttonTool": "<StableButtonTool>",
        "carouselTool": "<StableCardTool>",
        "skipTurnTool": "<AgentSkipTurnTool>",
        "webSearchTool": "<StableWebSearchTool>",
        "callForwardTool": "<StableCallForwardTool>",
        "knowledgeBaseTool": "<StableKnowledgeBaseTool>",
        "settings": {}
      }
    ]
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v2/stable/playbook/batch?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "playbooks": [
        {
          "name": "<string>",
          "description": "<string>",
          "instructions": "<MarkdownText>",
          "endTool": "<StableEndTool>",
          "cardTool": "<StableCardTool>",
          "buttonTool": "<StableButtonTool>",
          "carouselTool": "<StableCardTool>",
          "skipTurnTool": "<AgentSkipTurnTool>",
          "webSearchTool": "<StableWebSearchTool>",
          "callForwardTool": "<StableCallForwardTool>",
          "knowledgeBaseTool": "<StableKnowledgeBaseTool>",
          "settings": {}
        }
      ]
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf playbook create-many --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "playbooks": [
    {
      "name": "<string>",
      "description": "<string>",
      "instructions": "<MarkdownText>",
      "endTool": "<StableEndTool>",
      "cardTool": "<StableCardTool>",
      "buttonTool": "<StableButtonTool>",
      "carouselTool": "<StableCardTool>",
      "skipTurnTool": "<AgentSkipTurnTool>",
      "webSearchTool": "<StableWebSearchTool>",
      "callForwardTool": "<StableCallForwardTool>",
      "knowledgeBaseTool": "<StableKnowledgeBaseTool>",
      "settings": {}
    }
  ]
}
JSON
```


## Delete playbook

Deletes a single playbook by ID. A playbook is a set of instructions that drives an agent toward a goal, calling tools as it needs them. The response carries only a confirmation message, so refetch the playbooks to see what is left.

### Endpoint

```http
DELETE /v1/stable/playbook/{playbookID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `playbookID`

Required · string

The ID of the playbook to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Responses

#### 200

Confirms the playbook was deleted from the project environment. The body is a message only, so list the playbooks again to see which remain.

Schema:

```json
{
  "$ref": "#/components/schemas/StableDeleteResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request DELETE \
  --url 'https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

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

#### Python

```python
import requests

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

#### Voiceflow CLI

```bash
vf playbook delete --playbook-id <playbookID> --project-id <projectID> --environment-alias <environmentAlias>
```


## 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, and its instructions come back as a plain Markdown string.

### Endpoint

```http
GET /v2/stable/playbook/{playbookID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `playbookID`

Required · string

The ID of the playbook to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `includeInstructions`

Optional · boolean

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.

```json
{
  "default": false,
  "description": "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.",
  "type": "boolean"
}
```

### Responses

#### 200

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

Schema:

```json
{
  "$ref": "#/components/schemas/StablePlaybookReadResponseV2"
}
```

Example:

```json
{
  "playbook": {
    "id": "<string>",
    "name": "<string>",
    "settings": {
      "model": "<AIModel>",
      "realtime": {
        "voice": "<string>",
        "eagerness": "<string>"
      },
      "maxTokens": 0,
      "temperature": 0,
      "reasoningEffort": "<AIReasoningEffort>",
      "serviceTier": "<AIParamsServiceTier>"
    },
    "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>"
    },
    "webSearchTool": {
      "enabled": true,
      "messages": null,
      "toolSound": null,
      "description": "<string>",
      "allowedDomains": [
        "<string>"
      ],
      "sourceUrlsCount": 0
    },
    "callForwardTool": {
      "enabled": true,
      "address": "<VariableReferenceString>",
      "messages": null,
      "extension": "<VariableReferenceString>",
      "toolSound": null,
      "description": "<string>",
      "addressType": "<CallForwardAddressType>",
      "callerIDPassthrough": true
    },
    "knowledgeBaseTool": {
      "query": "<VariableReferenceString>",
      "enabled": true,
      "filters": [
        "<StableKBFilter>"
      ],
      "messages": null,
      "toolSound": null,
      "chunkLimit": 0,
      "description": "<string>",
      "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
      "sourceUrlsCount": 0
    },
    "skipTurnTool": {
      "enabled": true,
      "description": "<string>"
    },
    "instructionsLineCount": 0
  }
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v2/stable/playbook/<playbookID>?projectID=<projectID>&environmentAlias=<environmentAlias>&includeInstructions=<includeInstructions>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

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

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v2/stable/playbook/<playbookID>?projectID=<projectID>&environmentAlias=<environmentAlias>&includeInstructions=<includeInstructions>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf playbook get --playbook-id <playbookID> --project-id <projectID> --environment-alias <environmentAlias> --include-instructions <includeInstructions>
```


## Update playbook

Changes an existing playbook in place, with its instructions sent as a plain Markdown string. The response lists any references or mentions that did not resolve; read the playbook again to see its new values.

### Endpoint

```http
PATCH /v2/stable/playbook/{playbookID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `playbookID`

Required · string

The ID of the playbook to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/StablePlaybookUpdateRequestV2"
          }
        ]
      }
    }
  }
}
```

### Responses

#### 200

Confirms the playbook was updated, and lists any references or mentions in the new text that did not resolve. The response is a message, not the revised playbook, so fetch it again to read back what changed.

Schema:

```json
{
  "$ref": "#/components/schemas/StableMarkdownUpdateResponse"
}
```

Example:

```json
{
  "message": "<string>",
  "unresolvedReferences": [
    {
      "path": "<string>",
      "token": "<string>",
      "reason": "unknown"
    }
  ],
  "unresolvedMentions": [
    {
      "path": "<string>",
      "mention": "<string>"
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request PATCH \
  --url 'https://realtime-api.voiceflow.com/v2/stable/playbook/<playbookID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "settings": {
    "model": "<AIModel>",
    "realtime": {
      "voice": "<string>",
      "eagerness": "<string>"
    },
    "maxTokens": 0,
    "temperature": 0,
    "reasoningEffort": "<AIReasoningEffort>",
    "serviceTier": "<AIParamsServiceTier>"
  },
  "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": "<VariableReferenceString>",
    "messages": null,
    "extension": "<VariableReferenceString>",
    "toolSound": null,
    "description": "<string>",
    "addressType": "<CallForwardAddressType>",
    "callerIDPassthrough": true
  },
  "knowledgeBaseTool": {
    "query": "<VariableReferenceString>",
    "enabled": true,
    "filters": [
      "<StableKBFilter>"
    ],
    "messages": null,
    "toolSound": null,
    "chunkLimit": 0,
    "description": "<string>",
    "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
    "sourceUrlsCount": 0
  }
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/stable/playbook/<playbookID>?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "<string>",
    "settings": {
      "model": "<AIModel>",
      "realtime": {
        "voice": "<string>",
        "eagerness": "<string>"
      },
      "maxTokens": 0,
      "temperature": 0,
      "reasoningEffort": "<AIReasoningEffort>",
      "serviceTier": "<AIParamsServiceTier>"
    },
    "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": "<VariableReferenceString>",
      "messages": null,
      "extension": "<VariableReferenceString>",
      "toolSound": null,
      "description": "<string>",
      "addressType": "<CallForwardAddressType>",
      "callerIDPassthrough": true
    },
    "knowledgeBaseTool": {
      "query": "<VariableReferenceString>",
      "enabled": true,
      "filters": [
        "<StableKBFilter>"
      ],
      "messages": null,
      "toolSound": null,
      "chunkLimit": 0,
      "description": "<string>",
      "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
      "sourceUrlsCount": 0
    }
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.patch(
    'https://realtime-api.voiceflow.com/v2/stable/playbook/<playbookID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "name": "<string>",
      "settings": {
        "model": "<AIModel>",
        "realtime": {
          "voice": "<string>",
          "eagerness": "<string>"
        },
        "maxTokens": 0,
        "temperature": 0,
        "reasoningEffort": "<AIReasoningEffort>",
        "serviceTier": "<AIParamsServiceTier>"
      },
      "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": "<VariableReferenceString>",
        "messages": None,
        "extension": "<VariableReferenceString>",
        "toolSound": None,
        "description": "<string>",
        "addressType": "<CallForwardAddressType>",
        "callerIDPassthrough": True
      },
      "knowledgeBaseTool": {
        "query": "<VariableReferenceString>",
        "enabled": True,
        "filters": [
          "<StableKBFilter>"
        ],
        "messages": None,
        "toolSound": None,
        "chunkLimit": 0,
        "description": "<string>",
        "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
        "sourceUrlsCount": 0
      }
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf playbook update --playbook-id <playbookID> --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "name": "<string>",
  "settings": {
    "model": "<AIModel>",
    "realtime": {
      "voice": "<string>",
      "eagerness": "<string>"
    },
    "maxTokens": 0,
    "temperature": 0,
    "reasoningEffort": "<AIReasoningEffort>",
    "serviceTier": "<AIParamsServiceTier>"
  },
  "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": "<VariableReferenceString>",
    "messages": null,
    "extension": "<VariableReferenceString>",
    "toolSound": null,
    "description": "<string>",
    "addressType": "<CallForwardAddressType>",
    "callerIDPassthrough": true
  },
  "knowledgeBaseTool": {
    "query": "<VariableReferenceString>",
    "enabled": true,
    "filters": [
      "<StableKBFilter>"
    ],
    "messages": null,
    "toolSound": null,
    "chunkLimit": 0,
    "description": "<string>",
    "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
    "sourceUrlsCount": 0
  }
}
JSON
```


## Read playbook instructions

Returns one page of a playbook's instructions, each line prefixed with its 1-based number, so a later patch can quote text exactly as it appears. `offset` and `limit` pick the page; the totals in the response cover the whole document.

### Endpoint

```http
GET /v2/stable/playbook/{playbookID}/instructions
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `playbookID`

Required · string

The ID of the playbook to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `offset`

Optional · integer

The 1-based line number to start from. Clamped to the last line of the document.

```json
{
  "default": 1,
  "description": "The 1-based line number to start from. Clamped to the last line of the document.",
  "type": "integer",
  "minimum": 1,
  "maximum": 9007199254740991
}
```

#### `limit`

Optional · integer

The maximum number of lines to return. A page is also capped at 24,000 characters, so a page of very long lines can come back shorter than this — follow nextOffset while hasMore is true.

```json
{
  "default": 400,
  "description": "The maximum number of lines to return. A page is also capped at 24,000 characters, so a page of very long lines can come back shorter than this — follow nextOffset while hasMore is true.",
  "type": "integer",
  "minimum": 1,
  "maximum": 2000
}
```

### Responses

#### 200

Returns the requested lines of the playbook's instructions as one numbered block, with the page's actual offset, its line count, the document's total lines and characters, and whether more lines follow.

Schema:

```json
{
  "$ref": "#/components/schemas/StableInstructionsReadResponseV2"
}
```

Example:

```json
{
  "content": "<string>",
  "offset": 0,
  "returnedLines": 0,
  "totalLines": 0,
  "totalCharacters": 0,
  "hasMore": true,
  "nextOffset": 0,
  "note": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v2/stable/playbook/<playbookID>/instructions?projectID=<projectID>&environmentAlias=<environmentAlias>&offset=<offset>&limit=<limit>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

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

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v2/stable/playbook/<playbookID>/instructions?projectID=<projectID>&environmentAlias=<environmentAlias>&offset=<offset>&limit=<limit>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf playbook read-instructions --playbook-id <playbookID> --project-id <projectID> --environment-alias <environmentAlias> --offset <offset> --limit <limit>
```


## Patch playbook instructions

Replaces one exact string in a playbook's instructions with another, matching literally on whitespace, punctuation and case. Quote `oldString` from a read or search result; with `replaceAll` off, more than one match is an error rather than a guess.

### Endpoint

```http
PATCH /v2/stable/playbook/{playbookID}/instructions
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `playbookID`

Required · string

The ID of the playbook to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableInstructionsPatchRequest"
      }
    }
  }
}
```

### Responses

#### 200

Returns how many occurrences were replaced in the playbook's instructions, a unified diff of the changed lines, the document's line count after the write, and any references or mentions the new text left unresolved.

Schema:

```json
{
  "$ref": "#/components/schemas/StableInstructionsPatchResponseV2"
}
```

Example:

```json
{
  "message": "<string>",
  "replacements": 0,
  "diff": "<string>",
  "totalLines": 0,
  "unresolvedReferences": [
    {
      "path": "<string>",
      "token": "<string>",
      "reason": "unknown"
    }
  ],
  "unresolvedMentions": [
    {
      "path": "<string>",
      "mention": "<string>"
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request PATCH \
  --url 'https://realtime-api.voiceflow.com/v2/stable/playbook/<playbookID>/instructions?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "oldString": "<string>",
  "newString": "<string>",
  "replaceAll": false
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/stable/playbook/<playbookID>/instructions?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "oldString": "<string>",
    "newString": "<string>",
    "replaceAll": false
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.patch(
    'https://realtime-api.voiceflow.com/v2/stable/playbook/<playbookID>/instructions?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "oldString": "<string>",
      "newString": "<string>",
      "replaceAll": False
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf playbook patch-instructions --playbook-id <playbookID> --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "oldString": "<string>",
  "newString": "<string>",
  "replaceAll": false
}
JSON
```


## Search playbook instructions

Searches a playbook's instructions line by line with a JavaScript regular expression and returns one page of matching lines with surrounding context, up to `limit`; the match totals count the whole document.

### Endpoint

```http
POST /v2/stable/playbook/{playbookID}/instructions/search
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `playbookID`

Required · string

The ID of the playbook to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableInstructionsSearchRequest"
      }
    }
  }
}
```

### Responses

#### 200

Returns the matching lines of the playbook's instructions, each with its line number, hit count and context lines, plus the total matches and matching lines across the whole document and whether the limit cut the list short.

Schema:

```json
{
  "$ref": "#/components/schemas/StableInstructionsSearchResponse"
}
```

Example:

```json
{
  "matches": [
    {
      "line": 0,
      "count": 0,
      "before": [
        "<string>"
      ],
      "text": "<string>",
      "after": [
        "<string>"
      ]
    }
  ],
  "totalMatches": 0,
  "matchingLines": 0,
  "hasMore": true
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v2/stable/playbook/<playbookID>/instructions/search?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "pattern": "<string>",
  "ignoreCase": false,
  "contextLines": 0,
  "limit": 50
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/stable/playbook/<playbookID>/instructions/search?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "pattern": "<string>",
    "ignoreCase": false,
    "contextLines": 0,
    "limit": 50
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v2/stable/playbook/<playbookID>/instructions/search?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "pattern": "<string>",
      "ignoreCase": False,
      "contextLines": 0,
      "limit": 50
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf playbook search-instructions --playbook-id <playbookID> --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "pattern": "<string>",
  "ignoreCase": false,
  "contextLines": 0,
  "limit": 50
}
JSON
```


## Duplicate playbook

Copy a playbook with its exit paths, messages and every tool but a workflow tool.

### Endpoint

```http
POST /v1/stable/playbook/{playbookID}/duplicate
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `playbookID`

Required · string



```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StablePlaybookDuplicateRequest"
      }
    }
  }
}
```

### Responses

#### 201

Schema:

```json
{
  "$ref": "#/components/schemas/StablePlaybookDuplicateResponse"
}
```

Example:

```json
{
  "playbook": {
    "id": "<string>",
    "name": "<string>",
    "settings": {
      "model": "<AIModel>",
      "realtime": {
        "voice": "<string>",
        "eagerness": "<string>"
      },
      "maxTokens": 0,
      "temperature": 0,
      "reasoningEffort": "<AIReasoningEffort>",
      "serviceTier": "<AIParamsServiceTier>"
    },
    "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>"
    },
    "webSearchTool": {
      "enabled": true,
      "messages": null,
      "toolSound": null,
      "description": "<string>",
      "allowedDomains": [
        "<string>"
      ],
      "sourceUrlsCount": 0
    },
    "callForwardTool": {
      "enabled": true,
      "address": "<VariableReferenceString>",
      "messages": null,
      "extension": "<VariableReferenceString>",
      "toolSound": null,
      "description": "<string>",
      "addressType": "<CallForwardAddressType>",
      "callerIDPassthrough": true
    },
    "knowledgeBaseTool": {
      "query": "<VariableReferenceString>",
      "enabled": true,
      "filters": [
        "<StableKBFilter>"
      ],
      "messages": null,
      "toolSound": null,
      "chunkLimit": 0,
      "description": "<string>",
      "queryMode": "<AgentKnowledgeBaseToolQueryMode>",
      "sourceUrlsCount": 0
    },
    "skipTurnTool": {
      "enabled": true,
      "description": "<string>"
    },
    "instructionsLineCount": 0
  },
  "ids": {
    "tools": {},
    "paths": {}
  },
  "skippedWorkflowTools": [
    "<string>"
  ]
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>/duplicate?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>"
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>/duplicate?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "<string>"
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>/duplicate?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "name": "<string>"
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf playbook duplicate --playbook-id <playbookID> --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "name": "<string>"
}
JSON
```


## Add playbook tool message

Gives one of the playbook's tools a message in a slot that has none yet, either generative (examples the model writes from) or scripted (an existing response said verbatim). Address a built-in tool with `nativeTool` or an attached tool with `toolID`, and compile the environment afterward.

### Endpoint

```http
POST /v1/stable/playbook/{playbookID}/tool-message
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `playbookID`

Required · string

The ID of the playbook to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `slot`

Required · object

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

```json
{
  "$ref": "#/components/schemas/StableToolMessageSlot"
}
```

#### `toolID`

Optional · string

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

```json
{
  "description": "A tool attached to this agent or playbook. Cannot be used with nativeTool.",
  "type": "string",
  "minLength": 1
}
```

#### `nativeTool`

Optional · object

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

```json
{
  "allOf": [
    {
      "$ref": "#/components/schemas/StableNativeToolKey"
    }
  ]
}
```

### Request body

A tool message in one of its two forms. Writing one form switches the slot to it and leaves the other form stored but inactive, exactly as the editor does — so switching back does not have to be retyped.

Required

```json
{
  "required": true,
  "description": "A tool message in one of its two forms. Writing one form switches the slot to it and leaves the other form stored but inactive, exactly as the editor does — so switching back does not have to be retyped.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableToolMessageRequest"
      }
    }
  }
}
```

### Responses

#### 200

Confirms the message was set and which form, generative or scripted, the slot is now in.

Schema:

```json
{
  "$ref": "#/components/schemas/StableTextUpdateResponse"
}
```

Example:

```json
{
  "message": "<string>",
  "unresolvedReferences": [
    {
      "path": "<string>",
      "token": "<string>",
      "reason": "unknown"
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>/tool-message?projectID=<projectID>&environmentAlias=<environmentAlias>&slot=<slot>&toolID=<toolID>&nativeTool=<nativeTool>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "generative",
  "examples": [
    "<string>"
  ]
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>/tool-message?projectID=<projectID>&environmentAlias=<environmentAlias>&slot=<slot>&toolID=<toolID>&nativeTool=<nativeTool>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "type": "generative",
    "examples": [
      "<string>"
    ]
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>/tool-message?projectID=<projectID>&environmentAlias=<environmentAlias>&slot=<slot>&toolID=<toolID>&nativeTool=<nativeTool>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "type": "generative",
      "examples": [
        "<string>"
      ]
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf playbook add-tool-message --playbook-id <playbookID> --project-id <projectID> --environment-alias <environmentAlias> --slot <slot> --tool-id <toolID> --native-tool <nativeTool> <<'JSON'
{
  "type": "generative",
  "examples": [
    "<string>"
  ]
}
JSON
```


## Update playbook tool message

Replaces the message in a slot that already has one, with the full set of examples or the response to say instead. Switching between generative and scripted keeps the stored text of the form you switched away from, switched off.

### Endpoint

```http
PATCH /v1/stable/playbook/{playbookID}/tool-message
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `playbookID`

Required · string

The ID of the playbook to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `slot`

Required · object

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

```json
{
  "$ref": "#/components/schemas/StableToolMessageSlot"
}
```

#### `toolID`

Optional · string

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

```json
{
  "description": "A tool attached to this agent or playbook. Cannot be used with nativeTool.",
  "type": "string",
  "minLength": 1
}
```

#### `nativeTool`

Optional · object

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

```json
{
  "allOf": [
    {
      "$ref": "#/components/schemas/StableNativeToolKey"
    }
  ]
}
```

### Request body

A tool message in one of its two forms. Writing one form switches the slot to it and leaves the other form stored but inactive, exactly as the editor does — so switching back does not have to be retyped.

Required

```json
{
  "required": true,
  "description": "A tool message in one of its two forms. Writing one form switches the slot to it and leaves the other form stored but inactive, exactly as the editor does — so switching back does not have to be retyped.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableToolMessageRequest"
      }
    }
  }
}
```

### Responses

#### 200

Confirms the message was replaced and which form, generative or scripted, the slot is now in.

Schema:

```json
{
  "$ref": "#/components/schemas/StableTextUpdateResponse"
}
```

Example:

```json
{
  "message": "<string>",
  "unresolvedReferences": [
    {
      "path": "<string>",
      "token": "<string>",
      "reason": "unknown"
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request PATCH \
  --url 'https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>/tool-message?projectID=<projectID>&environmentAlias=<environmentAlias>&slot=<slot>&toolID=<toolID>&nativeTool=<nativeTool>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "generative",
  "examples": [
    "<string>"
  ]
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>/tool-message?projectID=<projectID>&environmentAlias=<environmentAlias>&slot=<slot>&toolID=<toolID>&nativeTool=<nativeTool>', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "type": "generative",
    "examples": [
      "<string>"
    ]
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.patch(
    'https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>/tool-message?projectID=<projectID>&environmentAlias=<environmentAlias>&slot=<slot>&toolID=<toolID>&nativeTool=<nativeTool>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "type": "generative",
      "examples": [
        "<string>"
      ]
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf playbook update-tool-message --playbook-id <playbookID> --project-id <projectID> --environment-alias <environmentAlias> --slot <slot> --tool-id <toolID> --native-tool <nativeTool> <<'JSON'
{
  "type": "generative",
  "examples": [
    "<string>"
  ]
}
JSON
```


## Delete playbook tool message

Clears one message slot on one of the playbook's tools, discarding its examples and unlinking its scripted response. The response carries only a confirmation message, so refetch the playbook's tool to see its remaining messages.

### Endpoint

```http
DELETE /v1/stable/playbook/{playbookID}/tool-message
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `playbookID`

Required · string

The ID of the playbook to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `slot`

Required · object

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

```json
{
  "$ref": "#/components/schemas/StableToolMessageSlot"
}
```

#### `toolID`

Optional · string

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

```json
{
  "description": "A tool attached to this agent or playbook. Cannot be used with nativeTool.",
  "type": "string",
  "minLength": 1
}
```

#### `nativeTool`

Optional · object

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

```json
{
  "allOf": [
    {
      "$ref": "#/components/schemas/StableNativeToolKey"
    }
  ]
}
```

### Responses

#### 200

Confirms the message in the requested slot was removed.

Schema:

```json
{
  "$ref": "#/components/schemas/StableDeleteResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request DELETE \
  --url 'https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>/tool-message?projectID=<projectID>&environmentAlias=<environmentAlias>&slot=<slot>&toolID=<toolID>&nativeTool=<nativeTool>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>/tool-message?projectID=<projectID>&environmentAlias=<environmentAlias>&slot=<slot>&toolID=<toolID>&nativeTool=<nativeTool>', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.delete(
    'https://realtime-api.voiceflow.com/v1/stable/playbook/<playbookID>/tool-message?projectID=<projectID>&environmentAlias=<environmentAlias>&slot=<slot>&toolID=<toolID>&nativeTool=<nativeTool>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf playbook delete-tool-message --playbook-id <playbookID> --project-id <projectID> --environment-alias <environmentAlias> --slot <slot> --tool-id <toolID> --native-tool <nativeTool>
```


## Schema definitions

### AIModel

```json
{
  "type": "string",
  "enum": [
    "gpt-3.5-turbo-1106",
    "gpt-3.5-turbo",
    "gpt-4",
    "gpt-4o",
    "gpt-4o-mini",
    "gpt-4.1-2025-04-14",
    "gpt-4.1-mini-2025-04-14",
    "gpt-4.1-nano-2025-04-14",
    "gpt-o3-mini",
    "o3-2025-04-16",
    "o4-mini-2025-04-16",
    "gpt-5",
    "gpt-5-mini",
    "gpt-5-nano",
    "gpt-5.2",
    "gpt-5.4",
    "gpt-5.4-mini",
    "gpt-5.5",
    "gpt-5.6-sol",
    "gpt-5.6-terra",
    "gpt-5.6-luna",
    "gpt-6-sol",
    "gpt-6-luna",
    "gpt-6.1-sol",
    "gpt-realtime",
    "gpt-live-1",
    "claude-4-opus",
    "claude-4-sonnet",
    "claude-4.5-sonnet",
    "claude-4.6-sonnet",
    "claude-4.5-haiku",
    "claude-4.5-opus",
    "claude-4.7-opus",
    "bedrock-claude-4-sonnet",
    "bedrock-claude-4.5-sonnet",
    "bedrock-claude-4.6-sonnet",
    "bedrock-claude-5-sonnet",
    "bedrock-claude-5.5-sonnet",
    "bedrock-claude-4.5-haiku",
    "bedrock-claude-5.5-haiku",
    "bedrock-claude-4.5-opus",
    "bedrock-claude-4.7-opus",
    "bedrock-claude-4.8-opus",
    "voiceflow-core-4.0",
    "voiceflow-core-4.1",
    "voiceflow-core-4.2",
    "voiceflow-flash-4.2",
    "gemini-2.5-pro",
    "gemini-2.5-flash",
    "gemini-live-2.5-flash",
    "gemini-3-flash",
    "gemini-3.5-flash",
    "gemini-3.1-pro",
    "gpt-oss-20b",
    "gpt-oss-120b",
    "llama-guard-4",
    "llama-3.1-instant",
    "llama-3.3-versatile",
    "qwen3.6-27b",
    "grok-4.6",
    "voiceflow-flash-4.1",
    "kimi-k3",
    "gemini-flash-2",
    "gpt-4-turbo",
    "claude-3.5-haiku",
    "claude-3-opus",
    "claude-3.7-sonnet",
    "claude-v2",
    "llama-3.2-1b-preview",
    "gemini-pro-1.5",
    "claude-3-haiku",
    "claude-3-sonnet",
    "text-davinci-003",
    "claude-v1",
    "claude-instant-v1",
    "deep-seek-r1-distill-llama-70B",
    "claude-3.5-sonnet"
  ],
  "x-enumNames": [
    "GPT_3_5_TURBO_1106",
    "GPT_3_5_TURBO",
    "GPT_4",
    "GPT_4_O",
    "GPT_4_O_MINI",
    "GPT_4_1",
    "GPT_4_1_MINI",
    "GPT_4_1_NANO",
    "GPT_O_3_MINI",
    "GPT_O_3",
    "GPT_O_4_MINI",
    "GPT_5",
    "GPT_5_MINI",
    "GPT_5_NANO",
    "GPT_5_2",
    "GPT_5_4",
    "GPT_5_4_MINI",
    "GPT_5_5",
    "GPT_5_6_SOL",
    "GPT_5_6_TERRA",
    "GPT_5_6_LUNA",
    "GPT_6_SOL",
    "GPT_6_LUNA",
    "GPT_6_1_SOL",
    "GPT_REALTIME",
    "GPT_LIVE_1",
    "CLAUDE_4_OPUS",
    "CLAUDE_4_SONNET",
    "CLAUDE_4_5_SONNET",
    "CLAUDE_4_6_SONNET",
    "CLAUDE_4_5_HAIKU",
    "CLAUDE_4_5_OPUS",
    "CLAUDE_4_7_OPUS",
    "BEDROCK_CLAUDE_4_SONNET",
    "BEDROCK_CLAUDE_4_5_SONNET",
    "BEDROCK_CLAUDE_4_6_SONNET",
    "BEDROCK_CLAUDE_5_SONNET",
    "BEDROCK_CLAUDE_5_5_SONNET",
    "BEDROCK_CLAUDE_4_5_HAIKU",
    "BEDROCK_CLAUDE_5_5_HAIKU",
    "BEDROCK_CLAUDE_4_5_OPUS",
    "BEDROCK_CLAUDE_4_7_OPUS",
    "BEDROCK_CLAUDE_4_8_OPUS",
    "VOICEFLOW_CORE_4_0",
    "VOICEFLOW_CORE_4_1",
    "VOICEFLOW_CORE_4_2",
    "VOICEFLOW_FLASH_4_2",
    "GEMINI_2_5_PRO",
    "GEMINI_2_5_FLASH",
    "GEMINI_LIVE_2_5_FLASH",
    "GEMINI_3_FLASH",
    "GEMINI_3_5_FLASH",
    "GEMINI_3_1_PRO",
    "GPT_OSS_20_B",
    "GPT_OSS_120_B",
    "LLAMA_GUARD_4",
    "LLAMA_3_1_INSTANT",
    "LLAMA_3_3_VERSATILE",
    "QWEN_3_6_27_B",
    "GROK_4_6",
    "VOICEFLOW_FLASH_4_1",
    "KIMI_K_3",
    "GEMINI_FLASH_2",
    "GPT_4_TURBO",
    "CLAUDE_3_5_HAIKU",
    "CLAUDE_3_OPUS",
    "CLAUDE_3_7_SONNET",
    "CLAUDE_V_2",
    "LLAMA_3_2_1_B_PREVIEW",
    "GEMINI_PRO_1_5",
    "CLAUDE_3_HAIKU",
    "CLAUDE_3_SONNET",
    "DA_VINCI_003",
    "CLAUDE_V_1",
    "CLAUDE_INSTANT_V_1",
    "DEEP_SEEK_R_1_DISTILL_LLAMA_70_B",
    "CLAUDE_3_5_SONNET"
  ]
}
```

### AIParamsServiceTier

```json
{
  "type": "string",
  "enum": [
    "default",
    "flex",
    "priority"
  ],
  "x-enumNames": [
    "DEFAULT",
    "FLEX",
    "PRIORITY"
  ]
}
```

### AIReasoningEffort

```json
{
  "type": "string",
  "enum": [
    "off",
    "adaptive",
    "minimal",
    "low",
    "medium",
    "high"
  ],
  "x-enumNames": [
    "OFF",
    "ADAPTIVE",
    "MINIMAL",
    "LOW",
    "MEDIUM",
    "HIGH"
  ]
}
```

### AgentKnowledgeBaseToolQueryMode

```json
{
  "type": "string",
  "enum": [
    "custom",
    "rewriting"
  ],
  "x-enumNames": [
    "CUSTOM",
    "REWRITING"
  ]
}
```

### AgentSettings

```json
{
  "type": "object",
  "properties": {
    "model": {
      "allOf": [
        {
          "$ref": "#/components/schemas/AIModel"
        }
      ]
    },
    "realtime": {
      "type": "object",
      "properties": {
        "voice": {
          "type": "string"
        },
        "eagerness": {
          "type": "string"
        }
      }
    },
    "maxTokens": {
      "type": "number"
    },
    "temperature": {
      "type": "number"
    },
    "reasoningEffort": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/AIReasoningEffort"
        }
      ]
    },
    "serviceTier": {
      "description": "The service tier to request from models that support it. `priority` is faster processing: faster responses at a higher credit cost. When unset, the deprecated project-level `priorityProcessing` setting applies.",
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/AIParamsServiceTier"
        }
      ]
    }
  }
}
```

### AgentSkipTurnTool

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "description": {
      "type": "string"
    }
  },
  "required": [
    "enabled",
    "description"
  ]
}
```

### CallForwardAddressType

```json
{
  "type": "string",
  "enum": [
    "phone",
    "sip"
  ],
  "x-enumNames": [
    "PHONE",
    "SIP"
  ]
}
```

### DefaultValueString

```json
{
  "type": "string",
  "description": "Plain text resolved at runtime and never shown to a model. {variable_name} inserts a variable or entity, {secret_name} a project secret, {variable_name.path} a field of a variable. Escape a literal { or \\ with a backslash. When a name is both a variable and a secret, the secret wins. A name matching none is stored as literal text and reported in unresolvedReferences. Where the field is sent to an upstream system, an unresolved placeholder may be sent as literal text; on an MCP server it is re-resolved by name at connect time, so a literal that matches a real secret binds."
}
```

### MarkdownLikeString

```json
{
  "type": "string",
  "description": "Message text shown to the end user. Limited markdown: **bold**, _italic_, <u>underline</u>, ~~strikethrough~~, [label](url). {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."
}
```

### MarkdownText

```json
{
  "type": "string",
  "description": "Markdown text. Backticked `Name` resolves to a tool, playbook, or workflow reference, and a system tool is written as its field name, such as `webSearchTool`; braced {name} resolves to a variable or entity reference. A name that resolves to nothing is stored as literal text and reported back in the response. Text is saved in one form: a numbered list keeps its first number and counts up from it, bullets are -, italics are _x_, a nested list is indented to its parent's text, and every callout line starts with >. Outside inline code a backslash before punctuation is a markdown escape and is not kept; put regular expressions and code in backticks."
}
```

### StableButtonTool

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "messages": {
      "default": null,
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableToolMessages"
        }
      ]
    },
    "description": {
      "type": "string"
    }
  },
  "required": [
    "enabled",
    "description"
  ]
}
```

### StableCallForwardTool

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "address": {
      "$ref": "#/components/schemas/VariableReferenceString"
    },
    "messages": {
      "default": null,
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableToolMessages"
        }
      ]
    },
    "extension": {
      "allOf": [
        {
          "$ref": "#/components/schemas/VariableReferenceString"
        }
      ]
    },
    "toolSound": {
      "default": null,
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/ToolNodeDataToolSound"
        }
      ]
    },
    "description": {
      "type": "string"
    },
    "addressType": {
      "$ref": "#/components/schemas/CallForwardAddressType"
    },
    "callerIDPassthrough": {
      "type": "boolean"
    }
  },
  "required": [
    "enabled",
    "address",
    "description",
    "addressType"
  ]
}
```

### StableCardTool

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "messages": {
      "default": null,
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableToolMessages"
        }
      ]
    },
    "description": {
      "type": "string"
    }
  },
  "required": [
    "enabled",
    "description"
  ]
}
```

### StableDeleteResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the deletion."
    }
  },
  "required": [
    "message"
  ]
}
```

### StableEndTool

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "messages": {
      "default": null,
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableToolMessages"
        }
      ]
    },
    "toolSound": {
      "default": null,
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/ToolNodeDataToolSound"
        }
      ]
    },
    "description": {
      "type": "string"
    }
  },
  "required": [
    "enabled",
    "description"
  ]
}
```

### StableInstructionsPatchRequest

```json
{
  "type": "object",
  "properties": {
    "oldString": {
      "type": "string",
      "minLength": 1,
      "description": "The exact text to replace, copied verbatim from a read or search result. Matching is literal — whitespace, punctuation and case must match. Do not include the line numbers a read adds."
    },
    "newString": {
      "type": "string",
      "description": "The text to put in its place. May be empty to delete."
    },
    "replaceAll": {
      "default": false,
      "description": "Replace every occurrence. When false, more than one match is an error rather than a guess.",
      "type": "boolean"
    }
  },
  "required": [
    "oldString",
    "newString"
  ],
  "additionalProperties": false
}
```

### StableInstructionsPatchResponseV2

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable summary naming the lines that changed."
    },
    "replacements": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many occurrences were replaced."
    },
    "diff": {
      "type": "string",
      "description": "A unified diff of the changed lines, with 1-based hunk headers."
    },
    "totalLines": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many lines the document has AFTER the write."
    },
    "unresolvedReferences": {
      "description": "References this write kept as literal text instead of binding, each with the reason. The write still succeeded.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableUnresolvedReference"
      }
    },
    "unresolvedMentions": {
      "description": "Backticked `name` mentions that matched no attached tool, playbook or workflow and were stored as inline code. The write still succeeded.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableUnresolvedMention"
      }
    }
  },
  "required": [
    "message",
    "replacements",
    "diff",
    "totalLines"
  ]
}
```

### StableInstructionsReadResponseV2

```json
{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "The requested lines, each as its 1-based number, a tab, then the text, joined by newlines."
    },
    "offset": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "The line number this page actually starts at, after clamping."
    },
    "returnedLines": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many lines this page carries."
    },
    "totalLines": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many lines the whole document has."
    },
    "totalCharacters": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many characters the whole document has."
    },
    "hasMore": {
      "type": "boolean",
      "description": "Whether lines remain after this page."
    },
    "nextOffset": {
      "nullable": true,
      "description": "The first line not returned, or null when there is nothing more to read.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "note": {
      "description": "Names the backticked names on this page that are links to a tool, playbook or workflow. A link reads as the resource's current name, whatever spelling the write used. Absent when the page shows no link.",
      "type": "string"
    }
  },
  "required": [
    "content",
    "offset",
    "returnedLines",
    "totalLines",
    "totalCharacters",
    "hasMore",
    "nextOffset"
  ]
}
```

### StableInstructionsSearchMatch

```json
{
  "type": "object",
  "properties": {
    "line": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "The 1-based line number of the match."
    },
    "count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many times the pattern matched on this line."
    },
    "before": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The requested lines of context above this one."
    },
    "text": {
      "type": "string",
      "description": "The matching line."
    },
    "after": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The requested lines of context below this one."
    }
  },
  "required": [
    "line",
    "count",
    "before",
    "text",
    "after"
  ]
}
```

### StableInstructionsSearchRequest

```json
{
  "type": "object",
  "properties": {
    "pattern": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "description": "A JavaScript regular expression, evaluated against each line on its own."
    },
    "ignoreCase": {
      "default": false,
      "description": "Match case-insensitively. Defaults to false, like grep.",
      "type": "boolean"
    },
    "contextLines": {
      "default": 0,
      "description": "How many lines either side of each match to return.",
      "type": "integer",
      "minimum": 0,
      "maximum": 5
    },
    "limit": {
      "default": 50,
      "description": "The maximum number of matching LINES to return. The reported totals cover the whole document.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "required": [
    "pattern"
  ],
  "additionalProperties": false
}
```

### StableInstructionsSearchResponse

```json
{
  "type": "object",
  "properties": {
    "matches": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableInstructionsSearchMatch"
      }
    },
    "totalMatches": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Total occurrences across the whole document, not just this page."
    },
    "matchingLines": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Total lines with at least one occurrence, across the whole document."
    },
    "hasMore": {
      "type": "boolean",
      "description": "Whether matching lines were left out because of the limit."
    }
  },
  "required": [
    "matches",
    "totalMatches",
    "matchingLines",
    "hasMore"
  ]
}
```

### StableKBFilter

```json
{
  "type": "object",
  "properties": {
    "description": {
      "default": null,
      "nullable": true,
      "type": "string"
    },
    "defaultValue": {
      "default": null,
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/DefaultValueString"
        }
      ]
    },
    "key": {
      "type": "string"
    }
  },
  "required": [
    "key"
  ]
}
```

### StableKnowledgeBaseTool

```json
{
  "type": "object",
  "properties": {
    "query": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/VariableReferenceString"
        }
      ]
    },
    "enabled": {
      "type": "boolean"
    },
    "filters": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableKBFilter"
      }
    },
    "messages": {
      "default": null,
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableToolMessages"
        }
      ]
    },
    "toolSound": {
      "default": null,
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/ToolNodeDataToolSound"
        }
      ]
    },
    "chunkLimit": {
      "nullable": true,
      "type": "number"
    },
    "description": {
      "type": "string"
    },
    "queryMode": {
      "allOf": [
        {
          "$ref": "#/components/schemas/AgentKnowledgeBaseToolQueryMode"
        }
      ]
    },
    "sourceUrlsCount": {
      "nullable": true,
      "type": "number",
      "minimum": 1,
      "maximum": 5
    }
  },
  "required": [
    "enabled",
    "description"
  ]
}
```

### StableMarkdownUpdateResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the update."
    },
    "unresolvedReferences": {
      "description": "References this write kept as literal text instead of binding, each with the reason. The write still succeeded.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableUnresolvedReference"
      }
    },
    "unresolvedMentions": {
      "description": "Backticked `name` mentions that matched no attached tool, playbook or workflow and were stored as inline code. The write still succeeded.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableUnresolvedMention"
      }
    }
  },
  "required": [
    "message"
  ]
}
```

### StableNativeToolKey

```json
{
  "type": "string",
  "enum": [
    "endTool",
    "cardTool",
    "buttonTool",
    "carouselTool",
    "webSearchTool",
    "callForwardTool",
    "knowledgeBaseTool"
  ],
  "description": "One of the built-in tools on this agent or playbook, under the same key it is read back at. skipTurnTool is absent because it carries no messages. The Voiceflow editor offers only the execution message on endTool, cardTool, buttonTool, carouselTool and callForwardTool; webSearchTool and knowledgeBaseTool offer all four. This API accepts any slot on any of them.",
  "x-enumNames": [
    "END_TOOL",
    "CARD_TOOL",
    "BUTTON_TOOL",
    "CAROUSEL_TOOL",
    "WEB_SEARCH_TOOL",
    "CALL_FORWARD_TOOL",
    "KNOWLEDGE_BASE_TOOL"
  ]
}
```

### StablePlaybookCreateManyRequestV2

```json
{
  "type": "object",
  "properties": {
    "playbooks": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StablePlaybookCreateRequestV2"
      }
    }
  },
  "required": [
    "playbooks"
  ]
}
```

### StablePlaybookCreateRequestV2

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "description": {
      "nullable": true,
      "description": "A human-readable description of what the playbook does.",
      "type": "string"
    },
    "instructions": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/MarkdownText"
        }
      ]
    },
    "endTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableEndTool"
        }
      ]
    },
    "cardTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableCardTool"
        }
      ]
    },
    "buttonTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableButtonTool"
        }
      ]
    },
    "carouselTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableCardTool"
        }
      ]
    },
    "skipTurnTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/AgentSkipTurnTool"
        }
      ]
    },
    "webSearchTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableWebSearchTool"
        }
      ]
    },
    "callForwardTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableCallForwardTool"
        }
      ]
    },
    "knowledgeBaseTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableKnowledgeBaseTool"
        }
      ]
    },
    "settings": {
      "default": {},
      "allOf": [
        {
          "$ref": "#/components/schemas/AgentSettings"
        }
      ]
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}
```

### StablePlaybookDuplicateRequest

```json
{
  "type": "object",
  "properties": {
    "name": {
      "description": "The name of the copy. Leave it out to use the original's name with \" copy\" added.",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    }
  },
  "additionalProperties": false
}
```

### StablePlaybookDuplicateResponse

```json
{
  "type": "object",
  "properties": {
    "playbook": {
      "$ref": "#/components/schemas/StablePlaybookReadV2"
    },
    "ids": {
      "type": "object",
      "properties": {
        "tools": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Each of the original's API, function, MCP and integration attachments mapped to the copy's."
        },
        "paths": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Each of the original's exit paths mapped to the copy's."
        }
      },
      "required": [
        "tools",
        "paths"
      ],
      "description": "Where each copied tool and exit path went."
    },
    "skippedWorkflowTools": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The original's workflow tools. The copy did not get them, because workflow tools go on the Main Agent only. The original keeps them."
    }
  },
  "required": [
    "playbook",
    "ids",
    "skippedWorkflowTools"
  ]
}
```

### StablePlaybookListResponseV2

```json
{
  "type": "object",
  "properties": {
    "playbooks": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StablePlaybookV2"
      }
    },
    "unresolvedReferences": {
      "description": "References this write kept as literal text instead of binding, each with the reason. The write still succeeded.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableUnresolvedReference"
      }
    },
    "unresolvedMentions": {
      "description": "Backticked `name` mentions that matched no attached tool, playbook or workflow and were stored as inline code. The write still succeeded.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableUnresolvedMention"
      }
    }
  },
  "required": [
    "playbooks"
  ]
}
```

### StablePlaybookReadListResponseV2

```json
{
  "type": "object",
  "properties": {
    "playbooks": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StablePlaybookReadV2"
      }
    }
  },
  "required": [
    "playbooks"
  ]
}
```

### StablePlaybookReadResponseV2

```json
{
  "type": "object",
  "properties": {
    "playbook": {
      "$ref": "#/components/schemas/StablePlaybookReadV2"
    }
  },
  "required": [
    "playbook"
  ]
}
```

### StablePlaybookReadV2

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "settings": {
      "$ref": "#/components/schemas/AgentSettings"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "description": {
      "nullable": true,
      "description": "A human-readable description of what the playbook does.",
      "type": "string"
    },
    "instructions": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/MarkdownText"
        }
      ]
    },
    "pathToolOrder": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The IDs of the playbook's path tools, in display order."
    },
    "endTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableEndTool"
        }
      ]
    },
    "cardTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableCardTool"
        }
      ]
    },
    "buttonTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableButtonTool"
        }
      ]
    },
    "carouselTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableCardTool"
        }
      ]
    },
    "webSearchTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableWebSearchTool"
        }
      ]
    },
    "callForwardTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableCallForwardTool"
        }
      ]
    },
    "knowledgeBaseTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableKnowledgeBaseTool"
        }
      ]
    },
    "skipTurnTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/AgentSkipTurnTool"
        }
      ]
    },
    "instructionsLineCount": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many lines the instructions have, so a caller can decide whether to page through them."
    }
  },
  "required": [
    "id",
    "name",
    "settings",
    "createdAt",
    "updatedAt",
    "description",
    "pathToolOrder",
    "endTool",
    "cardTool",
    "buttonTool",
    "carouselTool",
    "webSearchTool",
    "callForwardTool",
    "knowledgeBaseTool",
    "skipTurnTool",
    "instructionsLineCount"
  ]
}
```

### StablePlaybookResponseV2

```json
{
  "type": "object",
  "properties": {
    "playbook": {
      "$ref": "#/components/schemas/StablePlaybookV2"
    },
    "unresolvedReferences": {
      "description": "References this write kept as literal text instead of binding, each with the reason. The write still succeeded.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableUnresolvedReference"
      }
    },
    "unresolvedMentions": {
      "description": "Backticked `name` mentions that matched no attached tool, playbook or workflow and were stored as inline code. The write still succeeded.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableUnresolvedMention"
      }
    }
  },
  "required": [
    "playbook"
  ]
}
```

### StablePlaybookUpdateRequestV2

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "settings": {
      "allOf": [
        {
          "$ref": "#/components/schemas/AgentSettings"
        }
      ]
    },
    "description": {
      "nullable": true,
      "description": "A human-readable description of what the playbook does.",
      "type": "string"
    },
    "instructions": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/MarkdownText"
        }
      ]
    },
    "endTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableEndTool"
        }
      ]
    },
    "cardTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableCardTool"
        }
      ]
    },
    "buttonTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableButtonTool"
        }
      ]
    },
    "carouselTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableCardTool"
        }
      ]
    },
    "skipTurnTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/AgentSkipTurnTool"
        }
      ]
    },
    "webSearchTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableWebSearchTool"
        }
      ]
    },
    "callForwardTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableCallForwardTool"
        }
      ]
    },
    "knowledgeBaseTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableKnowledgeBaseTool"
        }
      ]
    }
  },
  "additionalProperties": false
}
```

### StablePlaybookV2

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "settings": {
      "$ref": "#/components/schemas/AgentSettings"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "description": {
      "nullable": true,
      "description": "A human-readable description of what the playbook does.",
      "type": "string"
    },
    "instructions": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/MarkdownText"
        }
      ]
    },
    "pathToolOrder": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The IDs of the playbook's path tools, in display order."
    },
    "endTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableEndTool"
        }
      ]
    },
    "cardTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableCardTool"
        }
      ]
    },
    "buttonTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableButtonTool"
        }
      ]
    },
    "carouselTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableCardTool"
        }
      ]
    },
    "webSearchTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableWebSearchTool"
        }
      ]
    },
    "callForwardTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableCallForwardTool"
        }
      ]
    },
    "knowledgeBaseTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableKnowledgeBaseTool"
        }
      ]
    },
    "skipTurnTool": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/AgentSkipTurnTool"
        }
      ]
    }
  },
  "required": [
    "id",
    "name",
    "settings",
    "createdAt",
    "updatedAt",
    "description",
    "instructions",
    "pathToolOrder",
    "endTool",
    "cardTool",
    "buttonTool",
    "carouselTool",
    "webSearchTool",
    "callForwardTool",
    "knowledgeBaseTool",
    "skipTurnTool"
  ]
}
```

### StableTextUpdateResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the update."
    },
    "unresolvedReferences": {
      "description": "References this write kept as literal text instead of binding, each with the reason. The write still succeeded.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableUnresolvedReference"
      }
    }
  },
  "required": [
    "message"
  ]
}
```

### StableToolMessageGenerative

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "examples": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/MarkdownLikeString"
      }
    }
  },
  "required": [
    "enabled"
  ]
}
```

### StableToolMessageRequest

```json
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "generative"
          ],
          "description": "Discriminator: the model writes this message itself, guided by the examples below.",
          "x-enumNames": [
            "GENERATIVE"
          ]
        },
        "examples": {
          "minItems": 1,
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/MarkdownLikeString"
          },
          "description": "Example phrasings the model writes from. Replaces every example the slot holds today."
        }
      },
      "required": [
        "type",
        "examples"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "scripted"
          ],
          "description": "Discriminator: this message is a fixed response, said verbatim.",
          "x-enumNames": [
            "SCRIPTED"
          ]
        },
        "messageID": {
          "type": "string",
          "description": "The ID of an existing response in this environment — the same ID this slot reports as <slot>MessageID on a read."
        }
      },
      "required": [
        "type",
        "messageID"
      ],
      "additionalProperties": false
    }
  ],
  "description": "A tool message in one of its two forms. Writing one form switches the slot to it and leaves the other form stored but inactive, exactly as the editor does — so switching back does not have to be retyped."
}
```

### StableToolMessageSlot

```json
{
  "type": "string",
  "enum": [
    "delay",
    "failure",
    "execution",
    "completion"
  ],
  "description": "Which of the tool's four messages to write. `execution` is said when the tool starts (the editor labels it Start), `completion` when it finishes (Complete), `failure` when it errors (Failed), `delay` when it is taking a while (Delayed).",
  "x-enumNames": [
    "DELAY",
    "FAILURE",
    "EXECUTION",
    "COMPLETION"
  ]
}
```

### StableToolMessages

```json
{
  "type": "object",
  "properties": {
    "generative": {
      "type": "object",
      "properties": {
        "execution": {
          "allOf": [
            {
              "$ref": "#/components/schemas/StableToolMessageGenerative"
            }
          ]
        },
        "failure": {
          "allOf": [
            {
              "$ref": "#/components/schemas/StableToolMessageGenerative"
            }
          ]
        },
        "delay": {
          "allOf": [
            {
              "$ref": "#/components/schemas/StableToolMessageGenerative"
            }
          ]
        },
        "completion": {
          "allOf": [
            {
              "$ref": "#/components/schemas/StableToolMessageGenerative"
            }
          ]
        }
      }
    },
    "delayMessageID": {
      "nullable": true,
      "type": "string"
    },
    "failureMessageID": {
      "nullable": true,
      "type": "string"
    },
    "executionMessageID": {
      "nullable": true,
      "type": "string"
    },
    "completionMessageID": {
      "nullable": true,
      "type": "string"
    },
    "delayMessageSeconds": {
      "nullable": true,
      "type": "number"
    }
  },
  "required": [
    "delayMessageID",
    "failureMessageID",
    "executionMessageID",
    "completionMessageID",
    "delayMessageSeconds"
  ]
}
```

### StableUnresolvedMention

```json
{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Dotted path of the markdown field that carried it, e.g. `instructions` or `playbooks[3].instructions`."
    },
    "mention": {
      "type": "string",
      "description": "The mention as written, without backticks."
    }
  },
  "required": [
    "path",
    "mention"
  ]
}
```

### StableUnresolvedReference

```json
{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Dotted path of the field that carried it, e.g. `knowledgeBaseTool.filters[0].defaultValue`."
    },
    "token": {
      "type": "string",
      "description": "The reference as written, without braces."
    },
    "reason": {
      "type": "string",
      "enum": [
        "unknown",
        "secret-not-allowed",
        "path-on-non-variable",
        "resource-id",
        "invalid-name",
        "dangling"
      ],
      "description": "`unknown`: no variable or entity of that name. `secret-not-allowed`: the name is a project secret and this field does not accept one. `path-on-non-variable`: only a variable has fields. `resource-id`: a bare resource id, not a name. `invalid-name`: outside the `^\\w{1,64}$` name grammar. `dangling`: the reference rendered as a bare id, because its row is gone or its name is outside the name grammar.",
      "x-enumNames": [
        "UNKNOWN",
        "SECRET_NOT_ALLOWED",
        "PATH_ON_NON_VARIABLE",
        "RESOURCE_ID",
        "INVALID_NAME",
        "DANGLING"
      ]
    }
  },
  "required": [
    "path",
    "token",
    "reason"
  ]
}
```

### StableWebSearchTool

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "messages": {
      "default": null,
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableToolMessages"
        }
      ]
    },
    "toolSound": {
      "default": null,
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/ToolNodeDataToolSound"
        }
      ]
    },
    "description": {
      "type": "string"
    },
    "allowedDomains": {
      "nullable": true,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "sourceUrlsCount": {
      "nullable": true,
      "type": "number",
      "minimum": 1,
      "maximum": 5
    }
  },
  "required": [
    "enabled"
  ]
}
```

### ToolNodeDataToolSound

```json
{
  "type": "object",
  "properties": {
    "ref": {
      "nullable": true,
      "type": "string"
    },
    "volume": {
      "default": 0.75,
      "type": "number",
      "minimum": 0,
      "maximum": 1
    }
  },
  "required": [
    "ref"
  ]
}
```

### VariableReferenceString

```json
{
  "type": "string",
  "description": "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."
}
```
