List Library Scenarios

GET

agents

library

scenarios

curl --request GET \
  --url https://api.bland.ai/v2/agents/library/scenarios \
  --header 'authorization: <authorization>'

const options = {method: 'GET', headers: {authorization: '<authorization>'}};

fetch('https://api.bland.ai/v2/agents/library/scenarios', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bland.ai/v2/agents/library/scenarios",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bland.ai/v2/agents/library/scenarios"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v2/agents/library/scenarios")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "agent_id": "b5154820-6f11-4886-8523-d896934528ae",
      "agent_name": "Appointment reminders",
      "scenarios": [
        {
          "id": "00fa3bcf-56f5-45b9-8996-427d57b091b7",
          "name": "Reschedule appointment",
          "kind": "scenario",
          "description": "Help the caller move their appointment. Confirm the new date and time before ending.",
          "node": {
            "id": "00fa3bcf-56f5-45b9-8996-427d57b091b7",
            "type": "scenario",
            "position": { "x": -190, "y": 260 },
            "data": {
              "name": "Reschedule appointment",
              "rule": "Help the caller move their appointment. Confirm the new date and time before ending.",
              "target": { "kind": "dialogue", "label": "Reschedule" },
              "loopWhile": "",
              "variables": [
                {
                  "id": "7aeefed0-9806-400d-b2a7-96e6b58d1ac1",
                  "key": "new_appointment_time",
                  "value": "The date and time the caller agreed to",
                  "type": "string",
                  "accurateSpelling": false
                }
              ],
              "entry": {
                "mode": "llm",
                "label": "Wants to reschedule",
                "description": "",
                "alwaysPick": false,
                "conditions": []
              }
            }
          }
        }
      ]
    },
    {
      "agent_id": "2c5cbfa4-4d00-4b35-bd1b-195598f7d823",
      "agent_name": "Billing support",
      "scenarios": [
        {
          "id": "3c2be395-2d36-4437-833f-aacfc371a033",
          "name": "Dispute a charge",
          "kind": "complex-scenario",
          "description": "Walk the caller through disputing a charge on their statement.",
          "children": [
            {
              "id": "66cbecac-8007-4be8-981c-26264801320f",
              "name": "Collect charge details",
              "kind": "prompt"
            }
          ],
          "node": {
            "id": "3c2be395-2d36-4437-833f-aacfc371a033",
            "type": "complex-scenario",
            "position": { "x": 190, "y": 260 },
            "data": {
              "name": "Dispute a charge",
              "rule": "Walk the caller through disputing a charge on their statement.",
              "target": { "kind": "dialogue", "label": "Dispute" },
              "entry": {
                "mode": "llm",
                "label": "Wants to dispute a charge",
                "description": "",
                "alwaysPick": false,
                "conditions": []
              },
              "flow": {
                "nodes": [
                  { "id": "start", "type": "start", "position": { "x": 0, "y": 0 }, "data": {} },
                  {
                    "id": "66cbecac-8007-4be8-981c-26264801320f",
                    "type": "prompt",
                    "position": { "x": 0, "y": 160 },
                    "data": {
                      "name": "Collect charge details",
                      "prompt": "Ask for the date and amount of the charge the caller wants to dispute.",
                      "useStaticText": false,
                      "loopWhile": "",
                      "variables": [],
                      "useAudioExtraction": false,
                      "ignorePreviousExtractions": false,
                      "settings": {}
                    }
                  },
                  { "id": "end", "type": "end", "position": { "x": 0, "y": 320 }, "data": {} }
                ],
                "edges": [
                  { "id": "e-start-collect", "source": "start", "target": "66cbecac-8007-4be8-981c-26264801320f" },
                  { "id": "e-collect-end", "source": "66cbecac-8007-4be8-981c-26264801320f", "target": "end" }
                ]
              }
            }
          }
        }
      ]
    }
  ],
  "errors": null
}

{
  "data": {
    "groups": [
      {
        "agent_id": "b5154820-6f11-4886-8523-d896934528ae",
        "agent_name": "Appointment reminders",
        "scenarios": [ /* ... */ ]
      }
    ],
    "next_cursor": "b5154820-6f11-4886-8523-d896934528ae"
  },
  "errors": null
}

Overview

Returns the top-level scenario and auth nodes from the newest saved version of each agent in your organization, grouped per agent, with the full node payload inline so you can insert one into another agent’s graph and save it with Create Agent Version. Agents with no saved version or no scenarios are omitted from the results. For nodes you have retired from a canvas, see List Archived Nodes. By default the response is a single bounded page of up to 50 agents. To walk every agent in the organization, opt in to the paginated envelope with paginate=true and follow the returned next_cursor until it is null.

Headers

string

required

Your API key for authentication.

Query Parameters

string

Skip this agent’s scenarios, typically the agent you are currently editing. An empty value is ignored.

boolean

default:"false"

Set to true to receive { groups, next_cursor } instead of the bounded legacy array. Each page returns up to 50 agents.

