Update Disposition Draft
curl --request PATCH \
--url https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/draft \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"expectedDraftRevision": 123,
"definition": {
"name": "<string>",
"description": "<string>",
"timing": "<string>",
"values": [
{}
],
"values[].id": "<string>",
"values[].key": "<string>",
"values[].label": "<string>",
"values[].schema": {},
"values[].source": {},
"values[].source.kind": "<string>",
"values[].source.variableKey": "<string>",
"values[].source.execution": {},
"values[].source.extractorId": "<string>",
"values[].source.extractorVersionId": "<string>",
"values[].source.frozen": {},
"values[].source.judgeId": "<string>",
"values[].source.judgeVersionId": "<string>",
"values[].source.snippetId": "<string>",
"values[].source.snippetVersion": 123,
"values[].source.timeoutSeconds": 123,
"values[].source.connections": {},
"values[].source.secrets": {},
"values[].source.dependencyValueIds": [
{}
],
"transformation": {},
"postCallWebhook": {}
}
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/draft"
payload = {
"expectedDraftRevision": 123,
"definition": {
"name": "<string>",
"description": "<string>",
"timing": "<string>",
"values": [{}],
"values[].id": "<string>",
"values[].key": "<string>",
"values[].label": "<string>",
"values[].schema": {},
"values[].source": {},
"values[].source.kind": "<string>",
"values[].source.variableKey": "<string>",
"values[].source.execution": {},
"values[].source.extractorId": "<string>",
"values[].source.extractorVersionId": "<string>",
"values[].source.frozen": {},
"values[].source.judgeId": "<string>",
"values[].source.judgeVersionId": "<string>",
"values[].source.snippetId": "<string>",
"values[].source.snippetVersion": 123,
"values[].source.timeoutSeconds": 123,
"values[].source.connections": {},
"values[].source.secrets": {},
"values[].source.dependencyValueIds": [{}],
"transformation": {},
"postCallWebhook": {}
}
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
expectedDraftRevision: 123,
definition: {
name: '<string>',
description: '<string>',
timing: '<string>',
values: [{}],
'values[].id': '<string>',
'values[].key': '<string>',
'values[].label': '<string>',
'values[].schema': {},
'values[].source': {},
'values[].source.kind': '<string>',
'values[].source.variableKey': '<string>',
'values[].source.execution': {},
'values[].source.extractorId': '<string>',
'values[].source.extractorVersionId': '<string>',
'values[].source.frozen': {},
'values[].source.judgeId': '<string>',
'values[].source.judgeVersionId': '<string>',
'values[].source.snippetId': '<string>',
'values[].source.snippetVersion': 123,
'values[].source.timeoutSeconds': 123,
'values[].source.connections': {},
'values[].source.secrets': {},
'values[].source.dependencyValueIds': [{}],
transformation: {},
postCallWebhook: {}
}
})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/draft', 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}/draft",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'expectedDraftRevision' => 123,
'definition' => [
'name' => '<string>',
'description' => '<string>',
'timing' => '<string>',
'values' => [
[
]
],
'values[].id' => '<string>',
'values[].key' => '<string>',
'values[].label' => '<string>',
'values[].schema' => [
],
'values[].source' => [
],
'values[].source.kind' => '<string>',
'values[].source.variableKey' => '<string>',
'values[].source.execution' => [
],
'values[].source.extractorId' => '<string>',
'values[].source.extractorVersionId' => '<string>',
'values[].source.frozen' => [
],
'values[].source.judgeId' => '<string>',
'values[].source.judgeVersionId' => '<string>',
'values[].source.snippetId' => '<string>',
'values[].source.snippetVersion' => 123,
'values[].source.timeoutSeconds' => 123,
'values[].source.connections' => [
],
'values[].source.secrets' => [
],
'values[].source.dependencyValueIds' => [
[
]
],
'transformation' => [
],
'postCallWebhook' => [
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/draft"
payload := strings.NewReader("{\n \"expectedDraftRevision\": 123,\n \"definition\": {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"timing\": \"<string>\",\n \"values\": [\n {}\n ],\n \"values[].id\": \"<string>\",\n \"values[].key\": \"<string>\",\n \"values[].label\": \"<string>\",\n \"values[].schema\": {},\n \"values[].source\": {},\n \"values[].source.kind\": \"<string>\",\n \"values[].source.variableKey\": \"<string>\",\n \"values[].source.execution\": {},\n \"values[].source.extractorId\": \"<string>\",\n \"values[].source.extractorVersionId\": \"<string>\",\n \"values[].source.frozen\": {},\n \"values[].source.judgeId\": \"<string>\",\n \"values[].source.judgeVersionId\": \"<string>\",\n \"values[].source.snippetId\": \"<string>\",\n \"values[].source.snippetVersion\": 123,\n \"values[].source.timeoutSeconds\": 123,\n \"values[].source.connections\": {},\n \"values[].source.secrets\": {},\n \"values[].source.dependencyValueIds\": [\n {}\n ],\n \"transformation\": {},\n \"postCallWebhook\": {}\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/draft")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"expectedDraftRevision\": 123,\n \"definition\": {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"timing\": \"<string>\",\n \"values\": [\n {}\n ],\n \"values[].id\": \"<string>\",\n \"values[].key\": \"<string>\",\n \"values[].label\": \"<string>\",\n \"values[].schema\": {},\n \"values[].source\": {},\n \"values[].source.kind\": \"<string>\",\n \"values[].source.variableKey\": \"<string>\",\n \"values[].source.execution\": {},\n \"values[].source.extractorId\": \"<string>\",\n \"values[].source.extractorVersionId\": \"<string>\",\n \"values[].source.frozen\": {},\n \"values[].source.judgeId\": \"<string>\",\n \"values[].source.judgeVersionId\": \"<string>\",\n \"values[].source.snippetId\": \"<string>\",\n \"values[].source.snippetVersion\": 123,\n \"values[].source.timeoutSeconds\": 123,\n \"values[].source.connections\": {},\n \"values[].source.secrets\": {},\n \"values[].source.dependencyValueIds\": [\n {}\n ],\n \"transformation\": {},\n \"postCallWebhook\": {}\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/draft")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"expectedDraftRevision\": 123,\n \"definition\": {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"timing\": \"<string>\",\n \"values\": [\n {}\n ],\n \"values[].id\": \"<string>\",\n \"values[].key\": \"<string>\",\n \"values[].label\": \"<string>\",\n \"values[].schema\": {},\n \"values[].source\": {},\n \"values[].source.kind\": \"<string>\",\n \"values[].source.variableKey\": \"<string>\",\n \"values[].source.execution\": {},\n \"values[].source.extractorId\": \"<string>\",\n \"values[].source.extractorVersionId\": \"<string>\",\n \"values[].source.frozen\": {},\n \"values[].source.judgeId\": \"<string>\",\n \"values[].source.judgeVersionId\": \"<string>\",\n \"values[].source.snippetId\": \"<string>\",\n \"values[].source.snippetVersion\": 123,\n \"values[].source.timeoutSeconds\": 123,\n \"values[].source.connections\": {},\n \"values[].source.secrets\": {},\n \"values[].source.dependencyValueIds\": [\n {}\n ],\n \"transformation\": {},\n \"postCallWebhook\": {}\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"dispositionId": "70195e6f-b0b5-4ade-b851-2a2f25dcbde0",
"revision": 4,
"baseVersionId": "9cf8e056-0ffa-4acf-853e-c37ecaaa7e64",
"definition": {
"name": "Appointment outcome",
"description": "Did the caller book an appointment?",
"timing": "within_24h",
"values": [
{
"id": "59ef1515-aa81-4010-bd61-790abdebe92f",
"key": "callback_window",
"label": "Requested callback window",
"schema": { "kind": "string", "description": "Preferred callback time in the caller's words" },
"source": {
"kind": "structured_extraction",
"extractorId": "cf3403ca-16af-4e5e-ad76-e4c044e6611e",
"extractorVersionId": "af6ec0dc-ebf5-47a8-bf8c-4b114cd90ddf",
"execution": { "reasoningEffort": "medium", "inputSourceIds": ["transcript"] }
}
}
],
"transformation": {
"version": 1,
"root": {
"kind": "object",
"fields": {
"callback_window": { "kind": "value", "valueId": "59ef1515-aa81-4010-bd61-790abdebe92f" }
}
}
},
"postCallWebhook": { "mode": "emit_followup" }
}
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "Invalid request body",
"ext": "{\"errors\":[\"/expectedDraftRevision: Expected required property\"]}"
}
]
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "Definition failed validation",
"ext": "{\"problems\":[{\"valueId\":\"59ef1515-aa81-4010-bd61-790abdebe92f\",\"message\":\"Disposition value schema must exactly match the pinned extractor output schema\"}]}"
}
]
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "Draft revision moved (expected 3) — reload and reapply your change"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Disposition not found"
}
]
}
Dispositions
Update Disposition Draft
Replace a disposition’s draft definition.
PATCH
/
v2
/
agents
/
{agent_id}
/
dispositions
/
{disposition_id}
/
draft
Update Disposition Draft
curl --request PATCH \
--url https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/draft \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"expectedDraftRevision": 123,
"definition": {
"name": "<string>",
"description": "<string>",
"timing": "<string>",
"values": [
{}
],
"values[].id": "<string>",
"values[].key": "<string>",
"values[].label": "<string>",
"values[].schema": {},
"values[].source": {},
"values[].source.kind": "<string>",
"values[].source.variableKey": "<string>",
"values[].source.execution": {},
"values[].source.extractorId": "<string>",
"values[].source.extractorVersionId": "<string>",
"values[].source.frozen": {},
"values[].source.judgeId": "<string>",
"values[].source.judgeVersionId": "<string>",
"values[].source.snippetId": "<string>",
"values[].source.snippetVersion": 123,
"values[].source.timeoutSeconds": 123,
"values[].source.connections": {},
"values[].source.secrets": {},
"values[].source.dependencyValueIds": [
{}
],
"transformation": {},
"postCallWebhook": {}
}
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/draft"
payload = {
"expectedDraftRevision": 123,
"definition": {
"name": "<string>",
"description": "<string>",
"timing": "<string>",
"values": [{}],
"values[].id": "<string>",
"values[].key": "<string>",
"values[].label": "<string>",
"values[].schema": {},
"values[].source": {},
"values[].source.kind": "<string>",
"values[].source.variableKey": "<string>",
"values[].source.execution": {},
"values[].source.extractorId": "<string>",
"values[].source.extractorVersionId": "<string>",
"values[].source.frozen": {},
"values[].source.judgeId": "<string>",
"values[].source.judgeVersionId": "<string>",
"values[].source.snippetId": "<string>",
"values[].source.snippetVersion": 123,
"values[].source.timeoutSeconds": 123,
"values[].source.connections": {},
"values[].source.secrets": {},
"values[].source.dependencyValueIds": [{}],
"transformation": {},
"postCallWebhook": {}
}
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
expectedDraftRevision: 123,
definition: {
name: '<string>',
description: '<string>',
timing: '<string>',
values: [{}],
'values[].id': '<string>',
'values[].key': '<string>',
'values[].label': '<string>',
'values[].schema': {},
'values[].source': {},
'values[].source.kind': '<string>',
'values[].source.variableKey': '<string>',
'values[].source.execution': {},
'values[].source.extractorId': '<string>',
'values[].source.extractorVersionId': '<string>',
'values[].source.frozen': {},
'values[].source.judgeId': '<string>',
'values[].source.judgeVersionId': '<string>',
'values[].source.snippetId': '<string>',
'values[].source.snippetVersion': 123,
'values[].source.timeoutSeconds': 123,
'values[].source.connections': {},
'values[].source.secrets': {},
'values[].source.dependencyValueIds': [{}],
transformation: {},
postCallWebhook: {}
}
})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/draft', 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}/draft",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'expectedDraftRevision' => 123,
'definition' => [
'name' => '<string>',
'description' => '<string>',
'timing' => '<string>',
'values' => [
[
]
],
'values[].id' => '<string>',
'values[].key' => '<string>',
'values[].label' => '<string>',
'values[].schema' => [
],
'values[].source' => [
],
'values[].source.kind' => '<string>',
'values[].source.variableKey' => '<string>',
'values[].source.execution' => [
],
'values[].source.extractorId' => '<string>',
'values[].source.extractorVersionId' => '<string>',
'values[].source.frozen' => [
],
'values[].source.judgeId' => '<string>',
'values[].source.judgeVersionId' => '<string>',
'values[].source.snippetId' => '<string>',
'values[].source.snippetVersion' => 123,
'values[].source.timeoutSeconds' => 123,
'values[].source.connections' => [
],
'values[].source.secrets' => [
],
'values[].source.dependencyValueIds' => [
[
]
],
'transformation' => [
],
'postCallWebhook' => [
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/draft"
payload := strings.NewReader("{\n \"expectedDraftRevision\": 123,\n \"definition\": {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"timing\": \"<string>\",\n \"values\": [\n {}\n ],\n \"values[].id\": \"<string>\",\n \"values[].key\": \"<string>\",\n \"values[].label\": \"<string>\",\n \"values[].schema\": {},\n \"values[].source\": {},\n \"values[].source.kind\": \"<string>\",\n \"values[].source.variableKey\": \"<string>\",\n \"values[].source.execution\": {},\n \"values[].source.extractorId\": \"<string>\",\n \"values[].source.extractorVersionId\": \"<string>\",\n \"values[].source.frozen\": {},\n \"values[].source.judgeId\": \"<string>\",\n \"values[].source.judgeVersionId\": \"<string>\",\n \"values[].source.snippetId\": \"<string>\",\n \"values[].source.snippetVersion\": 123,\n \"values[].source.timeoutSeconds\": 123,\n \"values[].source.connections\": {},\n \"values[].source.secrets\": {},\n \"values[].source.dependencyValueIds\": [\n {}\n ],\n \"transformation\": {},\n \"postCallWebhook\": {}\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/draft")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"expectedDraftRevision\": 123,\n \"definition\": {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"timing\": \"<string>\",\n \"values\": [\n {}\n ],\n \"values[].id\": \"<string>\",\n \"values[].key\": \"<string>\",\n \"values[].label\": \"<string>\",\n \"values[].schema\": {},\n \"values[].source\": {},\n \"values[].source.kind\": \"<string>\",\n \"values[].source.variableKey\": \"<string>\",\n \"values[].source.execution\": {},\n \"values[].source.extractorId\": \"<string>\",\n \"values[].source.extractorVersionId\": \"<string>\",\n \"values[].source.frozen\": {},\n \"values[].source.judgeId\": \"<string>\",\n \"values[].source.judgeVersionId\": \"<string>\",\n \"values[].source.snippetId\": \"<string>\",\n \"values[].source.snippetVersion\": 123,\n \"values[].source.timeoutSeconds\": 123,\n \"values[].source.connections\": {},\n \"values[].source.secrets\": {},\n \"values[].source.dependencyValueIds\": [\n {}\n ],\n \"transformation\": {},\n \"postCallWebhook\": {}\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/draft")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"expectedDraftRevision\": 123,\n \"definition\": {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"timing\": \"<string>\",\n \"values\": [\n {}\n ],\n \"values[].id\": \"<string>\",\n \"values[].key\": \"<string>\",\n \"values[].label\": \"<string>\",\n \"values[].schema\": {},\n \"values[].source\": {},\n \"values[].source.kind\": \"<string>\",\n \"values[].source.variableKey\": \"<string>\",\n \"values[].source.execution\": {},\n \"values[].source.extractorId\": \"<string>\",\n \"values[].source.extractorVersionId\": \"<string>\",\n \"values[].source.frozen\": {},\n \"values[].source.judgeId\": \"<string>\",\n \"values[].source.judgeVersionId\": \"<string>\",\n \"values[].source.snippetId\": \"<string>\",\n \"values[].source.snippetVersion\": 123,\n \"values[].source.timeoutSeconds\": 123,\n \"values[].source.connections\": {},\n \"values[].source.secrets\": {},\n \"values[].source.dependencyValueIds\": [\n {}\n ],\n \"transformation\": {},\n \"postCallWebhook\": {}\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"dispositionId": "70195e6f-b0b5-4ade-b851-2a2f25dcbde0",
"revision": 4,
"baseVersionId": "9cf8e056-0ffa-4acf-853e-c37ecaaa7e64",
"definition": {
"name": "Appointment outcome",
"description": "Did the caller book an appointment?",
"timing": "within_24h",
"values": [
{
"id": "59ef1515-aa81-4010-bd61-790abdebe92f",
"key": "callback_window",
"label": "Requested callback window",
"schema": { "kind": "string", "description": "Preferred callback time in the caller's words" },
"source": {
"kind": "structured_extraction",
"extractorId": "cf3403ca-16af-4e5e-ad76-e4c044e6611e",
"extractorVersionId": "af6ec0dc-ebf5-47a8-bf8c-4b114cd90ddf",
"execution": { "reasoningEffort": "medium", "inputSourceIds": ["transcript"] }
}
}
],
"transformation": {
"version": 1,
"root": {
"kind": "object",
"fields": {
"callback_window": { "kind": "value", "valueId": "59ef1515-aa81-4010-bd61-790abdebe92f" }
}
}
},
"postCallWebhook": { "mode": "emit_followup" }
}
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "Invalid request body",
"ext": "{\"errors\":[\"/expectedDraftRevision: Expected required property\"]}"
}
]
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "Definition failed validation",
"ext": "{\"problems\":[{\"valueId\":\"59ef1515-aa81-4010-bd61-790abdebe92f\",\"message\":\"Disposition value schema must exactly match the pinned extractor output schema\"}]}"
}
]
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "Draft revision moved (expected 3) — reload and reapply your change"
}
]
}
{
"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.revision you read from Get Disposition Draft as expectedDraftRevision, and the call returns 409 if someone else saved first. Editing the draft never affects the published version or calls already running; publish with Publish Disposition to make changes live.
Requires an admin, owner, operator, or prompter role.
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.Body Parameters
Unknown fields anywhere in the body are rejected. This is a full replacement, not a merge: every field ofdefinition must be present.
integer
required
The draft revision you last read, at least
1. If the live revision differs, nothing is written and the call returns 409 CONFLICT. On success the revision becomes expectedDraftRevision + 1.object
required
The complete replacement definition. Schema violations return
400 BAD_REQUEST with message Invalid request body and an ext string listing each failing path. Rule violations return 400 BAD_REQUEST with message Definition failed validation and an ext string carrying problems, each with valueId and message. Drafts are validated less strictly than publishing: a structured_extraction value may omit its version pin, and judge or extractor pins may still be editable.Show definition object
Show definition object
string
required
Display name, 1 to 120 characters.
string
required
Free-text description, up to 2000 characters. May be empty.
string
required
immediate runs within 30 minutes of call completion. within_24h queues the run with a 24-hour deadline.array
required
Up to 50 value objects. Each value produces one field of the result. Value
ids and keys must be unique within the definition. A definition with no values can be saved but not published or tested.string
required
A UUID you generate. It is the value’s permanent identity: results, corrections, and the transformation all refer to it. Keep existing ids stable when editing so history stays attached.
string
required
Payload field name, 1 to 64 characters matching
^[a-z][a-z0-9_]*$. May change between drafts.string
required
Human-readable label, 1 to 120 characters.
object
required
The value’s output shape.
kind is one of boolean, string, number, enum, array, or object; every kind accepts an optional description up to 2000 characters. string accepts format: "date-time". enum requires options: 1 to 24 entries of { "key", "label" } with key 1 to 64 characters, label 1 to 120, and keys unique. array requires items (a nested schema) and accepts minItems (at least 0) and maxItems (at least 1); neither may exceed 1000 and minItems may not exceed maxItems. object requires properties (a map of names up to 64 characters to nested schemas, at most 64 of them) and required (unique names that all appear in properties). A schema may not exceed 200 nodes, 8 levels of nesting, or 64 KB.object
required
How the value is produced.
kind selects one of four shapes; the fields for each kind are listed below. A judge value’s schema must be boolean or an enum whose keys exactly match the judge’s level keys (a pass/fail judge maps to boolean or a two-option pass and fail enum). A structured_extraction value’s schema must exactly match the pinned extractor’s output schema. A variable_extraction value’s schema must exactly match the outputSchema of the matching entry in Get Variable Catalog.string
required
One of
variable_extraction, structured_extraction, judge, or custom_code.string
variable_extraction only, required. Key of an existing variable on the agent, 1 to 128 characters matching ^[A-Za-z_][A-Za-z0-9_.-]{0,127}$. The variable must exist in the agent’s current configuration.object
For
variable_extraction, optional { "reasoningEffort" } defaulting to auto. For structured_extraction and judge, required { "reasoningEffort", "inputSourceIds" }. reasoningEffort is auto, low, medium, or high. inputSourceIds is 1 to 8 of transcript, audio_recording, call_metadata, pathway_logs, tool_logs, variables, agent_config, call_config. An audio judge must include audio_recording. A structured extraction cannot combine low effort with audio_recording.string
structured_extraction only, required. UUID of an extractor from List Extractors that is org-wide or scoped to this agent.string
structured_extraction only. UUID of a version of that extractor. Optional while drafting; required to publish or run a test, and publish requires a published (archived) version.object
structured_extraction only. Written by the server at publish time with a copy of the pinned extractor’s prompt, output schema, and inference configuration. You may echo back the copy you read from the draft or omit it; publish rewrites it either way.string
judge only, required. UUID of a judge from Get Judge Catalog that is org-wide or scoped to this agent.string
judge only, required. UUID of a version of that judge. Publish and test runs require a published (archived) version; a draft may temporarily reference an editable one.string
custom_code only, required. UUID of a code snippet owned by your organization. The snippet must be JavaScript.integer
custom_code only, required. Snippet version number, at least 1.integer
custom_code only, required. 1 to 60.object
custom_code only, required (may be {}). Up to 20 entries keyed by an alias matching ^[A-Za-z_][A-Za-z0-9_]{0,63}$, each { "resourceId": "uuid", "integration": "optional string" }. Resources must belong to your organization.object
custom_code only, required (may be {}). Up to 20 entries keyed by an alias with the same pattern, each { "secretId": "uuid" }.array
custom_code only, required (may be []). Up to 20 unique value ids whose results are passed to the code. Only variable_extraction, structured_extraction, and judge values may be referenced; a code value cannot depend on itself or on another code value.object
required
{ "version": 1, "root": node }. A node is one of { "kind": "value", "valueId" }, { "kind": "literal", "value" }, { "kind": "object", "fields": { name: node } } with names up to 64 characters, or { "kind": "array", "items": [node] } with up to 50 items. Every referenced valueId must exist in values. At most 2000 nodes.object
required
{ "mode": "hold" } or { "mode": "emit_followup" }. hold is only valid with timing: "immediate".Response
string
The disposition this draft belongs to.
number
The new draft revision,
expectedDraftRevision + 1.string | null
The most recently published version, or
null if never published.object
The saved definition, as stored.
null | array
null on success, or a list of error objects if the request failed.{
"data": {
"dispositionId": "70195e6f-b0b5-4ade-b851-2a2f25dcbde0",
"revision": 4,
"baseVersionId": "9cf8e056-0ffa-4acf-853e-c37ecaaa7e64",
"definition": {
"name": "Appointment outcome",
"description": "Did the caller book an appointment?",
"timing": "within_24h",
"values": [
{
"id": "59ef1515-aa81-4010-bd61-790abdebe92f",
"key": "callback_window",
"label": "Requested callback window",
"schema": { "kind": "string", "description": "Preferred callback time in the caller's words" },
"source": {
"kind": "structured_extraction",
"extractorId": "cf3403ca-16af-4e5e-ad76-e4c044e6611e",
"extractorVersionId": "af6ec0dc-ebf5-47a8-bf8c-4b114cd90ddf",
"execution": { "reasoningEffort": "medium", "inputSourceIds": ["transcript"] }
}
}
],
"transformation": {
"version": 1,
"root": {
"kind": "object",
"fields": {
"callback_window": { "kind": "value", "valueId": "59ef1515-aa81-4010-bd61-790abdebe92f" }
}
}
},
"postCallWebhook": { "mode": "emit_followup" }
}
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "Invalid request body",
"ext": "{\"errors\":[\"/expectedDraftRevision: Expected required property\"]}"
}
]
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "Definition failed validation",
"ext": "{\"problems\":[{\"valueId\":\"59ef1515-aa81-4010-bd61-790abdebe92f\",\"message\":\"Disposition value schema must exactly match the pinned extractor output schema\"}]}"
}
]
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "Draft revision moved (expected 3) — reload and reapply your change"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Disposition not found"
}
]
}
Docs for agents: llms.txt
Was this page helpful?