> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Disposition Draft

> Replace a disposition's draft definition.

### Overview

> [!NOTE]
>
> 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](https://docs.bland.ai/api-v2/get/agents-id-dispositions-disposition-id-draft.md) 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](https://docs.bland.ai/api-v2/post/agents-id-dispositions-disposition-id-publish.md) to make changes live.

Requires an admin, owner, operator, or prompter role.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Path Parameters

**agent\_id** `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.

**disposition\_id** `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.

**expectedDraftRevision** `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`.

**definition** `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.

**definition object**

**name** `string` *required*

Display name, 1 to 120 characters.

**description** `string` *required*

Free-text description, up to 2000 characters. May be empty.

**timing** `string` *required*

`immediate` runs within 30 minutes of call completion. `within_24h` queues the run with a 24-hour deadline.

**values** `array` *required*

Up to 50 value objects. Each value produces one field of the result. Value `id`s and `key`s must be unique within the definition. A definition with no values can be saved but not published or tested.

**values\[].id** `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.

**values\[].key** `string` *required*

Payload field name, 1 to 64 characters matching `^[a-z][a-z0-9_]*$`. May change between drafts.

**values\[].label** `string` *required*

Human-readable label, 1 to 120 characters.

**values\[].schema** `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.

**values\[].source** `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](https://docs.bland.ai/api-v2/get/agents-id-dispositions-variable-catalog.md).

**values\[].source.kind** `string` *required*

One of `variable_extraction`, `structured_extraction`, `judge`, or `custom_code`.

**values\[].source.variableKey** `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.

**values\[].source.execution** `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`.

**values\[].source.extractorId** `string`

`structured_extraction` only, required. UUID of an extractor from [List Extractors](https://docs.bland.ai/api-v2/get/agents-id-dispositions-extractors.md) that is org-wide or scoped to this agent.

**values\[].source.extractorVersionId** `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.

**values\[].source.frozen** `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.

**values\[].source.judgeId** `string`

`judge` only, required. UUID of a judge from [Get Judge Catalog](https://docs.bland.ai/api-v2/get/agents-id-dispositions-judge-catalog.md) that is org-wide or scoped to this agent.

**values\[].source.judgeVersionId** `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.

**values\[].source.snippetId** `string`

`custom_code` only, required. UUID of a code snippet owned by your organization. The snippet must be JavaScript.

**values\[].source.snippetVersion** `integer`

`custom_code` only, required. Snippet version number, at least `1`.

**values\[].source.timeoutSeconds** `integer`

`custom_code` only, required. 1 to 60.

**values\[].source.connections** `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.

**values\[].source.secrets** `object`

`custom_code` only, required (may be `{}`). Up to 20 entries keyed by an alias with the same pattern, each `{ "secretId": "uuid" }`.

**values\[].source.dependencyValueIds** `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.

**transformation** `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.

**postCallWebhook** `object` *required*

`{ "mode": "hold" }` or `{ "mode": "emit_followup" }`. `hold` is only valid with `timing: "immediate"`.

### Response

**data.dispositionId** `string`

The disposition this draft belongs to.

**data.revision** `number`

The new draft revision, `expectedDraftRevision + 1`.

**data.baseVersionId** `string | null`

The most recently published version, or `null` if never published.

**data.definition** `object`

The saved definition, as stored.

**errors** `null | array`

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

```json Response theme={null}
{
  "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
}
```

```json Invalid Body theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "BAD_REQUEST",
      "message": "Invalid request body",
      "ext": "{\"errors\":[\"/expectedDraftRevision: Expected required property\"]}"
    }
  ]
}
```

```json Definition Invalid theme={null}
{
  "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\"}]}"
    }
  ]
}
```

```json Conflict theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "CONFLICT",
      "message": "Draft revision moved (expected 3) — reload and reapply your change"
    }
  ]
}
```

```json Not Found theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "NOT_FOUND",
      "message": "Disposition not found"
    }
  ]
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.