string

Agent UUID cursor for the next page. Pass the next_cursor from the previous paginated response. Only used when paginate=true. Invalid UUIDs return 400 INVALID_CURSOR.

Response

array | object

Without paginate=true, an array of groups (one per agent that has at least one library scenario), ordered by agent ID. With paginate=true, an object with groups (same shape) and next_cursor (the agent ID to pass as after for the next page, or null when there are no more pages).

Show group object

string

The agent the scenarios were read from.

string

The agent’s display name.

array

The agent’s top-level scenario and auth nodes. See the scenario object below.

array

Scenario objects within a group.

Show scenario object

string

The node’s ID inside its source agent. Remap IDs before inserting the node into another graph.

string

The node’s name, or Untitled node when it has none.

string

The node type. One of scenario, complex-scenario, auth, complex-auth, auth-zone.

string | null

The first 160 characters of the node’s rule or prompt, whitespace collapsed. null when the node has neither.

array

Present only for container nodes (those with a nested data.flow). Each entry has id, name, and kind (the child step’s node type). Start and end pills are excluded.

object

The complete node as stored in the source agent’s version snapshot (id, type, position, data, and for containers data.flow). Insertable as-is.

null | array

null on success, or a list of error objects if the request failed.

{
  "data": [
    {
      "agent_id": "b5154820-6f11-4886-8523-d896934528ae",
      "agent_name": "Appointment reminders",
      "scenarios": [
        {
          "id": "00fa3bcf-56f5-45b9-8996-427d57b091b7",
          "name": "Reschedule appointment",
          "kind": "scenario",
          "description": "Help the caller move their appointment. Confirm the new date and time before ending.",
          "node": {
            "id": "00fa3bcf-56f5-45b9-8996-427d57b091b7",
            "type": "scenario",
            "position": { "x": -190, "y": 260 },
            "data": {
              "name": "Reschedule appointment",
              "rule": "Help the caller move their appointment. Confirm the new date and time before ending.",
              "target": { "kind": "dialogue", "label": "Reschedule" },
              "loopWhile": "",
              "variables": [
                {
                  "id": "7aeefed0-9806-400d-b2a7-96e6b58d1ac1",
                  "key": "new_appointment_time",
                  "value": "The date and time the caller agreed to",
                  "type": "string",
                  "accurateSpelling": false
                }
              ],
              "entry": {
                "mode": "llm",
                "label": "Wants to reschedule",
                "description": "",
                "alwaysPick": false,
                "conditions": []
              }
            }
          }
        }
      ]
    },
    {
      "agent_id": "2c5cbfa4-4d00-4b35-bd1b-195598f7d823",
      "agent_name": "Billing support",
      "scenarios": [
        {
          "id": "3c2be395-2d36-4437-833f-aacfc371a033",
          "name": "Dispute a charge",
          "kind": "complex-scenario",
          "description": "Walk the caller through disputing a charge on their statement.",
          "children": [
            {
              "id": "66cbecac-8007-4be8-981c-26264801320f",
              "name": "Collect charge details",
              "kind": "prompt"
            }
          ],
          "node": {
            "id": "3c2be395-2d36-4437-833f-aacfc371a033",
            "type": "complex-scenario",
            "position": { "x": 190, "y": 260 },
            "data": {
              "name": "Dispute a charge",
              "rule": "Walk the caller through disputing a charge on their statement.",
              "target": { "kind": "dialogue", "label": "Dispute" },
              "entry": {
                "mode": "llm",
                "label": "Wants to dispute a charge",
                "description": "",
                "alwaysPick": false,
                "conditions": []
              },
              "flow": {
                "nodes": [
                  { "id": "start", "type": "start", "position": { "x": 0, "y": 0 }, "data": {} },
                  {
                    "id": "66cbecac-8007-4be8-981c-26264801320f",
                    "type": "prompt",
                    "position": { "x": 0, "y": 160 },
                    "data": {
                      "name": "Collect charge details",
                      "prompt": "Ask for the date and amount of the charge the caller wants to dispute.",
                      "useStaticText": false,
                      "loopWhile": "",
                      "variables": [],
                      "useAudioExtraction": false,
                      "ignorePreviousExtractions": false,
                      "settings": {}
                    }
                  },
                  { "id": "end", "type": "end", "position": { "x": 0, "y": 320 }, "data": {} }
                ],
                "edges": [
                  { "id": "e-start-collect", "source": "start", "target": "66cbecac-8007-4be8-981c-26264801320f" },
                  { "id": "e-collect-end", "source": "66cbecac-8007-4be8-981c-26264801320f", "target": "end" }
                ]
              }
            }
          }
        }
      ]
    }
  ],
  "errors": null
}

{
  "data": {
    "groups": [
      {
        "agent_id": "b5154820-6f11-4886-8523-d896934528ae",
        "agent_name": "Appointment reminders",
        "scenarios": [ /* ... */ ]
      }
    ],
    "next_cursor": "b5154820-6f11-4886-8523-d896934528ae"
  },
  "errors": null
}

