List Disposition Versions

GET

agents

{agent_id}

dispositions

{disposition_id}

versions

List Disposition Versions

curl --request GET \
  --url https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/versions \
  --header 'authorization: <authorization>'

import requests

url = "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/versions"

headers = {"authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

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

fetch('https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/versions', 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/{agent_id}/dispositions/{disposition_id}/versions",
  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/{agent_id}/dispositions/{disposition_id}/versions"

	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/{agent_id}/dispositions/{disposition_id}/versions")

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": {
    "versions": [
      {
        "id": "af219236-2cf3-44dc-b0d8-52f312ca1ca9",
        "dispositionId": "36c8c6ea-ab36-4510-97b7-59506262bd46",
        "versionNumber": 2,
        "definition": {
          "name": "Appointment outcome",
          "description": "Did the caller book an appointment?",
          "timing": "immediate",
          "values": [
            {
              "id": "1e3731a3-03fa-4e75-a292-03a87b06b1a8",
              "key": "booked",
              "label": "Appointment booked",
              "schema": { "kind": "boolean" },
              "source": {
                "kind": "judge",
                "judgeId": "06bf4d35-15f7-4fc3-a707-0f2bef6a21b2",
                "judgeVersionId": "a1579eb4-41f6-4b43-beb1-8c73b203cb63",
                "execution": { "reasoningEffort": "auto", "inputSourceIds": ["transcript"] }
              }
            }
          ],
          "transformation": {
            "version": 1,
            "root": {
              "kind": "object",
              "fields": {
                "booked": { "kind": "value", "valueId": "1e3731a3-03fa-4e75-a292-03a87b06b1a8" }
              }
            }
          },
          "postCallWebhook": { "mode": "emit_followup" }
        },
        "publishedAt": "2026-09-09T11:47:52.903Z"
      },
      {
        "id": "6df49c21-73c0-4217-862d-453a0edd82b1",
        "dispositionId": "36c8c6ea-ab36-4510-97b7-59506262bd46",
        "versionNumber": 1,
        "definition": {
          "name": "Appointment outcome",
          "description": "",
          "timing": "immediate",
          "values": [
            {
              "id": "1e3731a3-03fa-4e75-a292-03a87b06b1a8",
              "key": "booked",
              "label": "Appointment booked",
              "schema": { "kind": "boolean" },
              "source": {
                "kind": "judge",
                "judgeId": "06bf4d35-15f7-4fc3-a707-0f2bef6a21b2",
                "judgeVersionId": "a1579eb4-41f6-4b43-beb1-8c73b203cb63",
                "execution": { "reasoningEffort": "auto", "inputSourceIds": ["transcript"] }
              }
            }
          ],
          "transformation": {
            "version": 1,
            "root": { "kind": "value", "valueId": "1e3731a3-03fa-4e75-a292-03a87b06b1a8" }
          },
          "postCallWebhook": { "mode": "emit_followup" }
        },
        "publishedAt": "2026-09-02T16:05:19.334Z"
      }
    ],
    "nextCursor": null
  },
  "errors": null
}

{
  "data": null,
  "errors": [
    {
      "error": "BAD_REQUEST",
      "message": "beforeVersion must be a positive safe integer"
    }
  ]
}

{
  "data": null,
  "errors": [
    {
      "error": "NOT_FOUND",
      "message": "Disposition not found"
    }
  ]
}

Overview

Dispositions are enabled per organization. If your organization does not have access, these endpoints return 404.

Returns the immutable versions created by Publish Disposition, highest versionNumber first, 25 per page. Page backwards with beforeVersion. Each entry carries the full frozen definition; fetch a single one with Get Disposition Version.

Headers

string

required

Your API key for authentication.

Path Parameters

string

required

The agent’s unique identifier. Must be a UUID; otherwise returns 400 with the message agentId must be a valid UUID. Returns 404 Agent not found if the agent is not in your organization.

string

required

The disposition’s unique identifier. Must be a UUID; otherwise returns 400 with the message dispositionId must be a valid UUID. Returns 404 Disposition not found if it does not belong to this agent.

Query Parameters

integer

Cursor for the next page: return only versions with versionNumber strictly less than this value. Use the nextCursor from the previous response. Must be a positive integer; otherwise returns 400 with the message beforeVersion must be a positive safe integer.

Response

array

Up to 25 version objects, ordered by versionNumber descending.

Show version object

string

Unique identifier for the version. Pass it as {version_id} to Get Disposition Version.

string

The disposition this version belongs to.

number

Sequential number starting at 1, unique per disposition.

object

The frozen definition, same shape as the definition body parameter of Create Disposition. structured_extraction sources carry the server-written frozen copy of the extractor prompt, output schema, and inference configuration that this version executes; inferenceConfig.modelProfileKey, when present, is one of balanced, fast, or high_accuracy.

string

ISO 8601 timestamp of publication.

number | null

The versionNumber to pass as beforeVersion for the next page, or null when there are no older versions.

null | array

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

