Update Disposition Extractor Draft
curl --request PATCH \
--url https://api.bland.ai/v2/agents/{agent_id}/dispositions/extractors/{extractor_id}/draft \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"expectedVersionId": "<string>",
"expectedDraftRevision": 123,
"name": "<string>",
"description": {},
"systemPromptMd": "<string>",
"promptMd": "<string>",
"outputSchema": {},
"inferenceConfig": {}
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/dispositions/extractors/{extractor_id}/draft"
payload = {
"expectedVersionId": "<string>",
"expectedDraftRevision": 123,
"name": "<string>",
"description": {},
"systemPromptMd": "<string>",
"promptMd": "<string>",
"outputSchema": {},
"inferenceConfig": {}
}
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({
expectedVersionId: '<string>',
expectedDraftRevision: 123,
name: '<string>',
description: {},
systemPromptMd: '<string>',
promptMd: '<string>',
outputSchema: {},
inferenceConfig: {}
})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/dispositions/extractors/{extractor_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/extractors/{extractor_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([
'expectedVersionId' => '<string>',
'expectedDraftRevision' => 123,
'name' => '<string>',
'description' => [
],
'systemPromptMd' => '<string>',
'promptMd' => '<string>',
'outputSchema' => [
],
'inferenceConfig' => [
]
]),
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/extractors/{extractor_id}/draft"
payload := strings.NewReader("{\n \"expectedVersionId\": \"<string>\",\n \"expectedDraftRevision\": 123,\n \"name\": \"<string>\",\n \"description\": {},\n \"systemPromptMd\": \"<string>\",\n \"promptMd\": \"<string>\",\n \"outputSchema\": {},\n \"inferenceConfig\": {}\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/extractors/{extractor_id}/draft")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"expectedVersionId\": \"<string>\",\n \"expectedDraftRevision\": 123,\n \"name\": \"<string>\",\n \"description\": {},\n \"systemPromptMd\": \"<string>\",\n \"promptMd\": \"<string>\",\n \"outputSchema\": {},\n \"inferenceConfig\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/dispositions/extractors/{extractor_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 \"expectedVersionId\": \"<string>\",\n \"expectedDraftRevision\": 123,\n \"name\": \"<string>\",\n \"description\": {},\n \"systemPromptMd\": \"<string>\",\n \"promptMd\": \"<string>\",\n \"outputSchema\": {},\n \"inferenceConfig\": {}\n}"
response = http.request(request)
puts response.read_body{
"data": {
"extractor": {
"id": "0f1f5c7b-3d6e-47b0-981b-d121f6853552",
"agentId": "a1250a05-0ae1-45ca-91e6-1ef7930f0093",
"key": "callback_window",
"name": "Callback window",
"description": "When the caller asked to be called back.",
"currentVersionId": "cc5a57dc-1f76-4007-a9ea-47378e50de0c",
"activeVersionId": null,
"draftRevision": 2,
"createdAt": "2026-09-08T10:21:37.902Z",
"updatedAt": "2026-09-10T17:05:12.446Z"
},
"currentVersion": {
"id": "cc5a57dc-1f76-4007-a9ea-47378e50de0c",
"extractorId": "0f1f5c7b-3d6e-47b0-981b-d121f6853552",
"versionNumber": 1,
"state": "editable",
"name": "Callback window",
"description": "When the caller asked to be called back.",
"systemPromptMd": "You extract scheduling details from customer service calls.",
"promptMd": "Find the day and time window the caller asked for a callback. Leave fields empty if the caller did not ask for one.",
"outputSchema": {
"kind": "object",
"properties": {
"requested": { "kind": "boolean", "description": "Whether the caller asked for a callback." },
"window_start": { "kind": "string", "format": "date-time" },
"window_end": { "kind": "string", "format": "date-time" }
},
"required": ["requested"]
},
"inferenceConfig": {
"modelProfileKey": "high_accuracy",
"temperature": 0,
"thinking": "medium",
"contextSources": ["transcript"]
},
"createdAt": "2026-09-08T10:21:37.902Z",
"updatedAt": "2026-09-10T17:05:12.446Z"
}
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "Extractor draft changed; refresh and try again"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Disposition extractor not found"
}
]
}
Extractors
Update Disposition Extractor Draft
Edit an extractor’s editable draft version.
PATCH
/
v2
/
agents
/
{agent_id}
/
dispositions
/
extractors
/
{extractor_id}
/
draft
Update Disposition Extractor Draft
curl --request PATCH \
--url https://api.bland.ai/v2/agents/{agent_id}/dispositions/extractors/{extractor_id}/draft \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"expectedVersionId": "<string>",
"expectedDraftRevision": 123,
"name": "<string>",
"description": {},
"systemPromptMd": "<string>",
"promptMd": "<string>",
"outputSchema": {},
"inferenceConfig": {}
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/dispositions/extractors/{extractor_id}/draft"
payload = {
"expectedVersionId": "<string>",
"expectedDraftRevision": 123,
"name": "<string>",
"description": {},
"systemPromptMd": "<string>",
"promptMd": "<string>",
"outputSchema": {},
"inferenceConfig": {}
}
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({
expectedVersionId: '<string>',
expectedDraftRevision: 123,
name: '<string>',
description: {},
systemPromptMd: '<string>',
promptMd: '<string>',
outputSchema: {},
inferenceConfig: {}
})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/dispositions/extractors/{extractor_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/extractors/{extractor_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([
'expectedVersionId' => '<string>',
'expectedDraftRevision' => 123,
'name' => '<string>',
'description' => [
],
'systemPromptMd' => '<string>',
'promptMd' => '<string>',
'outputSchema' => [
],
'inferenceConfig' => [
]
]),
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/extractors/{extractor_id}/draft"
payload := strings.NewReader("{\n \"expectedVersionId\": \"<string>\",\n \"expectedDraftRevision\": 123,\n \"name\": \"<string>\",\n \"description\": {},\n \"systemPromptMd\": \"<string>\",\n \"promptMd\": \"<string>\",\n \"outputSchema\": {},\n \"inferenceConfig\": {}\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/extractors/{extractor_id}/draft")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"expectedVersionId\": \"<string>\",\n \"expectedDraftRevision\": 123,\n \"name\": \"<string>\",\n \"description\": {},\n \"systemPromptMd\": \"<string>\",\n \"promptMd\": \"<string>\",\n \"outputSchema\": {},\n \"inferenceConfig\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/dispositions/extractors/{extractor_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 \"expectedVersionId\": \"<string>\",\n \"expectedDraftRevision\": 123,\n \"name\": \"<string>\",\n \"description\": {},\n \"systemPromptMd\": \"<string>\",\n \"promptMd\": \"<string>\",\n \"outputSchema\": {},\n \"inferenceConfig\": {}\n}"
response = http.request(request)
puts response.read_body{
"data": {
"extractor": {
"id": "0f1f5c7b-3d6e-47b0-981b-d121f6853552",
"agentId": "a1250a05-0ae1-45ca-91e6-1ef7930f0093",
"key": "callback_window",
"name": "Callback window",
"description": "When the caller asked to be called back.",
"currentVersionId": "cc5a57dc-1f76-4007-a9ea-47378e50de0c",
"activeVersionId": null,
"draftRevision": 2,
"createdAt": "2026-09-08T10:21:37.902Z",
"updatedAt": "2026-09-10T17:05:12.446Z"
},
"currentVersion": {
"id": "cc5a57dc-1f76-4007-a9ea-47378e50de0c",
"extractorId": "0f1f5c7b-3d6e-47b0-981b-d121f6853552",
"versionNumber": 1,
"state": "editable",
"name": "Callback window",
"description": "When the caller asked to be called back.",
"systemPromptMd": "You extract scheduling details from customer service calls.",
"promptMd": "Find the day and time window the caller asked for a callback. Leave fields empty if the caller did not ask for one.",
"outputSchema": {
"kind": "object",
"properties": {
"requested": { "kind": "boolean", "description": "Whether the caller asked for a callback." },
"window_start": { "kind": "string", "format": "date-time" },
"window_end": { "kind": "string", "format": "date-time" }
},
"required": ["requested"]
},
"inferenceConfig": {
"modelProfileKey": "high_accuracy",
"temperature": 0,
"thinking": "medium",
"contextSources": ["transcript"]
},
"createdAt": "2026-09-08T10:21:37.902Z",
"updatedAt": "2026-09-10T17:05:12.446Z"
}
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "Extractor draft changed; refresh and try again"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Disposition extractor not found"
}
]
}
Overview
Dispositions are enabled per organization. If your organization does not have access, these endpoints return
404.editable version in place. Only the fields you send change; the merged draft is validated with the same rules as Create Disposition Extractor. Published versions are never modified; to make the edited draft pinnable, call Publish Disposition Extractor.
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. A malformed id returns
400 with the message agentId must be a valid UUID.string
required
The extractor’s unique identifier. Must be organization-wide or scoped to this agent; otherwise returns
404 with the message Disposition extractor not found. A malformed id returns 400 with the message extractorId must be a valid UUID.Body Parameters
Unknown fields are rejected. A body that fails shape validation returns400 with the message Invalid request body; a merged draft that breaks a prompt, schema, or model-profile rule returns 400 with the message Extractor definition failed validation. In both cases the error’s ext field is a JSON string listing each problem.
string
required
The extractor’s current
currentVersionId. If another update or publish has moved it, the request returns 409 CONFLICT with the message Extractor draft changed; refresh and try again.integer
required
The extractor’s current
draftRevision. Minimum 1. A stale value returns the same 409 CONFLICT.string
New display name, 1 to 120 characters. Updates both the extractor record and the draft version.
string | null
New description, up to 2000 characters. Send
null to clear it. Updates both the extractor record and the draft version.string
New system prompt in Markdown. Up to 8000 characters and 8000 UTF-8 bytes.
string
New extraction prompt in Markdown. 1 to 8000 characters, up to 8000 UTF-8 bytes, and must contain non-whitespace text.
systemPromptMd and promptMd together may not exceed 16000 UTF-8 bytes.object
Replaces the whole output schema. Same shape and limits as on Create Disposition Extractor.
object
Replaces the whole inference configuration, so
contextSources is required inside it. Same fields and limits as on Create Disposition Extractor. modelProfileKey defaults to balanced when omitted.Response
object
The extractor record after the update, with
draftRevision incremented by 1.Show extractor object
Show extractor object
string
Unique identifier for the extractor.
string | null
null for an organization-wide extractor. Otherwise the id of the one agent it is scoped to.string
Stable machine key, unique within your organization.
string
The extractor’s display name.
string | null
Optional description.
string
Unchanged by this call; the same id as
data.currentVersion.id.string | null
The most recently published version, or
null if never published. Unchanged by this call.integer
The new revision. Pass it as
expectedDraftRevision on your next update or publish.string
ISO 8601 timestamp of creation.
string
ISO 8601 timestamp of this update.
object
The updated
editable version.Show version object
Show version object
string
Unique identifier for the version.
string
The extractor this version belongs to.
integer
Unchanged by this call.
string
Always
editable here.string
Display name after the update.
string | null
Description after the update.
string
System prompt after the update. Empty string when none is set.
string
Extraction prompt after the update.
object
Output schema after the update.
object
Inference configuration after the update:
modelProfileKey, contextSources, and, when set, temperature, maxOutputTokens, and thinking.string
ISO 8601 timestamp of creation.
string
ISO 8601 timestamp of this update.
null | array
null on success, or a list of error objects if the request failed.{
"data": {
"extractor": {
"id": "0f1f5c7b-3d6e-47b0-981b-d121f6853552",
"agentId": "a1250a05-0ae1-45ca-91e6-1ef7930f0093",
"key": "callback_window",
"name": "Callback window",
"description": "When the caller asked to be called back.",
"currentVersionId": "cc5a57dc-1f76-4007-a9ea-47378e50de0c",
"activeVersionId": null,
"draftRevision": 2,
"createdAt": "2026-09-08T10:21:37.902Z",
"updatedAt": "2026-09-10T17:05:12.446Z"
},
"currentVersion": {
"id": "cc5a57dc-1f76-4007-a9ea-47378e50de0c",
"extractorId": "0f1f5c7b-3d6e-47b0-981b-d121f6853552",
"versionNumber": 1,
"state": "editable",
"name": "Callback window",
"description": "When the caller asked to be called back.",
"systemPromptMd": "You extract scheduling details from customer service calls.",
"promptMd": "Find the day and time window the caller asked for a callback. Leave fields empty if the caller did not ask for one.",
"outputSchema": {
"kind": "object",
"properties": {
"requested": { "kind": "boolean", "description": "Whether the caller asked for a callback." },
"window_start": { "kind": "string", "format": "date-time" },
"window_end": { "kind": "string", "format": "date-time" }
},
"required": ["requested"]
},
"inferenceConfig": {
"modelProfileKey": "high_accuracy",
"temperature": 0,
"thinking": "medium",
"contextSources": ["transcript"]
},
"createdAt": "2026-09-08T10:21:37.902Z",
"updatedAt": "2026-09-10T17:05:12.446Z"
}
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "Extractor draft changed; refresh and try again"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Disposition extractor not found"
}
]
}
Docs for agents: llms.txt
Was this page helpful?