Docs for agents: llms.txt

⌘I

List Library Scenarios

curl --request GET \
  --url https://api.bland.ai/v2/agents/library/scenarios \
  --header 'authorization: <authorization>'

const options = {method: 'GET', headers: {authorization: '<authorization>'}};

fetch('https://api.bland.ai/v2/agents/library/scenarios', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bland.ai/v2/agents/library/scenarios",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bland.ai/v2/agents/library/scenarios"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v2/agents/library/scenarios")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "agent_id": "b5154820-6f11-4886-8523-d896934528ae",
      "agent_name": "Appointment reminders",
      "scenarios": [
        {
          "id": "00fa3bcf-56f5-45b9-8996-427d57b091b7",
          "name": "Reschedule appointment",
          "kind": "scenario",
          "description": "Help the caller move their appointment. Confirm the new date and time before ending.",
          "node": {
            "id": "00fa3bcf-56f5-45b9-8996-427d57b091b7",
            "type": "scenario",
            "position": { "x": -190, "y": 260 },
            "data": {
              "name": "Reschedule appointment",
              "rule": "Help the caller move their appointment. Confirm the new date and time before ending.",
              "target": { "kind": "dialogue", "label": "Reschedule" },
              "loopWhile": "",
              "variables": [
                {
                  "id": "7aeefed0-9806-400d-b2a7-96e6b58d1ac1",
                  "key": "new_appointment_time",
                  "value": "The date and time the caller agreed to",
                  "type": "string",
                  "accurateSpelling": false
                }
              ],
              "entry": {
                "mode": "llm",
                "label": "Wants to reschedule",
                "description": "",
                "alwaysPick": false,
                "conditions": []
              }
            }
          }
        }
      ]
    },
    {
      "agent_id": "2c5cbfa4-4d00-4b35-bd1b-195598f7d823",
      "agent_name": "Billing support",
      "scenarios": [
        {
          "id": "3c2be395-2d36-4437-833f-aacfc371a033",
          "name": "Dispute a charge",
          "kind": "complex-scenario",
          "description": "Walk the caller through disputing a charge on their statement.",
          "children": [
            {
              "id": "66cbecac-8007-4be8-981c-26264801320f",
              "name": "Collect charge details",
              "kind": "prompt"
            }
          ],
          "node": {
            "id": "3c2be395-2d36-4437-833f-aacfc371a033",
            "type": "complex-scenario",
            "position": { "x": 190, "y": 260 },
            "data": {
              "name": "Dispute a charge",
              "rule": "Walk the caller through disputing a charge on their statement.",
              "target": { "kind": "dialogue", "label": "Dispute" },
              "entry": {
                "mode": "llm",
                "label": "Wants to dispute a charge",
                "description": "",
                "alwaysPick": false,
                "conditions": []
              },
              "flow": {
                "nodes": [
                  { "id": "start", "type": "start", "position": { "x": 0, "y": 0 }, "data": {} },
                  {
                    "id": "66cbecac-8007-4be8-981c-26264801320f",
                    "type": "prompt",
                    "position": { "x": 0, "y": 160 },
                    "data": {
                      "name": "Collect charge details",
                      "prompt": "Ask for the date and amount of the charge the caller wants to dispute.",
                      "useStaticText": false,
                      "loopWhile": "",
                      "variables": [],
                      "useAudioExtraction": false,
                      "ignorePreviousExtractions": false,
                      "settings": {}
                    }
                  },
                  { "id": "end", "type": "end", "position": { "x": 0, "y": 320 }, "data": {} }
                ],
                "edges": [
                  { "id": "e-start-collect", "source": "start", "target": "66cbecac-8007-4be8-981c-26264801320f" },
                  { "id": "e-collect-end", "source": "66cbecac-8007-4be8-981c-26264801320f", "target": "end" }
                ]
              }
            }
          }
        }
      ]
    }
  ],
  "errors": null
}

{
  "data": {
    "groups": [
      {
        "agent_id": "b5154820-6f11-4886-8523-d896934528ae",
        "agent_name": "Appointment reminders",
        "scenarios": [ /* ... */ ]
      }
    ],
    "next_cursor": "b5154820-6f11-4886-8523-d896934528ae"
  },
  "errors": null
}

Get Started

Calls

Agents

Versions

Identity

Environments and Releases

Branches

Variables

Checks

Experiments

Dispositions

Library

Migration

Knowledge Bases

Numbers

Blocked Numbers

Widgets

Tools

Contacts

Memory

Agent Testing

Evals

Guard Rails

Live Translation

Custom Twilio Accounts

Batches

Prompts

Account

API Keys

Organizations

Messaging

SIP Trunks

Custom Dialing Pools

Triage

Legacy

List Library Scenarios

Overview

Headers

Query Parameters

Response