{
  "data": {
    "versions": [
      {
        "id": "af219236-2cf3-44dc-b0d8-52f312ca1ca9",
        "dispositionId": "36c8c6ea-ab36-4510-97b7-59506262bd46",
        "versionNumber": 2,
        "definition": {
          "name": "Appointment outcome",
          "description": "Did the caller book an appointment?",
          "timing": "immediate",
          "values": [
            {
              "id": "1e3731a3-03fa-4e75-a292-03a87b06b1a8",
              "key": "booked",
              "label": "Appointment booked",
              "schema": { "kind": "boolean" },
              "source": {
                "kind": "judge",
                "judgeId": "06bf4d35-15f7-4fc3-a707-0f2bef6a21b2",
                "judgeVersionId": "a1579eb4-41f6-4b43-beb1-8c73b203cb63",
                "execution": { "reasoningEffort": "auto", "inputSourceIds": ["transcript"] }
              }
            }
          ],
          "transformation": {
            "version": 1,
            "root": {
              "kind": "object",
              "fields": {
                "booked": { "kind": "value", "valueId": "1e3731a3-03fa-4e75-a292-03a87b06b1a8" }
              }
            }
          },
          "postCallWebhook": { "mode": "emit_followup" }
        },
        "publishedAt": "2026-09-09T11:47:52.903Z"
      },
      {
        "id": "6df49c21-73c0-4217-862d-453a0edd82b1",
        "dispositionId": "36c8c6ea-ab36-4510-97b7-59506262bd46",
        "versionNumber": 1,
        "definition": {
          "name": "Appointment outcome",
          "description": "",
          "timing": "immediate",
          "values": [
            {
              "id": "1e3731a3-03fa-4e75-a292-03a87b06b1a8",
              "key": "booked",
              "label": "Appointment booked",
              "schema": { "kind": "boolean" },
              "source": {
                "kind": "judge",
                "judgeId": "06bf4d35-15f7-4fc3-a707-0f2bef6a21b2",
                "judgeVersionId": "a1579eb4-41f6-4b43-beb1-8c73b203cb63",
                "execution": { "reasoningEffort": "auto", "inputSourceIds": ["transcript"] }
              }
            }
          ],
          "transformation": {
            "version": 1,
            "root": { "kind": "value", "valueId": "1e3731a3-03fa-4e75-a292-03a87b06b1a8" }
          },
          "postCallWebhook": { "mode": "emit_followup" }
        },
        "publishedAt": "2026-09-02T16:05:19.334Z"
      }
    ],
    "nextCursor": null
  },
  "errors": null
}

{
  "data": null,
  "errors": [
    {
      "error": "BAD_REQUEST",
      "message": "beforeVersion must be a positive safe integer"
    }
  ]
}

{
  "data": null,
  "errors": [
    {
      "error": "NOT_FOUND",
      "message": "Disposition not found"
    }
  ]
}

Docs for agents: llms.txt

⌘I

List Disposition Versions

curl --request GET \
  --url https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/versions \
  --header 'authorization: <authorization>'

import requests

url = "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/versions"

headers = {"authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

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

fetch('https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/versions', 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/{agent_id}/dispositions/{disposition_id}/versions",
  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/{agent_id}/dispositions/{disposition_id}/versions"

	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/{agent_id}/dispositions/{disposition_id}/versions")

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": {
    "versions": [
      {
        "id": "af219236-2cf3-44dc-b0d8-52f312ca1ca9",
        "dispositionId": "36c8c6ea-ab36-4510-97b7-59506262bd46",
        "versionNumber": 2,
        "definition": {
          "name": "Appointment outcome",
          "description": "Did the caller book an appointment?",
          "timing": "immediate",
          "values": [
            {
              "id": "1e3731a3-03fa-4e75-a292-03a87b06b1a8",
              "key": "booked",
              "label": "Appointment booked",
              "schema": { "kind": "boolean" },
              "source": {
                "kind": "judge",
                "judgeId": "06bf4d35-15f7-4fc3-a707-0f2bef6a21b2",
                "judgeVersionId": "a1579eb4-41f6-4b43-beb1-8c73b203cb63",
                "execution": { "reasoningEffort": "auto", "inputSourceIds": ["transcript"] }
              }
            }
          ],
          "transformation": {
            "version": 1,
            "root": {
              "kind": "object",
              "fields": {
                "booked": { "kind": "value", "valueId": "1e3731a3-03fa-4e75-a292-03a87b06b1a8" }
              }
            }
          },
          "postCallWebhook": { "mode": "emit_followup" }
        },
        "publishedAt": "2026-09-09T11:47:52.903Z"
      },
      {
        "id": "6df49c21-73c0-4217-862d-453a0edd82b1",
        "dispositionId": "36c8c6ea-ab36-4510-97b7-59506262bd46",
        "versionNumber": 1,
        "definition": {
          "name": "Appointment outcome",
          "description": "",
          "timing": "immediate",
          "values": [
            {
              "id": "1e3731a3-03fa-4e75-a292-03a87b06b1a8",
              "key": "booked",
              "label": "Appointment booked",
              "schema": { "kind": "boolean" },
              "source": {
                "kind": "judge",
                "judgeId": "06bf4d35-15f7-4fc3-a707-0f2bef6a21b2",
                "judgeVersionId": "a1579eb4-41f6-4b43-beb1-8c73b203cb63",
                "execution": { "reasoningEffort": "auto", "inputSourceIds": ["transcript"] }
              }
            }
          ],
          "transformation": {
            "version": 1,
            "root": { "kind": "value", "valueId": "1e3731a3-03fa-4e75-a292-03a87b06b1a8" }
          },
          "postCallWebhook": { "mode": "emit_followup" }
        },
        "publishedAt": "2026-09-02T16:05:19.334Z"
      }
    ],
    "nextCursor": null
  },
  "errors": null
}

{
  "data": null,
  "errors": [
    {
      "error": "BAD_REQUEST",
      "message": "beforeVersion must be a positive safe integer"
    }
  ]
}

{
  "data": null,
  "errors": [
    {
      "error": "NOT_FOUND",
      "message": "Disposition not found"
    }
  ]
}