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

# Align Disposition Test Run

> Propose definition edits from a test run's corrections.

### Overview

> [!NOTE]
>
> Dispositions are enabled per organization. If your organization does not have access, these endpoints return `404`.

Reads the corrections saved on a finished test run and proposes rewritten prompt or description text for each corrected value, returned as before-and-after diffs with a rationale. Nothing is written: apply a proposal yourself by editing the extractor, the draft definition, or the judge. The run must be in a terminal status (`complete`, `partial`, or `failed`) and have at least one correction from [Correct Test Run Value](https://docs.bland.ai/api-v2/put/agents-id-dispositions-disposition-id-runs-run-id-cases-call-id-annotations-value-id.md). Each corrected value costs one inference call; an organization may make at most 30 align requests per hour.

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.

**run\_id** `string` *required*

The test run's unique identifier. Must be a UUID; otherwise returns `400` with the message `runId must be a valid UUID`. Returns `404 Test run not found` if it does not belong to this disposition.

### Body Parameters

The body is optional; an empty object aligns every corrected value with no extra guidance. Unknown fields return `400 BAD_REQUEST` with the message `Invalid request body`.

**valueIds** `array`

Restrict alignment to these value ids: 1 to 50 UUIDs. Every id must exist in the run's definition snapshot, otherwise `404` with the message `Disposition value not found in this run`. Values in the list that have no corrections are silently ignored.

**instructions** `string`

Free-text guidance added to every value's proposal request, up to 2000 characters after trimming. Use it to steer tone or emphasis (for example, "keep prompts under 80 words").

### Response

**data.proposals** `array`

One entry per corrected value that produced a usable proposal. A value whose corrections suggest no change appears with an empty `changes` array.

**proposal object**

**valueId** `string`

The definition value.

**key** `string`

The value's `key`.

**kind** `string`

`structured_extraction`, `variable_extraction`, or `judge`. `custom_code` values are never proposed against.

**changes** `array`

Up to 12 field-level edits, each `{ "field", "before", "after", "rationale" }`. `field` is `promptMd` or `systemPromptMd` (structured extraction and judge), `description` (variable extraction, the value schema's description), or `levels.` followed by an existing judge level key and `.promptMd` (a judge level prompt). `before` is the current text, read by the server from the run's frozen definition or the pinned judge version, never from the proposal. `after` is the full replacement text, up to 20,000 characters. `rationale` explains the change in up to 1000 characters. No-op edits and duplicate fields are dropped.

**data.skipped** `array`

Corrected values that received no proposal, each `{ "valueId", "reason" }`. `reason` is `custom_code` (code values have no editable text), `no_editable_fields` (an unfrozen extraction source or a judge whose pinned version is gone), `proposal_invalid` (no usable proposal after two attempts), or `brief_too_large` (the value's text and corrections exceed the per-request size budget even after trimming).

**data.truncatedCorrections** `number`

How many corrections were dropped, oldest first, to fit the request within its size budget. `0` when every correction was considered.

**errors** `null | array`

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

```json Response theme={null}
{
  "data": {
    "proposals": [
      {
        "valueId": "f4b706ec-43cc-4373-b4a5-a06130fddbbf",
        "key": "booked",
        "kind": "judge",
        "changes": [
          {
            "field": "promptMd",
            "before": "Decide whether the caller booked an appointment during this call.",
            "after": "Decide whether the caller booked an appointment during this call. Treat a verbal agreement to a specific day and time as booked, even if the agent did not read back a confirmation number.",
            "rationale": "Three corrections flipped the verdict from not booked to booked on calls where the caller agreed to a slot but no confirmation number was read back."
          }
        ]
      }
    ],
    "skipped": [
      {
        "valueId": "d2dc9bf3-d842-44f9-8002-dea791ff0ad4",
        "reason": "custom_code"
      }
    ],
    "truncatedCorrections": 0
  },
  "errors": null
}
```

```json Not Ready theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "DISPOSITION_ALIGN_NOT_READY",
      "message": "Aligning requires a terminal test run"
    }
  ]
}
```

```json No Corrections theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "DISPOSITION_ALIGN_NOT_READY",
      "message": "Correct at least one value on this run before aligning"
    }
  ]
}
```

```json Rate Limited theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "TOO_MANY_REQUESTS",
      "message": "Too many disposition align requests for this organization — please wait before requesting more."
    }
  ]
}
```

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

***

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.