Update Disposition Draft

PATCH

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.

Replaces the whole draft definition. The write is guarded by the draft revision: pass the 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 of definition 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

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

⌘I

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

​Headers

​Path Parameters

​Body Parameters

​Response

Overview

Headers

Path Parameters

Body Parameters

Response