Create Disposition
curl --request POST \
--url https://api.bland.ai/v2/agents/{agent_id}/dispositions \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"key": "<string>",
"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"
payload = {
"key": "<string>",
"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.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
key: '<string>',
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', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'key' => '<string>',
'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"
payload := strings.NewReader("{\n \"key\": \"<string>\",\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("POST", 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.post("https://api.bland.ai/v2/agents/{agent_id}/dispositions")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"key\": \"<string>\",\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")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"key\": \"<string>\",\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": {
"id": "cdc753be-4f30-454f-99bf-aec7ba366875",
"agentId": "7b72e5e3-362d-4b98-acd6-6929e9ed3995",
"key": "appointment_outcome",
"state": "disabled",
"publishedVersionId": null,
"publishedVersionNumber": null,
"draftRevision": 1,
"draftValueCount": 2,
"hasUnpublishedChanges": true,
"name": "Appointment outcome",
"description": "Did the caller book, and did they ask for a callback?",
"createdAt": "2026-09-10T18:02:11.418Z",
"updatedAt": "2026-09-10T18:02:11.418Z"
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "Invalid request body",
"ext": "{\"errors\":[\"/key: Expected string to match '^[a-z][a-z0-9_]*$'\"]}"
}
]
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "Definition failed validation",
"ext": "{\"problems\":[{\"valueId\":\"c60ed698-7680-4a76-8bf9-da4de408460b\",\"message\":\"Pinned judge version does not exist\"}]}"
}
]
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "A disposition with key \"appointment_outcome\" already exists"
}
]
}
Dispositions
Create Disposition
Create a disposition with an initial draft definition.
POST
/
v2
/
agents
/
{agent_id}
/
dispositions
Create Disposition
curl --request POST \
--url https://api.bland.ai/v2/agents/{agent_id}/dispositions \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"key": "<string>",
"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"
payload = {
"key": "<string>",
"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.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
key: '<string>',
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', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'key' => '<string>',
'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"
payload := strings.NewReader("{\n \"key\": \"<string>\",\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("POST", 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.post("https://api.bland.ai/v2/agents/{agent_id}/dispositions")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"key\": \"<string>\",\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")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"key\": \"<string>\",\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": {
"id": "cdc753be-4f30-454f-99bf-aec7ba366875",
"agentId": "7b72e5e3-362d-4b98-acd6-6929e9ed3995",
"key": "appointment_outcome",
"state": "disabled",
"publishedVersionId": null,
"publishedVersionNumber": null,
"draftRevision": 1,
"draftValueCount": 2,
"hasUnpublishedChanges": true,
"name": "Appointment outcome",
"description": "Did the caller book, and did they ask for a callback?",
"createdAt": "2026-09-10T18:02:11.418Z",
"updatedAt": "2026-09-10T18:02:11.418Z"
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "Invalid request body",
"ext": "{\"errors\":[\"/key: Expected string to match '^[a-z][a-z0-9_]*$'\"]}"
}
]
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "Definition failed validation",
"ext": "{\"problems\":[{\"valueId\":\"c60ed698-7680-4a76-8bf9-da4de408460b\",\"message\":\"Pinned judge version does not exist\"}]}"
}
]
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "A disposition with key \"appointment_outcome\" already exists"
}
]
}
Overview
Dispositions are enabled per organization. If your organization does not have access, these endpoints return
404.disabled and does not run on calls until you estimate and publish it. Edit the draft later with Update Disposition Draft.
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.Body Parameters
Unknown fields anywhere in the body are rejected.string
required
Stable slug for the disposition, 1 to 64 characters matching
^[a-z][a-z0-9_]*$. Unique per agent; returns 409 CONFLICT if another live disposition on this agent already uses it. Cannot be changed after creation.object
required
The full disposition definition. Schema violations return
400 BAD_REQUEST with message Invalid request body and an ext string listing each failing path. Rule violations (a judge pin that does not exist, a duplicate value key, a transformation that references an unknown value id) 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.{
"name": "Appointment outcome",
"description": "Did the caller book, and did they ask for a callback?",
"timing": "immediate",
"values": [
{
"id": "c60ed698-7680-4a76-8bf9-da4de408460b",
"key": "booked",
"label": "Appointment booked",
"schema": { "kind": "boolean" },
"source": {
"kind": "judge",
"judgeId": "3fec6d8e-053b-4d6b-9544-4bf559a13a1a",
"judgeVersionId": "f3a84fb2-81d9-41e7-95e3-3d1f7e44fb31",
"execution": { "reasoningEffort": "auto", "inputSourceIds": ["transcript"] }
}
},
{
"id": "e515708f-fa72-4786-90cd-3f4d3696ffcd",
"key": "callback_window",
"label": "Requested callback window",
"schema": { "kind": "string", "description": "Preferred callback time in the caller's words" },
"source": {
"kind": "structured_extraction",
"extractorId": "8986922b-f300-47c5-8c5d-f506d59c82ab",
"extractorVersionId": "8e503b95-67ca-4754-a058-d3ac7b88a217",
"execution": { "reasoningEffort": "medium", "inputSourceIds": ["transcript"] }
}
}
],
"transformation": {
"version": 1,
"root": {
"kind": "object",
"fields": {
"booked": { "kind": "value", "valueId": "c60ed698-7680-4a76-8bf9-da4de408460b" },
"callback_window": { "kind": "value", "valueId": "e515708f-fa72-4786-90cd-3f4d3696ffcd" }
}
}
},
"postCallWebhook": { "mode": "emit_followup" }
}
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 it stable across draft edits.
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’s extraction is re-run against the corrected post-call transcript. 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. Omit it.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 delays the call’s post-call webhook until this disposition’s results are ready and is only valid with timing: "immediate". emit_followup sends results in a separate follow-up webhook.Response
Returns201 on success.
object
The new disposition summary.
Show disposition object
Show disposition object
string
Unique identifier for the disposition.
string
The agent this disposition belongs to.
string
The slug you supplied.
string
Always
disabled on a new disposition.null
Always
null on a new disposition.null
Always
null on a new disposition.number
Always
1 on a new disposition. Pass it as expectedDraftRevision on the first draft update.number
Number of values in the definition you supplied.
boolean
Always
true on a new disposition.string
The definition’s name.
string
The definition’s description.
string
ISO 8601 timestamp of creation.
string
ISO 8601 timestamp of creation.
null | array
null on success, or a list of error objects if the request failed.{
"data": {
"id": "cdc753be-4f30-454f-99bf-aec7ba366875",
"agentId": "7b72e5e3-362d-4b98-acd6-6929e9ed3995",
"key": "appointment_outcome",
"state": "disabled",
"publishedVersionId": null,
"publishedVersionNumber": null,
"draftRevision": 1,
"draftValueCount": 2,
"hasUnpublishedChanges": true,
"name": "Appointment outcome",
"description": "Did the caller book, and did they ask for a callback?",
"createdAt": "2026-09-10T18:02:11.418Z",
"updatedAt": "2026-09-10T18:02:11.418Z"
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "Invalid request body",
"ext": "{\"errors\":[\"/key: Expected string to match '^[a-z][a-z0-9_]*$'\"]}"
}
]
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "Definition failed validation",
"ext": "{\"problems\":[{\"valueId\":\"c60ed698-7680-4a76-8bf9-da4de408460b\",\"message\":\"Pinned judge version does not exist\"}]}"
}
]
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "A disposition with key \"appointment_outcome\" already exists"
}
]
}
Docs for agents: llms.txt
Was this page helpful?