Responses are generated using AI and may contain mistakes.
Bland is getting a major upgrade. We're working on updating our docs as users transition in the coming weeks. Reach out to support@bland.ai with questions.
Dispositions are enabled per organization. If your organization does not have access, these endpoints return 404.
Validates the editable draft, moves it to the archived state as the extractor’s new activeVersionId, and opens a fresh editable copy with the next versionNumber as the new currentVersionId. The published version is immutable and appears in Get Extractor Catalog, where a disposition value can pin it. Dispositions that already pinned an earlier version keep running that version.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 and return 400 with the message Invalid request body. If the draft fails the same prompt, schema, or model-profile rules as Create Disposition Extractor, the request returns 400 with the message Extractor definition failed validation and nothing is published.
string
required
The extractor’s current currentVersionId, the draft being published. 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.
Response
object
The extractor record after publishing. activeVersionId now points at data.publishedVersion.id, currentVersionId at data.currentVersion.id, and draftRevision has incremented by 1.
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
The new editable version, the same id as data.currentVersion.id.
string
The version just published, the same id as data.publishedVersion.id.
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 publish.
object
The version that was just published, now archived and immutable.
Show version object
string
Unique identifier for the version. This is the id a disposition value pins.
string
The extractor this version belongs to.
integer
The published version number.
string
Always archived here.
string
Display name at this version.
string | null
Description at this version.
string
The frozen system prompt. Empty string when none is set.
string
The frozen extraction prompt.
object
The frozen output schema.
object
The frozen inference configuration: modelProfileKey, contextSources, and, when set, temperature, maxOutputTokens, and thinking.
string
ISO 8601 timestamp of creation.
string
ISO 8601 timestamp of the last draft edit before publishing.
object
The new editable draft, a copy of the published version with versionNumber incremented by 1. Same fields as data.publishedVersion, with state set to editable.
null | array
null on success, or a list of error objects if the request failed.
{ "data": { "extractor": { "id": "6816b867-754b-413f-9c19-1a7e94c541b4", "agentId": null, "key": "appointment_outcome", "name": "Appointment outcome", "description": "Whether an appointment was booked, rescheduled, or declined.", "currentVersionId": "ddf9de6a-0ba7-4f73-8a0c-c0d52afcd355", "activeVersionId": "ab65bde8-78d1-443c-9406-e3a8c8934b7b", "draftRevision": 2, "createdAt": "2026-09-01T15:02:11.480Z", "updatedAt": "2026-09-10T17:32:08.905Z" }, "publishedVersion": { "id": "ab65bde8-78d1-443c-9406-e3a8c8934b7b", "extractorId": "6816b867-754b-413f-9c19-1a7e94c541b4", "versionNumber": 1, "state": "archived", "name": "Appointment outcome", "description": "Whether an appointment was booked, rescheduled, or declined.", "systemPromptMd": "", "promptMd": "Decide whether the caller booked, rescheduled, or declined an appointment. Return unclear if the call ended before a decision.", "outputSchema": { "kind": "enum", "description": "Final appointment outcome for this call.", "options": [ { "key": "booked", "label": "Booked" }, { "key": "rescheduled", "label": "Rescheduled" }, { "key": "declined", "label": "Declined" }, { "key": "unclear", "label": "Unclear" } ] }, "inferenceConfig": { "modelProfileKey": "balanced", "thinking": "low", "contextSources": ["transcript", "call_metadata"] }, "createdAt": "2026-09-01T15:02:11.480Z", "updatedAt": "2026-09-01T15:02:11.480Z" }, "currentVersion": { "id": "ddf9de6a-0ba7-4f73-8a0c-c0d52afcd355", "extractorId": "6816b867-754b-413f-9c19-1a7e94c541b4", "versionNumber": 2, "state": "editable", "name": "Appointment outcome", "description": "Whether an appointment was booked, rescheduled, or declined.", "systemPromptMd": "", "promptMd": "Decide whether the caller booked, rescheduled, or declined an appointment. Return unclear if the call ended before a decision.", "outputSchema": { "kind": "enum", "description": "Final appointment outcome for this call.", "options": [ { "key": "booked", "label": "Booked" }, { "key": "rescheduled", "label": "Rescheduled" }, { "key": "declined", "label": "Declined" }, { "key": "unclear", "label": "Unclear" } ] }, "inferenceConfig": { "modelProfileKey": "balanced", "thinking": "low", "contextSources": ["transcript", "call_metadata"] }, "createdAt": "2026-09-10T17:32:08.905Z", "updatedAt": "2026-09-10T17:32:08.905Z" } }, "errors": null}