> ## 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.

# Create Disposition

> Create a disposition with an initial draft definition.

### Overview

<Note>
  Dispositions are enabled per organization. If your organization does not have access, these endpoints return `404`.
</Note>

Creates a disposition on the agent with the supplied definition as its draft. The disposition starts `disabled` and does not run on calls until you [estimate](/api-v2/post/agents-id-dispositions-disposition-id-estimates) and [publish](/api-v2/post/agents-id-dispositions-disposition-id-publish) it. Edit the draft later with [Update Disposition Draft](/api-v2/patch/agents-id-dispositions-disposition-id-draft).

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

### Headers

<ParamField header="authorization" type="string" required>
  Your API key for authentication.
</ParamField>

### Path Parameters

<ParamField path="agent_id" type="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.
</ParamField>

### Body Parameters

Unknown fields anywhere in the body are rejected.

<ParamField body="key" type="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.
</ParamField>

<ParamField body="definition" type="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.

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

  <Expandable title="definition object">
    <ParamField body="name" type="string" required>
      Display name, 1 to 120 characters.
    </ParamField>

    <ParamField body="description" type="string" required>
      Free-text description, up to 2000 characters. May be empty.
    </ParamField>

    <ParamField body="timing" type="string" required>
      `immediate` runs within 30 minutes of call completion. `within_24h` queues the run with a 24-hour deadline.
    </ParamField>

    <ParamField body="values" type="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.
    </ParamField>

    <ParamField body="values[].id" type="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.
    </ParamField>

    <ParamField body="values[].key" type="string" required>
      Payload field name, 1 to 64 characters matching `^[a-z][a-z0-9_]*$`. May change between drafts.
    </ParamField>

    <ParamField body="values[].label" type="string" required>
      Human-readable label, 1 to 120 characters.
    </ParamField>

    <ParamField body="values[].schema" type="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.
    </ParamField>

    <ParamField body="values[].source" type="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](/api-v2/get/agents-id-dispositions-variable-catalog).
    </ParamField>

    <ParamField body="values[].source.kind" type="string" required>
      One of `variable_extraction`, `structured_extraction`, `judge`, or `custom_code`.
    </ParamField>

    <ParamField body="values[].source.variableKey" type="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.
    </ParamField>

    <ParamField body="values[].source.execution" type="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`.
    </ParamField>

    <ParamField body="values[].source.extractorId" type="string">
      `structured_extraction` only, required. UUID of an extractor from [List Extractors](/api-v2/get/agents-id-dispositions-extractors) that is org-wide or scoped to this agent.
    </ParamField>

    <ParamField body="values[].source.extractorVersionId" type="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.
    </ParamField>

    <ParamField body="values[].source.frozen" type="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.
    </ParamField>

    <ParamField body="values[].source.judgeId" type="string">
      `judge` only, required. UUID of a judge from [Get Judge Catalog](/api-v2/get/agents-id-dispositions-judge-catalog) that is org-wide or scoped to this agent.
    </ParamField>

    <ParamField body="values[].source.judgeVersionId" type="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.
    </ParamField>

    <ParamField body="values[].source.snippetId" type="string">
      `custom_code` only, required. UUID of a code snippet owned by your organization. The snippet must be JavaScript.
    </ParamField>

    <ParamField body="values[].source.snippetVersion" type="integer">
      `custom_code` only, required. Snippet version number, at least `1`.
    </ParamField>

    <ParamField body="values[].source.timeoutSeconds" type="integer">
      `custom_code` only, required. 1 to 60.
    </ParamField>

    <ParamField body="values[].source.connections" type="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.
    </ParamField>

    <ParamField body="values[].source.secrets" type="object">
      `custom_code` only, required (may be `{}`). Up to 20 entries keyed by an alias with the same pattern, each `{ "secretId": "uuid" }`.
    </ParamField>

    <ParamField body="values[].source.dependencyValueIds" type="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.
    </ParamField>

    <ParamField body="transformation" type="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.
    </ParamField>

    <ParamField body="postCallWebhook" type="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.
    </ParamField>
  </Expandable>
</ParamField>

### Response

Returns `201` on success.

<ResponseField name="data" type="object">
  The new disposition summary.

  <Expandable title="disposition object">
    <ResponseField name="id" type="string">
      Unique identifier for the disposition.
    </ResponseField>

    <ResponseField name="agentId" type="string">
      The agent this disposition belongs to.
    </ResponseField>

    <ResponseField name="key" type="string">
      The slug you supplied.
    </ResponseField>

    <ResponseField name="state" type="string">
      Always `disabled` on a new disposition.
    </ResponseField>

    <ResponseField name="publishedVersionId" type="null">
      Always `null` on a new disposition.
    </ResponseField>

    <ResponseField name="publishedVersionNumber" type="null">
      Always `null` on a new disposition.
    </ResponseField>

    <ResponseField name="draftRevision" type="number">
      Always `1` on a new disposition. Pass it as `expectedDraftRevision` on the first draft update.
    </ResponseField>

    <ResponseField name="draftValueCount" type="number">
      Number of values in the definition you supplied.
    </ResponseField>

    <ResponseField name="hasUnpublishedChanges" type="boolean">
      Always `true` on a new disposition.
    </ResponseField>

    <ResponseField name="name" type="string">
      The definition's name.
    </ResponseField>

    <ResponseField name="description" type="string">
      The definition's description.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of creation.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp of creation.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="errors" type="null | array">
  `null` on success, or a list of error objects if the request failed.
</ResponseField>

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

  ```json Invalid Body theme={null}
  {
    "data": null,
    "errors": [
      {
        "error": "BAD_REQUEST",
        "message": "Invalid request body",
        "ext": "{\"errors\":[\"/key: Expected string to match '^[a-z][a-z0-9_]*$'\"]}"
      }
    ]
  }
  ```

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

  ```json Conflict theme={null}
  {
    "data": null,
    "errors": [
      {
        "error": "CONFLICT",
        "message": "A disposition with key \"appointment_outcome\" already exists"
      }
    ]
  }
  ```
</ResponseExample>

***

Docs for agents: [llms.txt](/llms.txt)