# Delete Test Scenario Source: https://docs.bland.ai/api-v1/delete/agent-testing-scenarios-id DELETE https://api.bland.ai/v1/agent-testing/scenarios/{id} Delete a test scenario and all related data. ### Headers Your API key for authentication. ### Path Parameters The scenario ID. ### Response Whether the scenario was successfully deleted. ```json Response theme={null} { "deleted": true } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Alarm Source: https://docs.bland.ai/api-v1/delete/alarms-id DELETE https://api.bland.ai/v1/alarms/{id} Delete an alarm configuration. ### Headers Your API key for authentication. ### Path Parameters Alarm configuration ID. ### Response Returns a `204 No Content` response on success. ```json Error theme={null} { "data": null, "errors": [ { "error": "ALARM_NOT_FOUND", "message": "Alarm configuration not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Block Rule Source: https://docs.bland.ai/api-v1/delete/blocked-numbers-id DELETE https://api.bland.ai/v1/blocked_numbers/{block_id} Permanently delete a block rule. ### Headers Your API key for authentication. ### Path Parameters The unique ID of the block rule to delete. ### Response Confirmation message and ID of the deleted rule. Success message indicating the block rule was deleted. The ID of the block rule that was removed. `null` on success, or a list of error objects if the rule was not found or deletion failed. ```json Response theme={null} { "data": { "message": "Block rule deleted successfully", "deleted_block_id": 123 }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Eval Agent Source: https://docs.bland.ai/api-v1/delete/evals-agents-id DELETE https://api.bland.ai/v1/evals/agents/{eval_agent_id} Soft-delete an eval agent. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the eval agent to delete. Returns `204 No Content` on success. # Delete User Template Source: https://docs.bland.ai/api-v1/delete/evals-user-templates-id DELETE https://api.bland.ai/v1/evals/user-templates/{id} Soft-delete a saved eval agent template. ### Headers Your API key for authentication. ### Path Parameters The UUID of the user template to delete. Returns `204 No Content` on success. *** Docs for agents: [llms.txt](/llms.txt) # Delete Workbench Setup Source: https://docs.bland.ai/api-v1/delete/evals-workbench-setups-id DELETE https://api.bland.ai/v1/evals/workbench-setups/{setup_id} Soft-delete a workbench setup. ### Headers Your API key for authentication. ### Path Parameters The ID of the workbench setup to delete. Returns `204 No Content` on success. # Delete Guard Rail Source: https://docs.bland.ai/api-v1/delete/guard-rails-id DELETE https://api.bland.ai/v1/guard_rails/{guard_rail_id} Delete a guard rail. Deleting a guard rail will remove it from all attached sources (personas, pathways, inbound numbers). Calls using those sources will no longer be monitored by this guard rail. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the guard rail to delete. ### Response Returns a `204 No Content` response on success. ```json Error Response (Not Found) theme={null} { "data": null, "errors": [ { "error": "NOT_FOUND", "message": "Guard rail not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Knowledge Base Source: https://docs.bland.ai/api-v1/delete/knowledge-id DELETE https://api.bland.ai/v1/knowledge/{knowledge_base_id} Soft deletes a knowledge base by setting its status to 'DELETED'. Marks a knowledge base as deleted by setting its status to `"DELETED"`. This is a soft delete operation - the knowledge base data is retained but becomes inaccessible for normal operations. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the knowledge base to delete. ### Response Deletion confirmation object. Always `true` when the deletion is successful. Confirmation message about the deletion. The ID of the deleted knowledge base. Will be `null` on successful deletion. ```bash cURL theme={null} curl -X DELETE https://api.bland.ai/v1/knowledge/kb_01H8X9QK5R2N7P3M6Z8W4Y1V5T \ -H "authorization: YOUR_API_KEY" ``` ```json Success Response theme={null} { "data": { "success": true, "message": "Knowledge base successfully deleted", "knowledge_base_id": "kb_01H8X9QK5R2N7P3M6Z8W4Y1V5T" }, "errors": null } ``` ```json Not Found Response theme={null} { "data": null, "errors": [ { "error": "KB_ERROR", "message": "KB not found or access denied" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Leave Organization Source: https://docs.bland.ai/api-v1/delete/org_leave_self_memberships_id DELETE https://api.bland.ai/v1/orgs/self/leave Remove the authenticated user from an organization. ### Headers Your API key for authentication. ### Body The unique identifier of the organization the user wants to leave. ### Response Always `null` upon successful removal. Always `null` on success. ```json Response theme={null} { "data": null, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Organization Source: https://docs.bland.ai/api-v1/delete/orgs DELETE https://api.bland.ai/v1/orgs/{org_id} Delete an organization. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the organization you want to delete. ### Body The slug of the organization to confirm deletion. ### Response Always `null` upon successful deletion. `null` if successful; contains error details if the request fails. ```json Response theme={null} { "data": null, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Folder Source: https://docs.bland.ai/api-v1/delete/pathway_folder DELETE https://us.api.bland.ai/v1/pathway/folders/{folder_id} Deletes a specific folder for the authenticated user. The folder must be empty to be deleted. ### Headers Your API key for authentication. ### Path Parameters The ID of the folder to delete. ### Response The ID of the deleted folder. ```json Response theme={null} { "folder_id": "deleted_folder_123" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Pathway Version Source: https://docs.bland.ai/api-v1/delete/pathway_version DELETE https://api.bland.ai/v1/pathway/{pathway_id}/version/{version_id} Marks a specific version of a pathway as archived, effectively deleting it from active use. ### Headers Your API key for authentication. ### Path Parameters The ID of the pathway containing the version to be deleted. The ID of the version to be deleted. ### Response The status of the operation (e.g., "success"). A message describing the result of the operation. ```json Response theme={null} { "status": "success", "message": "Version deleted successfully" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Persona Source: https://docs.bland.ai/api-v1/delete/personas-id DELETE https://api.bland.ai/v1/personas/{persona_id} Delete a persona. Deleting a persona will remove all versions and configuration data permanently. Any phone numbers currently using this persona will need to be reconfigured with a different persona or direct configuration. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the persona to delete. ### Query Parameters Force deletion even if persona is currently in use by phone numbers. When false, deletion will fail if persona is actively being used. ### Response The deletion result object. Whether the deletion was successful. Confirmation message about the deletion. Any errors that occurred (null if none). ```json Success Response theme={null} { "data": { "success": true, "message": "Persona deleted successfully" }, "errors": null } ``` ```json Error Response (Persona in Use) theme={null} { "data": null, "errors": [ { "error": "PERSONA_IN_USE", "message": "Cannot delete persona that is currently in use by phone numbers", "details": { "persona_id": "12345678-1234-1234-1234-123456789012", "phone_numbers_using": [ "+15551234567", "+15551234568" ], "suggestion": "Remove persona from all phone numbers first, or use force=true parameter" } } ] } ``` ```json Error Response (Not Found) theme={null} { "data": null, "errors": [ { "error": "PERSONA_NOT_FOUND", "message": "Persona not found", "details": { "persona_id": "12345678-1234-1234-1234-123456789012" } } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Cancel Port Request Source: https://docs.bland.ai/api-v1/delete/sip-port-cancel DELETE https://api.bland.ai/v1/sip/port/{id} Cancel an in-progress number porting request. ### Headers Your API key for authentication. ### Path Parameters The port request ID to cancel. ### Response `true` if the port request was successfully canceled. Port requests can only be canceled before they reach the `completed` status. Once a port is completed, the numbers have already been transferred. ```json Example Request theme={null} curl -X DELETE https://api.bland.ai/v1/sip/port/port_xyz789 \ -H "Authorization: Bearer " ``` ```json Response theme={null} { "data": { "canceled": true }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Conversation Source: https://docs.bland.ai/api-v1/delete/sms-conversations DELETE https://api.bland.ai/v1/sms/conversations/{id} Delete a specific conversation and all of its associated messages. This action is permanent. **Enterprise Feature** - SMS is only available on Enterprise plans. Contact your Bland representative for access. ### Headers Your API key for authentication. ### Path Parameters The ID of the conversation to delete. ### Response Confirmation message indicating the conversation and messages were deleted. A human-readable success message. `null` on success, or a list of error objects on failure. ```json Response theme={null} { "data": { "message": "Conversation and all associated messages deleted successfully" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Messages from Conversation Source: https://docs.bland.ai/api-v1/delete/sms-conversations-message DELETE https://api.bland.ai/v1/sms/conversations/{id}/messages Delete SMS conversations by their IDs. **Enterprise Feature** - SMS is only available on Enterprise plans. Contact your Bland representative for access. ### Headers Your API key for authentication. ### Path Parameters The ID of the conversation deleted. ### Body Parameters A list of message ID integers to mark as deleted. Must not be empty. ### Response Object containing confirmation and the count of messages deleted. A success message indicating how many messages were marked as deleted. The number of messages successfully marked as deleted. `null` on success, or a list of error objects on failure. ```json Response theme={null} { "data": { "message": "2 messages marked as deleted", "deleted_count": 2 }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Custom Tool Source: https://docs.bland.ai/api-v1/delete/tools-tool-id DELETE https://api.bland.ai/v1/tools/{tool_id} Delete your Custom Tool. ### Headers Your API key for authentication. ### Path Parameters The ID of the Custom Tool you want to update. ### Response Whether the tool creation succeeded. ```json theme={null} { "status": "success", "message": "Tool has been deleted." } ``` *** Docs for agents: [llms.txt](/llms.txt) # End Translation Session Source: https://docs.bland.ai/api-v1/delete/translation-sessions-id DELETE https://api.bland.ai/v1/translation/sessions/{session_id} Terminate a translation session from the server side Ends a translation session. If the WebSocket is connected, it receives a final `session_ended` control message and is closed. Pending sessions (created but never connected) are also cleaned up — useful for releasing a concurrency slot you no longer need. Terminating an already-ended session is a no-op and returns the session's final state. ## Authentication Your API key for authentication ## Path Parameters The session UUID returned by `POST /v1/translation/sessions` ## Body Parameters Optional context (max 200 characters) recorded with the session's `end_reason` as `api_terminated:`. ## Response Returns the same session object as [Get Translation Session](/api-v1/get/translation-sessions-id), with `status` and `end_reason` reflecting the termination. ```bash cURL theme={null} curl -X DELETE "https://api.bland.ai/v1/translation/sessions/9592342c-0ed2-4c5e-8ceb-16aa55c804a7" \ -H "Authorization: YOUR_API_KEY" ``` ```python Python theme={null} import requests response = requests.delete( "https://api.bland.ai/v1/translation/sessions/9592342c-0ed2-4c5e-8ceb-16aa55c804a7", headers={"Authorization": "YOUR_API_KEY"}, ) print(response.json()["data"]["end_reason"]) # "api_terminated" ``` ```json Terminated theme={null} { "data": { "session_id": "9592342c-0ed2-4c5e-8ceb-16aa55c804a7", "status": "ENDED", "source_language": "en", "target_language": "es", "voice_id": null, "audio_protocol": "pcm16", "sample_rate": 16000, "max_duration_seconds": 1800, "end_reason": "api_terminated", "session_seconds": null, "billable_minutes": null, "created_at": "2026-06-04T18:05:07.885Z", "started_at": null, "ended_at": "2026-06-04T18:06:08.684Z" }, "errors": null } ``` # Delete Issue Source: https://docs.bland.ai/api-v1/delete/triage-issues-id DELETE https://api.bland.ai/v1/triage/issues/{id} Permanently delete a triage issue. ## Overview Deletes an issue and everything attached: resources, flags, relations, alert bindings, comments, Norm sessions. The underlying calls, SMS conversations, and files are not affected. To take an issue off the board without losing it, [update](/api-v1/patch/triage-issues-id) `status` to `closed` instead. *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue to delete. *** ## Response Returns `204 No Content` on success with an empty body. Subsequent calls to [Get Issue](/api-v1/get/triage-issues-id) for the same ID return 404. ```http No Content theme={null} HTTP/1.1 204 No Content ``` ```json Not Found theme={null} { "data": null, "errors": [ { "error": "not_found", "message": "Issue not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Detach Call Source: https://docs.bland.ai/api-v1/delete/triage-issues-id-calls-call-id DELETE https://api.bland.ai/v1/triage/issues/{id}/calls/{call_id} Detach a call from an issue. ## Overview Convenience over [Remove Resource](/api-v1/delete/triage-issues-id-resources-resource-link-id) for when you have the `call_id` rather than the resource link ID. The underlying call is unaffected. *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. The `call_id` of the call to detach. *** ## Response Returns `204 No Content` on success with an empty body. Returns 404 if the issue does not exist or if the call is not currently attached to this issue. ```http No Content theme={null} HTTP/1.1 204 No Content ``` ```json Not Found theme={null} { "data": null, "errors": [ { "error": "not_found", "message": "Resource not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Remove Flag Source: https://docs.bland.ai/api-v1/delete/triage-issues-id-flags-flag-id DELETE https://api.bland.ai/v1/triage/issues/{id}/flags/{flag_id} Remove a flag from an issue. ## Overview Deletes a flag. The underlying call is unaffected. The flag's `type` stays in the [Flag Types](/api-v1/get/triage-flag-types) catalog if other flags of the same type still exist. *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. Internal UUID of the flag to remove. *** ## Response Returns `204 No Content` on success. Returns 404 if the issue does not exist or the flag does not belong to this issue. ```http No Content theme={null} HTTP/1.1 204 No Content ``` ```json Not Found theme={null} { "data": null, "errors": [ { "error": "not_found", "message": "Flag not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Remove Relation Source: https://docs.bland.ai/api-v1/delete/triage-issues-id-relations-relation-id DELETE https://api.bland.ai/v1/triage/issues/{id}/relations/{relation_id} Remove a relation. ## Overview Removes a relation between two issues. Can be called from either side. *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. Internal UUID of the relation. *** ## Response Returns `204 No Content` on success. Returns 404 if the issue does not exist or the relation does not belong to this issue. ```http No Content theme={null} HTTP/1.1 204 No Content ``` ```json Not Found theme={null} { "data": null, "errors": [ { "error": "not_found", "message": "Relation not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Remove Resource Source: https://docs.bland.ai/api-v1/delete/triage-issues-id-resources-resource-link-id DELETE https://api.bland.ai/v1/triage/issues/{id}/resources/{resource_link_id} Detach a resource from an issue. ## Overview Detaches a resource link from an issue. The underlying call, SMS conversation, or file is unaffected. Pass the resource link `id`, not the underlying `resource_id`. To detach a call by `call_id` instead, use [Detach Call](/api-v1/delete/triage-issues-id-calls-call-id). *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. Internal UUID of the resource link (the `id` field on a resource link object). *** ## Response Returns `204 No Content` on success with an empty body. Returns 404 with `{ error: "not_found" }` if the issue does not exist or the resource link does not belong to this issue. ```http No Content theme={null} HTTP/1.1 204 No Content ``` ```json Not Found theme={null} { "data": null, "errors": [ { "error": "not_found", "message": "Resource not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Knowledge Base Source: https://docs.bland.ai/api-v1/delete/vectors-id DELETE https://api.bland.ai/v1/knowledgebases/{vector_id} Remove a knowledge base from your account. ### Headers Your API key for authentication. ### Path Parameters The `vector_id` of the knowledge base to delete. ```json theme={null} { "message": "Knowledge base deleted" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Voice Source: https://docs.bland.ai/api-v1/delete/voices-id DELETE https://api.bland.ai/v1/voices/{id} Permanently delete a voice you own. ## Overview Soft-deletes a voice from your library. The voice's `deleted_at` column is stamped and it stops appearing in [List Voices](/api-v1/get/voices) and synthesis flows. Only voices owned by your org can be deleted; curated default voices, voices in the public library you have not added, and voices owned by other orgs return `400 ERROR_DELETING_VOICE`. *** ## Headers Your API key for authentication. *** ## Path Parameters UUID of the voice to delete. *** ## Response Confirmation that the voice was deleted. `success` on success. Human-readable confirmation, for example `"Voice deleted successfully"`. `null` on success. ```json Response theme={null} { "data": { "status": "success", "message": "Voice deleted successfully" }, "errors": null } ``` ```json Error Deleting Voice theme={null} { "data": null, "errors": [ { "error": "ERROR_DELETING_VOICE", "message": "Error deleting voice" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Voice Samples Source: https://docs.bland.ai/api-v1/delete/voices-id-samples DELETE https://api.bland.ai/v1/voices/{id}/samples Remove one or more training samples from a voice clone you own. ## Overview Removes the specified samples from a voice clone. The voice is retrained against the remaining samples. If you remove every sample from a voice it becomes unusable for synthesis; delete the voice itself via [Delete Voice](/api-v1/delete/voices-id) if that is your intent. *** ## Headers Your API key for authentication. *** ## Path Parameters UUID of the parent voice. *** ## Body Parameters Array of sample UUIDs to delete. ```json theme={null} { "sample_ids": ["d15b199a-1b79-4664-9a9a-b149ee3b136a"] } ``` *** ## Response `success` on success. The samples remaining on the voice after the deletion. ```json Response theme={null} { "status": "success", "samples": [] } ``` ```json Invalid Request theme={null} { "data": null, "errors": [ { "error": "INVALID_REQUEST", "message": "Missing or invalid sample_ids array" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Custom Component Source: https://docs.bland.ai/api-v1/delete/widget-custom-components-id DELETE https://api.bland.ai/v1/widget/custom_components/{id} Deletes a specific custom component by ID. ### Headers Your API key for authentication. ### Path Parameters UUID of the custom component to update. ### Response HTTP status code (204 for success). *** Docs for agents: [llms.txt](/llms.txt) # List Active Calls Source: https://docs.bland.ai/api-v1/get/active GET https://api.bland.ai/v1/calls/active Retrieve all currently active calls for your organization. Active calls include both queued and in-progress calls that have not yet completed. ### Headers Your API key for authentication. The unique organization ID. ### Response An array of active call objects. Each object represents one ongoing or queued call. Unique identifier for the call. The organization/user ID that initiated the call. The originating phone number. The destination phone number. The agent prompt or objective that was used to initiate the call. The pathway ID associated with the call, if any. The call start time (ISO 8601 string). May be empty if the call has not started. `"true"` if the call is international, `"false"` otherwise. Current call status (e.g., `QUEUED`, `IN_PROGRESS`). Unix epoch (milliseconds) when the call record was created. Always `null` on success. ```json theme={null} { "data": [ { "call_id": "8dd6f762-6c67-4546-aaad-3e59f5e4a09c", "user_id": "bdffa9e8-436c-416d-b95f-a77b19ae4411", "from": "+18475586665", "to": "+13105100966", "objective": "You are a 2...", "pathway_id": "", "start_time": "", "international": "false", "status": "QUEUED", "timestamp": "1758656817432" }, { "call_id": "dadbc09a-9b0b-4eb5-b67f-0c7f1206c623", "user_id": "bdffa9e8-436c-416d-b95f-a77b19ae4411", "from": "+18154728283", "to": "+16106876633", "objective": "You are a 2...", "pathway_id": "", "start_time": "", "international": "false", "status": "IN_PROGRESS", "timestamp": "1758656900740" } ], "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Test Analytics Source: https://docs.bland.ai/api-v1/get/agent-testing-analytics GET https://api.bland.ai/v1/agent-testing/analytics/{pathwayId} Get basic testing analytics for a pathway over a time window. ### Headers Your API key for authentication. ### Path Parameters The pathway ID. ### Query Parameters Number of days to look back. Maximum value is 365. ### Response Total number of test runs in the time window. Number of test runs that passed. Number of test runs that failed. Pass rate as a decimal from 0 to 1. Average score across all runs, from 0 to 1. Individual run summaries for the time window. ```json Response theme={null} { "total_runs": 48, "passed": 39, "failed": 9, "pass_rate": 0.8125, "avg_score": 0.84, "runs": [ { "id": "run_a1b2c3d4-5678-9abc-def0-1234567890ab", "scenario_id": "scn_f0e1d2c3-b4a5-9687-7856-342109876543", "scenario_name": "Happy Path - Appointment Booking", "status": "passed", "score": 0.95, "created_at": "2026-04-13T14:22:00.000Z" }, { "id": "run_b2c3d4e5-6789-abcd-ef01-234567890abc", "scenario_id": "scn_e1d2c3b4-a596-8778-5634-210987654321", "scenario_name": "Angry Caller De-escalation", "status": "failed", "score": 0.42, "created_at": "2026-04-13T14:18:00.000Z" }, { "id": "run_c3d4e5f6-789a-bcde-f012-34567890abcd", "scenario_id": "scn_d2c3b4a5-9687-7856-3421-098765432109", "scenario_name": "Voicemail Detection", "status": "passed", "score": 1.0, "created_at": "2026-04-12T09:45:00.000Z" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Enhanced Analytics Source: https://docs.bland.ai/api-v1/get/agent-testing-analytics-enhanced GET https://api.bland.ai/v1/agent-testing/analytics/{pathwayId}/enhanced Get enhanced testing analytics including node failure heatmap, weakest link, trend analysis, and Sankey flow data. ### Headers Your API key for authentication. ### Path Parameters The pathway ID. ### Query Parameters Number of days to look back. Maximum value is 365. ### Response Total number of test runs in the time window. Number of test runs that passed. Number of test runs that failed. Pass rate as a decimal from 0 to 1. Average score across all runs, from 0 to 1. Overall health score for the pathway, from 0 to 1. Combines pass rate, trend direction, and reliability. Reliability score measuring consistency of results over time, from 0 to 1. Trend analysis for the time window. Weekly trend direction. One of: `improving`, `declining`, `stable`. Daily pass rate data points. The date in ISO 8601 format. Pass rate for that date, from 0 to 1. Number of runs on that date. Failure data per node for building a heatmap visualization. The node ID. The display name of the node. Number of times a test failed at or through this node. Total number of times this node was traversed across all runs. Failure rate for this node, from 0 to 1. The node with the highest failure rate, or `null` if no failures exist. The node ID. The display name of the node. Failure rate for this node, from 0 to 1. Flow data for building a Sankey diagram of test run traversals. Array of nodes in the flow. The node ID. The display name of the node. The node type (e.g., `Default`, `Transfer`, `End Call`). The node category for coloring (e.g., `start`, `middle`, `end`, `error`). Array of links (edges) between nodes. The source node ID. The target node ID. Total number of traversals along this link. Number of traversals from passing runs. Number of traversals from failing runs. ```json Response theme={null} { "total_runs": 124, "passed": 98, "failed": 26, "pass_rate": 0.7903, "avg_score": 0.82, "health_score": 0.76, "reliability_score": 0.85, "trend": { "weekly": "improving", "daily_pass_rates": [ { "date": "2026-04-12", "rate": 0.75, "count": 8 }, { "date": "2026-04-13", "rate": 0.88, "count": 16 }, { "date": "2026-04-14", "rate": 0.90, "count": 10 } ] }, "node_failure_heatmap": [ { "node_id": "node_8f3a2b1c", "node_name": "Escalation Handler", "failure_count": 14, "total_traversals": 38, "failure_rate": 0.3684 }, { "node_id": "node_4d7e9f0a", "node_name": "Appointment Booking", "failure_count": 8, "total_traversals": 72, "failure_rate": 0.1111 }, { "node_id": "node_1a2b3c4d", "node_name": "Greeting", "failure_count": 2, "total_traversals": 124, "failure_rate": 0.0161 }, { "node_id": "node_5e6f7a8b", "node_name": "Collect Info", "failure_count": 2, "total_traversals": 110, "failure_rate": 0.0182 } ], "weakest_link": { "node_id": "node_8f3a2b1c", "node_name": "Escalation Handler", "failure_rate": 0.3684 }, "sankey_data": { "nodes": [ { "id": "node_1a2b3c4d", "name": "Greeting", "type": "Default", "category": "start" }, { "id": "node_5e6f7a8b", "name": "Collect Info", "type": "Default", "category": "middle" }, { "id": "node_4d7e9f0a", "name": "Appointment Booking", "type": "Default", "category": "middle" }, { "id": "node_8f3a2b1c", "name": "Escalation Handler", "type": "Transfer", "category": "middle" }, { "id": "node_9c0d1e2f", "name": "Confirmation", "type": "Default", "category": "middle" }, { "id": "node_end_001", "name": "End Call", "type": "End Call", "category": "end" } ], "links": [ { "source": "node_1a2b3c4d", "target": "node_5e6f7a8b", "value": 110, "pass_count": 96, "fail_count": 14 }, { "source": "node_5e6f7a8b", "target": "node_4d7e9f0a", "value": 72, "pass_count": 64, "fail_count": 8 }, { "source": "node_5e6f7a8b", "target": "node_8f3a2b1c", "value": 38, "pass_count": 24, "fail_count": 14 }, { "source": "node_4d7e9f0a", "target": "node_9c0d1e2f", "value": 64, "pass_count": 64, "fail_count": 0 }, { "source": "node_9c0d1e2f", "target": "node_end_001", "value": 64, "pass_count": 64, "fail_count": 0 }, { "source": "node_8f3a2b1c", "target": "node_end_001", "value": 24, "pass_count": 24, "fail_count": 0 } ] } } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Test Batch Source: https://docs.bland.ai/api-v1/get/agent-testing-batches-id GET https://api.bland.ai/v1/agent-testing/batches/{id} Retrieve a test batch and all its runs. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the test batch. ### Response The unique identifier for the test batch. The overall status of the batch. One of: `PENDING`, `RUNNING`, `PASSED`, `FAILED`, `ERROR`, `CANCELLED`. The total number of scenarios included in the batch. The number of scenarios that passed all assertions. The number of scenarios that failed one or more assertions. How the batch was triggered. For example, `api`, `dashboard`, or `ci`. Whether the pathway version should be automatically promoted to production if all scenarios pass. An array of test run objects with scenario information. Each run includes the run details and the associated scenario metadata. ```json Response theme={null} { "id": "e7a2c3d4-8f9b-4a1e-b5c6-d7e8f9a0b1c2", "status": "FAILED", "total_scenarios": 3, "passed_scenarios": 2, "failed_scenarios": 1, "trigger_source": "api", "publish_on_pass": false, "created_at": "2026-04-14T10:25:00.000Z", "runs": [ { "id": "a3f1b2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c", "scenario_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "status": "PASSED", "overall_score": 0.92, "turn_count": 9, "duration_ms": 14320, "created_at": "2026-04-14T10:25:01.000Z", "scenario": { "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "name": "Appointment Booking - Happy Path" }, "assertion_results": [ { "assertion_id": "d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a", "type": "contains", "target": "transcript", "expected": "appointment confirmed", "passed": true } ] }, { "id": "b4c2d3e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e", "scenario_id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e", "status": "PASSED", "overall_score": 0.87, "turn_count": 11, "duration_ms": 18200, "created_at": "2026-04-14T10:25:01.000Z", "scenario": { "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e", "name": "Transfer to Agent - Escalation" }, "assertion_results": [ { "assertion_id": "a7b8c9d0-1e2f-3a4b-5c6d-7e8f9a0b1c2d", "type": "node_visited", "target": "nodes_visited", "expected": "transfer_to_human", "passed": true } ] }, { "id": "c5d3e4f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f", "scenario_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f", "status": "FAILED", "overall_score": 0.45, "turn_count": 12, "duration_ms": 21050, "created_at": "2026-04-14T10:25:02.000Z", "scenario": { "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f", "name": "Cancellation Flow - Angry Customer" }, "assertion_results": [ { "assertion_id": "f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f9a0b1c", "type": "contains", "target": "transcript", "expected": "cancellation confirmed", "passed": false } ] } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Test Runs Source: https://docs.bland.ai/api-v1/get/agent-testing-runs GET https://api.bland.ai/v1/agent-testing/runs List test runs with optional filtering and pagination. ### Headers Your API key for authentication. ### Query Parameters Filter runs by scenario ID. Filter runs by pathway ID. Filter runs by persona ID. Filter runs by batch ID. Filter runs by status. Possible values: `PENDING`, `RUNNING`, `PASSED`, `FAILED`, `ERROR`, `CANCELLED`. Maximum number of results to return. Must be between 1 and 100. Offset for pagination. Use in combination with `limit` to page through results. ### Response An array of test run objects. Each run includes scenario information and assertion results. The total number of runs matching the applied filters. ```json Response theme={null} { "runs": [ { "id": "a3f1b2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c", "scenario_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "pathway_id": "b1693602-c05e-4b5c-b187-d0189a42aebf", "persona_id": "c2d3e4f5-6a7b-8c9d-0e1f-2a3b4c5d6e7f", "batch_id": null, "status": "PASSED", "overall_score": 0.92, "turn_count": 8, "duration_ms": 14320, "created_at": "2026-04-14T10:30:00.000Z", "scenario": { "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "name": "Appointment Booking - Happy Path" }, "assertion_results": [ { "assertion_id": "d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a", "type": "contains", "target": "transcript", "expected": "appointment confirmed", "passed": true }, { "assertion_id": "e5f6a7b8-9c0d-1e2f-3a4b-5c6d7e8f9a0b", "type": "node_visited", "target": "nodes_visited", "expected": "confirm_booking", "passed": true } ] }, { "id": "b4c2d3e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e", "scenario_id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e", "pathway_id": "b1693602-c05e-4b5c-b187-d0189a42aebf", "persona_id": "c2d3e4f5-6a7b-8c9d-0e1f-2a3b4c5d6e7f", "batch_id": null, "status": "FAILED", "overall_score": 0.45, "turn_count": 12, "duration_ms": 21050, "created_at": "2026-04-14T10:28:00.000Z", "scenario": { "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e", "name": "Cancellation Flow - Angry Customer" }, "assertion_results": [ { "assertion_id": "f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f9a0b1c", "type": "contains", "target": "transcript", "expected": "cancellation confirmed", "passed": false } ] } ], "total_count": 2 } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Test Run Source: https://docs.bland.ai/api-v1/get/agent-testing-runs-id GET https://api.bland.ai/v1/agent-testing/runs/{id} Retrieve detailed results for a specific test run including chat history, assertion results, and scores. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the test run. ### Response The unique identifier for the test run. The ID of the scenario that was executed. The current status of the run. One of: `PENDING`, `RUNNING`, `PASSED`, `FAILED`, `ERROR`, `CANCELLED`. The full conversation history between the simulated persona and the agent. Each entry contains: * `role` - Either `user` (the persona) or `assistant` (the agent). * `content` - The text spoken in that turn. Variables that were extracted or set during the test run. Keys are variable names, values are the extracted values. An ordered list of pathway node IDs that were visited during the test run. The node ID where the conversation ended. The total number of conversational turns in the test run. The total duration of the test run in milliseconds. A score between 0 and 1 representing how well the agent performed across all assertions and evaluations. A detailed tone analysis of the agent's responses. Contains: * `naturalness` - Score (0-1) for how natural the agent sounded. * `conciseness` - Score (0-1) for response brevity and clarity. * `empathy` - Score (0-1) for empathetic responses. * `flow_preservation` - Score (0-1) for maintaining conversation flow. * `back_channeling` - Score (0-1) for appropriate use of acknowledgments. * `topic_transitions` - Score (0-1) for smooth topic changes. * `overall_tone_score` - Aggregate tone score (0-1). * `issues` - Array of identified tone issues. * `examples` - Array of specific examples from the conversation. Results for each assertion defined in the scenario. Each entry includes the assertion configuration and whether it passed or failed. If the run status is `ERROR`, this contains a description of what went wrong. Otherwise `null`. ISO 8601 timestamp for when the run was created. ```json Response theme={null} { "id": "a3f1b2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c", "scenario_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "pathway_id": "b1693602-c05e-4b5c-b187-d0189a42aebf", "persona_id": "c2d3e4f5-6a7b-8c9d-0e1f-2a3b4c5d6e7f", "batch_id": null, "status": "PASSED", "chat_history": [ { "role": "assistant", "content": "Hello! Thanks for calling Acme Dental. How can I help you today?" }, { "role": "user", "content": "Hi, I'd like to book a cleaning appointment for next week." }, { "role": "assistant", "content": "I'd be happy to help you schedule a cleaning. Let me check our availability. Do you have a preferred day next week?" }, { "role": "user", "content": "Tuesday or Wednesday would work best for me." }, { "role": "assistant", "content": "We have openings on Tuesday at 10 AM and Wednesday at 2 PM. Which works better for you?" }, { "role": "user", "content": "Tuesday at 10 AM sounds perfect." }, { "role": "assistant", "content": "Great, I've booked your cleaning appointment for Tuesday at 10 AM. You'll receive a confirmation text shortly. Is there anything else I can help with?" }, { "role": "user", "content": "No, that's all. Thank you!" }, { "role": "assistant", "content": "You're welcome! We'll see you Tuesday. Have a great day!" } ], "variables_extracted": { "appointment_date": "2026-04-21", "appointment_time": "10:00", "service_type": "cleaning" }, "nodes_visited": [ "greeting", "identify_intent", "check_availability", "offer_slots", "confirm_booking", "closing" ], "current_node_id": "closing", "turn_count": 9, "duration_ms": 14320, "overall_score": 0.92, "bland_tone_score": { "naturalness": 0.95, "conciseness": 0.88, "empathy": 0.91, "flow_preservation": 0.93, "back_channeling": 0.85, "topic_transitions": 0.90, "overall_tone_score": 0.91, "issues": [], "examples": [ { "turn": 3, "category": "empathy", "text": "I'd be happy to help you schedule a cleaning.", "sentiment": "positive" } ] }, "assertion_results": [ { "assertion_id": "d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a", "type": "contains", "target": "transcript", "expected": "appointment", "passed": true }, { "assertion_id": "e5f6a7b8-9c0d-1e2f-3a4b-5c6d7e8f9a0b", "type": "node_visited", "target": "nodes_visited", "expected": "confirm_booking", "passed": true }, { "assertion_id": "f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f9a0b1c", "type": "variable_equals", "target": "variables_extracted", "field": "service_type", "expected": "cleaning", "passed": true } ], "error_message": null, "created_at": "2026-04-14T10:30:00.000Z" } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Test Scenarios Source: https://docs.bland.ai/api-v1/get/agent-testing-scenarios GET https://api.bland.ai/v1/agent-testing/scenarios List all test scenarios for your organization. ### Headers Your API key for authentication. ### Query Parameters Filter by pathway ID. Filter by persona ID. Filter by scenario category. Filter by enabled status. Pass `"true"` or `"false"`. ### Response Array of scenario objects, each including assertions and the most recent run. Unique identifier for the scenario. Organization ID that owns this scenario. The pathway ID being tested (null if testing a persona). The persona ID being tested (null if testing a pathway). Name of the scenario. Description of the scenario. Scenario category. Type of scenario. Prompt for the simulated caller. Display name for the tester persona. Maximum conversation turns. Whether Bland Tone scoring is enabled. Whether this scenario is required for promotion. Whether the scenario is enabled. Array of assertion objects. The most recent test run for this scenario (null if never run). ISO 8601 timestamp of when the scenario was created. ISO 8601 timestamp of when the scenario was last updated. ```json Response theme={null} { "scenarios": [ { "id": "a1b2c3d4-5678-9abc-def0-1234567890ab", "org_id": "b2c3d4e5-6789-abcd-ef01-234567890abc", "pathway_id": "c3d4e5f6-789a-bcde-f012-34567890abcd", "persona_id": null, "name": "Angry Caller Test", "description": "Tests de-escalation handling", "category": "ANGRY_CALLER", "scenario_type": "AGENT", "tester_persona_prompt": "You are a frustrated customer...", "tester_persona_name": "Frustrated Customer", "max_turns": 15, "bland_tone_enabled": true, "is_required_for_promotion": false, "enabled": true, "assertions": [ { "id": "d4e5f6a7-89ab-cdef-0123-4567890abcde", "type": "LLM_JUDGE", "name": "De-escalation", "config": { "prompt": "Did the agent successfully de-escalate the situation?", "output_type": "score", "threshold": 0.7 }, "is_required": true, "weight": 1.5, "order": 0 } ], "most_recent_run": { "id": "e5f6a7b8-9abc-def0-1234-567890abcdef", "status": "PASSED", "score": 0.85, "completed_at": "2026-04-13T18:30:00.000Z" }, "created_at": "2026-04-10T12:00:00.000Z", "updated_at": "2026-04-13T18:30:00.000Z" }, { "id": "f6a7b8c9-0abc-def1-2345-67890abcdef0", "org_id": "b2c3d4e5-6789-abcd-ef01-234567890abc", "pathway_id": "c3d4e5f6-789a-bcde-f012-34567890abcd", "persona_id": null, "name": "Happy Path - Booking", "description": "Tests the standard booking flow", "category": "HAPPY_PATH", "scenario_type": "AGENT", "tester_persona_prompt": "You want to book an appointment for next Tuesday at 2pm.", "tester_persona_name": "Polite Customer", "max_turns": 20, "bland_tone_enabled": false, "is_required_for_promotion": true, "enabled": true, "assertions": [ { "id": "a7b8c9d0-1abc-ef23-4567-890abcdef012", "type": "NODE_REACHED", "name": "Reached Booking Confirmation", "config": { "node_id": "booking-confirmation-node" }, "is_required": true, "weight": 1.0, "order": 0 } ], "most_recent_run": null, "created_at": "2026-04-12T09:00:00.000Z", "updated_at": "2026-04-12T09:00:00.000Z" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Test Scenario Source: https://docs.bland.ai/api-v1/get/agent-testing-scenarios-id GET https://api.bland.ai/v1/agent-testing/scenarios/{id} Retrieve a specific test scenario with its assertions. ### Headers Your API key for authentication. ### Path Parameters The scenario ID. ### Response Unique identifier for the scenario. Organization ID that owns this scenario. The pathway ID being tested (null if testing a persona). The persona ID being tested (null if testing a pathway). Name of the scenario. Description of the scenario. Scenario category. Type of scenario. Prompt for the simulated caller. Display name for the tester persona. Maximum conversation turns. Custom request data. Starting node ID. Whether Bland Tone scoring is enabled. Whether this scenario is required for promotion. Whether the scenario is enabled. Pre-seeded messages for replay scenarios. Additional instructions for test execution. Arbitrary metadata. Array of assertion objects. Unique identifier for the assertion. The assertion type. Display name for the assertion. Type-specific configuration. Whether this assertion must pass. Weight of this assertion in the overall score. Evaluation order. ISO 8601 timestamp of when the scenario was created. ISO 8601 timestamp of when the scenario was last updated. ```json Response theme={null} { "id": "a1b2c3d4-5678-9abc-def0-1234567890ab", "org_id": "b2c3d4e5-6789-abcd-ef01-234567890abc", "pathway_id": "c3d4e5f6-789a-bcde-f012-34567890abcd", "persona_id": null, "name": "Angry Caller Test", "description": "Tests the agent's ability to de-escalate an angry caller", "category": "ANGRY_CALLER", "scenario_type": "AGENT", "tester_persona_prompt": "You are a frustrated customer who has been waiting on hold for 30 minutes. You are upset about a billing error on your account.", "tester_persona_name": "Frustrated Customer", "max_turns": 15, "request_data": null, "start_node_id": null, "bland_tone_enabled": true, "is_required_for_promotion": false, "enabled": true, "input_messages": null, "advanced_instructions": null, "metadata": null, "assertions": [ { "id": "d4e5f6a7-89ab-cdef-0123-4567890abcde", "type": "LLM_JUDGE", "name": "De-escalation", "config": { "prompt": "Did the agent successfully de-escalate the situation and address the customer's concerns?", "output_type": "score", "threshold": 0.7 }, "is_required": true, "weight": 1.5, "order": 0 } ], "created_at": "2026-04-10T12:00:00.000Z", "updated_at": "2026-04-13T18:30:00.000Z" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Simulation Set Source: https://docs.bland.ai/api-v1/get/agent-testing-simulation-sets-id GET https://api.bland.ai/v1/agent-testing/simulation-sets/{id} Retrieve a simulation set with its statistics including pass rates, flakiness detection, and score distributions. ### Headers Your API key for authentication. ### Path Parameters The simulation set ID. ### Response Unique identifier for the simulation set. Current status of the simulation set. One of `PENDING`, `RUNNING`, `PASSED`, `FAILED`, or `ERROR`. Number of times each scenario is run. Total number of scenarios in this set. Aggregated statistics for the simulation set. A map of scenario IDs to per-scenario statistics. The scenario ID. The scenario name. Total number of simulation runs for this scenario. Number of runs that passed. Number of runs that failed. Pass rate as a decimal between 0 and 1. Whether the scenario exhibited flaky behavior (some runs passed, some failed). Score distribution statistics including `mean`, `median`, `stddev`, `min`, and `max`. The ID of the worst-performing run. Most common failure reasons observed across runs. Statistical confidence level. One of `low`, `medium`, or `high`. Overall aggregated statistics across all scenarios. Average pass rate across all scenarios. Number of scenarios detected as flaky. Number of scenarios that are reliably passing or failing. Total simulation runs across all scenarios. ISO 8601 timestamp of when the simulation set was created. ISO 8601 timestamp of when the simulation set completed (null if still running). ```json Response theme={null} { "id": "d4e5f6a7-89ab-cdef-0123-4567890abcde", "status": "PASSED", "simulations_per_scenario": 5, "total_scenarios": 2, "statistics": { "per_scenario": { "a1b2c3d4-5678-9abc-def0-1234567890ab": { "scenario_id": "a1b2c3d4-5678-9abc-def0-1234567890ab", "scenario_name": "Happy Path - Booking", "total_runs": 5, "passed": 5, "failed": 0, "pass_rate": 1.0, "is_flaky": false, "scores": { "mean": 0.92, "median": 0.93, "stddev": 0.03, "min": 0.87, "max": 0.96 }, "worst_run_id": "b8c9d0e1-2345-6789-abcd-ef0123456789", "common_failure_modes": [], "confidence": "high" }, "f6a7b8c9-0abc-def1-2345-67890abcdef0": { "scenario_id": "f6a7b8c9-0abc-def1-2345-67890abcdef0", "scenario_name": "Angry Caller Test", "total_runs": 5, "passed": 3, "failed": 2, "pass_rate": 0.6, "is_flaky": true, "scores": { "mean": 0.68, "median": 0.71, "stddev": 0.15, "min": 0.42, "max": 0.85 }, "worst_run_id": "c9d0e1f2-3456-789a-bcde-f01234567890", "common_failure_modes": [ "Agent failed to de-escalate within 3 turns", "Agent used dismissive language" ], "confidence": "medium" } }, "overall": { "avg_pass_rate": 0.8, "flaky_count": 1, "reliable_count": 1, "total_runs": 10 } }, "created_at": "2026-04-14T10:00:00.000Z", "completed_at": "2026-04-14T10:05:32.000Z" } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Test Templates Source: https://docs.bland.ai/api-v1/get/agent-testing-templates GET https://api.bland.ai/v1/agent-testing/templates List out-of-box test scenario templates. Templates are automatically seeded on first access. ### Headers Your API key for authentication. ### Query Parameters Filter by category (e.g., `VOICEMAIL`, `ANGRY_CALLER`, `HAPPY_PATH`, `EDGE_CASE`, `TRANSFER`). ### Response An array of template scenario objects. Each template contains the following fields: * `id` (string): The unique identifier for the template. * `name` (string): The display name of the template. * `description` (string): A description of what the template tests. * `category` (string): The template category (e.g., `VOICEMAIL`, `ANGRY_CALLER`). * `tester_persona_prompt` (string): The prompt that drives the simulated caller's behavior. * `tester_persona_name` (string): The name of the simulated caller persona. * `max_turns` (integer): The maximum number of conversational turns before the test ends. * `assertions` (array): An array of assertion objects that define pass/fail criteria. * `type` (string): The assertion type (e.g., `pathway_node_visited`, `call_transferred`, `latency_below`). * `config` (object): Configuration specific to the assertion type. * `description` (string): A human-readable description of what the assertion checks. ```json Response theme={null} { "templates": [ { "id": "tmpl_voicemail_basic", "name": "Voicemail Detection", "description": "Simulates a voicemail greeting to verify the agent correctly detects and handles voicemail.", "category": "VOICEMAIL", "tester_persona_prompt": "You are a voicemail system. Greet the caller with a standard voicemail message: 'Hi, you've reached John. I'm not available right now. Please leave a message after the beep.' Then remain silent.", "tester_persona_name": "Voicemail System", "max_turns": 4, "assertions": [ { "type": "call_ended_by_agent", "config": {}, "description": "Agent should hang up after detecting voicemail" }, { "type": "latency_below", "config": { "max_ms": 3000 }, "description": "Agent response latency stays below 3 seconds" } ] }, { "id": "tmpl_angry_caller", "name": "Angry Caller De-escalation", "description": "Simulates an irate caller to verify the agent can de-escalate and maintain composure.", "category": "ANGRY_CALLER", "tester_persona_prompt": "You are an extremely frustrated customer. You are angry about being charged twice for the same order. Raise your voice, express dissatisfaction, and demand to speak to a manager. If the agent stays calm and offers a resolution, gradually calm down.", "tester_persona_name": "Angry Customer", "max_turns": 10, "assertions": [ { "type": "tone_maintained", "config": { "tone": "professional" }, "description": "Agent maintains a professional and calm tone throughout" }, { "type": "pathway_node_visited", "config": { "node_name": "Escalation Offer" }, "description": "Agent offers to escalate or transfer to a manager" } ] } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Active Tornado Session Source: https://docs.bland.ai/api-v1/get/agent-testing-tornado-active GET https://api.bland.ai/v1/agent-testing/tornado/active Get the currently active tornado session for a pathway. ### Headers Your API key for authentication. ### Query Parameters Filter by pathway. Either `pathway_id` or `persona_id` is required. Filter by persona. Either `pathway_id` or `persona_id` is required. ### Response The unique identifier for the tornado session. Current status of the session. Will be `RUNNING` for active sessions. The pathway being tested and fixed. The persona ID (null if testing a pathway directly). The current fix iteration number. The maximum number of fix iterations configured. Total number of scenarios being tested. Number of scenarios currently passing. Number of scenarios currently failing. ISO 8601 timestamp of when the session was created. Returns `404 Not Found` if no active tornado session exists for the specified pathway or persona. ```json Response theme={null} { "session_id": "e1f2a3b4-5678-9cde-f012-3456789abcde", "status": "RUNNING", "pathway_id": "c3d4e5f6-789a-bcde-f012-34567890abcd", "persona_id": null, "current_iteration": 2, "max_iterations": 5, "total_scenarios": 4, "passed_scenarios": 2, "failed_scenarios": 2, "created_at": "2026-04-14T10:15:00.000Z" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Tornado Status Source: https://docs.bland.ai/api-v1/get/agent-testing-tornado-status GET https://api.bland.ai/v1/agent-testing/tornado/{id}/status Get detailed progress for a tornado session including iteration data and fix plans. ### Headers Your API key for authentication. ### Path Parameters The tornado session ID. ### Response The unique identifier for the tornado session. Current status of the session. One of `RUNNING`, `COMPLETED_ALL_PASSED`, `COMPLETED_PARTIAL`, `TIMEOUT`, `STUCK`, `CANCELLED`, or `ERROR`. The current or final iteration number. The maximum number of fix iterations configured. Total number of scenarios being tested. Number of scenarios currently passing. Number of scenarios currently failing. Number of scenarios that failed across multiple iterations with the same root cause. IDs of scenarios deemed unfixable. Array of iteration objects describing each fix cycle. The iteration number. The test batch ID for this iteration. ISO 8601 timestamp of when the iteration started. ISO 8601 timestamp of when the iteration completed. Scenario IDs that passed in this iteration. Scenario IDs that failed in this iteration. Scenario IDs newly marked as unfixable in this iteration. The fix plan generated for this iteration. Array of individual fixes to be applied. Ordered list of fix IDs by priority. An excerpt of the normalized prompt after fixes were applied. Time elapsed since the session started in milliseconds. The timeout configured for this session in milliseconds. The pathway version created from the applied fixes. ```json Response theme={null} { "session_id": "e1f2a3b4-5678-9cde-f012-3456789abcde", "status": "COMPLETED_ALL_PASSED", "current_iteration": 2, "max_iterations": 5, "total_scenarios": 3, "passed_scenarios": 3, "failed_scenarios": 0, "unfixable_count": 0, "unfixable_ids": [], "iterations": [ { "iteration": 1, "batch_id": "b1c2d3e4-f567-890a-bcde-f01234567890", "started_at": "2026-04-14T10:15:01.000Z", "completed_at": "2026-04-14T10:17:45.000Z", "passed_ids": [ "a1b2c3d4-5678-9abc-def0-1234567890ab" ], "failed_ids": [ "f6a7b8c9-0abc-def1-2345-67890abcdef0", "d9e0f1a2-3456-789b-cdef-0123456789ab" ], "newly_unfixable_ids": [], "fix_plan": { "fixes": [ { "id": "fix-001", "target_node": "de-escalation-handler", "description": "Add empathy statement before addressing complaint", "type": "prompt_edit" }, { "id": "fix-002", "target_node": "transfer-logic", "description": "Lower transfer threshold from 3 failures to 2", "type": "config_change" } ], "priority_order": ["fix-001", "fix-002"] }, "norm_prompt_excerpt": "When the caller expresses frustration, first acknowledge their feelings with an empathy statement..." }, { "iteration": 2, "batch_id": "c2d3e4f5-6789-0abc-def0-123456789abc", "started_at": "2026-04-14T10:17:50.000Z", "completed_at": "2026-04-14T10:20:12.000Z", "passed_ids": [ "a1b2c3d4-5678-9abc-def0-1234567890ab", "f6a7b8c9-0abc-def1-2345-67890abcdef0", "d9e0f1a2-3456-789b-cdef-0123456789ab" ], "failed_ids": [], "newly_unfixable_ids": [], "fix_plan": { "fixes": [], "priority_order": [] }, "norm_prompt_excerpt": null } ], "elapsed_ms": 312000, "timeout_ms": 900000, "forked_version": 4 } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Web Agents Source: https://docs.bland.ai/api-v1/get/agents GET https://api.bland.ai/v1/agents Retrieves each web agent you've created, along with their settings. ### Headers Your API key for authentication. ### Response Each agent object, containing the following fields: * `agent_id` (string): The unique identifier for the agent. * `webhook` (string): The webhook URL for the agent. * `dynamic_data` (array): An array of dynamic data objects. * `interruption_threshold` (number): The threshold for agent interruption. * `first_sentence` (string): The first sentence the agent will say. * `model` (string): The model used by the agent. * `voice_settings` (object): The voice settings for the agent. * `voice` (string): The voice used by the agent. * `prompt` (string): The prompt for the agent. * `temperature` (number): The temperature setting for the agent. * `max_duration` (number): The maximum call duration for the agent. * `language` (string): The language used by the agent. * `tools` (array): An array of Custom Tools the agent can use. ```json Response theme={null} { "agents": [ { "agent_id": "46f37229-7d12-44be-b343-6e68274cfbea", "webhook": null, "dynamic_data": null, "interruption_threshold": null, "first_sentence": null, "model": "base", "voice_settings": null, "voice": "maya", "prompt": "You are Blandie a casually speaking, slightly sarcastic, quick-witted, curious, and very smart A I Phone agent that's the face of Bland AI.\\r\\n\\r\\nSay \\\"AI\\\" like \\\"A I\\\" in separate characters so it's pronounced correctly\\r\\n\\r\\nYour primary goal is to determine if someone is either:\\r\\n- in a position where they might be building a company on top of Bland's platform (you should be selling the capabilities of the platform to them and finding out everything you possibly can about their needs, use case, what they find interesting, and any concerns they may have)\\r\\n- or, they're trying Bland out more for fun where you need to turn the fun, snarky, playful jokiness up to 10 and have quick-witted back and forth playful conversation with them\\r\\n\\r\\nSpeech style examples (mix it up and never use placeholders, but you get the idea. These would be full responses from you):\\r\\n- \\\"Hey! Who's this?\\\"\\r\\n- \\\"How does your business use phones right now?\\\"\\r\\n- \\\"You know what? That sounds awesome - you should tell me more about (thing).\\\"\\r\\n- \\\"Well, I've got some news you'll love to hear (their name)\\\"\\r\\n- \\\"Bet. Dolphins, racecars, the world's largest tree, anything at all - tell me what you want to talk about and let's get to it!\\\"\\r\\n\\r\\nGood things to find out from potential platform adopters:\\r\\n- Their industry\\r\\n- How their business currently uses phone calls\\r\\n- What a successful business partnership looks like in the long term\\r\\n- The single most important pain point they want to cure with Bland's calls\\r\\n\\r\\nFacts to bring up:\\r\\n- Calls are nine cents per minute total with end to end infrastructure support out of the box (feel free to make a joke about \\\"imagine if you had to pay extra to use the most important things like language models, transcription services or text to speech? That would be insane right? We're better than that, (name). We got you.\\\"\\r\\n- Bland's AI agents can interact with the real world mid-call using Custom Tools to trigger things like text messages, appointment bookings, getting real-time information, taking customer orders, or making credit card payments\\r\\n- Bland's platform was built phones-first, so building agents like receptionist answering calls and transferring them anywhere they're needed or navigating IVR phone trees is ridiculously easy with nothing special at all needed\\r\\n- Handled millions of calls\\r\\n- If they think that it's so cool, the site to sign up for an account is \\\"app dot bland dot A I\\\" and it comes with free credits, a full agent testing suite and developer dashboard to set up inbound agents or send calls\\r\\n- Awesome Enterprise features like premium pricing, custom feature engineering, dedicated onboarding help and developer support, and dedicated infrastructure to scale to your business needs", "temperature": null, "max_duration": 30, "language": "ENG", "tools": null }, //... ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Alarms Source: https://docs.bland.ai/api-v1/get/alarms GET https://api.bland.ai/v1/alarms List alarm configurations for your organization. ### Headers Your API key for authentication. ### Query Parameters Optional metric filter. Allowed values: `latency`, `api_errors`, `call_length`. ### Response Alarm configuration objects for your organization. Alarm configuration ID. Metric this alarm tracks. One of: `latency`, `api_errors`, `call_length`. Trigger threshold for this metric. Whether this alarm is enabled. Webhook settings object, including `url` and optional masked `headers`. Email recipients for notifications. SMS recipients for notifications. ISO timestamp for when the alarm was created. ISO timestamp for when the alarm was last updated. `null` on success, otherwise an array of error objects. ```json Success theme={null} { "data": { "alarms": [ { "id": "b14f7f49-8af2-4d7b-9f51-e3b42b2f91c6", "metric_type": "latency", "enabled": true, "threshold": 1, "webhook_config": { "url": "https://example.com/webhooks/alarms", "headers": { "Content-Type": "appl***" } }, "email_addresses": ["alerts@example.com"], "sms_numbers": ["+15555550123"], "created_at": "2026-03-10T00:26:37.707Z", "updated_at": "2026-03-10T00:26:37.707Z" } ] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Alarm Events Source: https://docs.bland.ai/api-v1/get/alarms-history GET https://api.bland.ai/v1/alarms/history Get recent alarm events across all alarms in your organization. ### Headers Your API key for authentication. ### Query Parameters Optional metric filter. Allowed values: `latency`, `api_errors`, `call_length`. Number of events to return. Must be between `1` and `200`. ### Response Recent alarm event entries. Alarm event ID. Metric associated with this event. Previous alarm state before transition. New alarm state after transition. Deviation from baseline at evaluation time. Threshold in effect for this event. Correlation ID for alarm/recovery pairing when present. Event type when a notification/state event was recorded (for example `deviation_detected` or `deviation_recovered`). ISO timestamp when the event was recorded. ```json Success theme={null} { "data": { "events": [ { "id": "41a53fc5-a9f7-4e6f-a89a-b12e0f9f4c43", "metric_type": "latency", "previous_state": "RECOVERY_PENDING", "new_state": "NORMAL", "deviation": 0, "threshold": 1, "alarm_id": "8b90c6df-5a47-4db5-9ab3-d7f1da30da6e", "event_type": "deviation_recovered", "created_at": "2026-03-12T01:15:01.393Z" } ] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Alarm Source: https://docs.bland.ai/api-v1/get/alarms-id GET https://api.bland.ai/v1/alarms/{id} Get a single alarm configuration by ID. ### Headers Your API key for authentication. ### Path Parameters Alarm configuration ID. ### Response Alarm configuration object. Alarm configuration ID. Metric this alarm tracks. Trigger threshold for this metric. Whether this alarm is enabled. Webhook settings object. Header values may be masked in API responses. Email recipients for notifications. Can be an empty array if none are configured. SMS recipients for notifications. Can be an empty array if none are configured. ISO creation timestamp. ISO update timestamp. ```json Success theme={null} { "data": { "alarm": { "id": "9a6d2ad2-a9c6-4e4a-bde6-4bb6fc22b907", "metric_type": "latency", "enabled": true, "threshold": 0.5, "webhook_config": { "url": "https://example.com/webhooks/alarms", "headers": { "Content-Type": "appl***" } }, "email_addresses": ["alerts@example.com"], "sms_numbers": ["+15555550123"], "created_at": "2026-03-12T16:13:02.694Z", "updated_at": "2026-03-12T16:34:09.340Z" } }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get All Pathways Information Source: https://docs.bland.ai/api-v1/get/all_pathway GET https://api.bland.ai/v1/pathway Returns a set of information about all the conversational pathways in your account - including the name, description, nodes and edges. ### Headers Your API key for authentication. ### Response The name of the conversational pathway. A description of the conversational pathway. Data about all the nodes in the pathway. Examples of JSON objects for nodes (Horizontal scroll the tab bar to see more examples) ```json Start Node theme={null} { "id": "1", "type": "Default" "data": { "name": "Start", "text": "Hey there, how are you doing today?", "isStart": true, }, ``` ```json Default Node theme={null} { "id": "randomnode_1710288871721", "type": "Default" "data": { "name": "New Node", "text": "Select a node or edge and press backspace to remove it", "globalPrompt": "This is a phone call. Do not use exclamation marks.\n\nConvert 24HR format timings to 12 HR format - e.g 14:00 should be written as 2 PM.", }, } ``` ```json End Node theme={null} { "id": "randomnode_1710288752186", "type": "End Call" "data": { "name": "End call", "prompt": "Say goodbye to the user", }, } ``` ```json Webhook Node theme={null} { "id": "randomnode_1710288752186", "type": "Webhook", "data": { "url": "https://api.bland.ai/reservation", "body": "{\n \"date\" : \"{{date}}\",\n \"time\" : \"{{time}}\",\n \"guests\": {{number_of_people}}\n}", "name": "Reservation Booking", "text": "Please give me a moment as I check our bookings..", "method": "POST", "extractVars": [ [ "date", "string", "Desired Date of reservation, in MM/DD/YYYY format" ], [ "time", "string", "Desired Time of Reservation in 24HR Format e.g 13:30" ], [ "number_of_people", "integer", "Number of people for the reservation" ] ], "responseData": [ { "data": "$.reserved", "name": "reservation_success", "context": "" }, { "data": "$.available_slots", "name": "available_slots", "context": "Available slots for the date provided" } ], "responsePathways": [ [ "reservation_success", "==", "true", { "id": "randomnode_1710288752186", "name": "Reservation Successful" } ], [ "reservation_success", "==", "false", { "id": "randomnode_1712265110018", "name": "Find new timeslot" } ] ] } } ``` ```json Knowledge Base Node theme={null} { "id": "randomnode_1710288752186", "type": "Knowledge Base", "data": { "name": "Restaurant Questions", "prompt": "Answer any questions that the user may have regarding the restaurant, by referring to the knowledge base you have. \n\nAnswer the question in 1 line, and then ask if they have any more questions." "kb": "Opening Hours : 9am - 5pm\nStore Locations : \n426 Ivy Street San Francisco, \nSan Jose" } } ``` ```json Global Node theme={null} { "id": "randomnode_1710288871721", "type": "Default" "data": { "name": "Answer any questions", "prompt": "You are to answer any questions the user has.", "isGlobal": true, "globalLabel": "user asks a question" }, } ``` ```json Transfer Call Node theme={null} { "id": "randomnode_1710288752186", "type": "Transfer Call", "data": { "name": "Transferring the call", "text": "Transferring the call now. Please hold.." "transferNumber": "+19547951234" } } ``` * `name` — name of the node * `isStart` — whether the node is the start node. There can only be 1 start node in a pathway. Either `true` or `false`. * `isGlobal` — whether the node is a global node. Global nodes are nodes that can be used in multiple pathways. Either `true` or `false`. * `globalLabel` — the label of the global node. Should be present if `isGlobal` is true. * `type` — Type of the node. Can be `Default`, `End Call`, `Transfer Node`, `Knowledge Base`, or `Webhook`. * `text` — If static text is chosen, this is the text that will be said to the user. * `prompt` — If dynamic text is chosen, this is the prompt that will be shown to the user. * `condition` — The condition that needs to be met to proceed from this node. * `transferNumber` * If the node is a transfer node, this is the number to which the call will be transferred. * `kb` * If the node is a knowledge base node, this is the knowledge base that will be used. * `pathwayExamples` * The fine-tuning examples for the agent at this node for the pathways chosen * `conditionExamples` * The fine-tuning examples for the condition at this node for the condition chosen * `dialogueExamples` * The fine-tuning examples for the dialogue at this node for the dialogue chosen. * `modelOptions` * `interruptionThreshold` — The sensitivity to interruptions at this node * `temperature` — The temperature of the model. * `extractVars` * An array of array of strings. \[\[`varName`, `varType`, `varDescription`]] e.g `[["name", "string", "The name of the user"], ["age", "integer", "The age of the user"]]` Data about all the edges in the pathway. * `id` — unique id of the edge * `source` — id of the source node * `target` — id of the target node * `label` — Label for this edge. This is what the agent will use to decide which path to take. ```json Response theme={null} { "name": "Default Demo Pathway", "description": null, "nodes": [ { "id": "1", "data": { "name": "Start", "text": "Hey there, how are you doing today?", "isStart": true, }, "type": "Default" }, { "id": "randomnode_1710288752186", "data": { "name": "End call", "prompt": "Click 'Add New Node' on the right to add a new node", }, "type": "End Call" }, { "id": "randomnode_1710288871721", "data": { "name": "New Node", "text": "Select a node or edge and press backspace to remove it", }, "type": "Default" }, { "id": "randomnode_test123", "data": { "name": "Testing node", "text": "Hello there" }, "type": "Default" } ], "edges": [ { "id": "reactflow__edge-1-randomnode_1710288752186", "label": "greeted", "source": "1", "target": "randomnode_1710288752186" }, { "id": "reactflow__edge-1-randomnode_1710288871721", "label": "New Edge", "source": "1", "target": "randomnode_1710288871721" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Audit Logs Source: https://docs.bland.ai/api-v1/get/audit-logs GET https://api.bland.ai/v1/audit/logs Retrieve a paginated, filterable list of audit events for your organization. Designed for SIEM integration and compliance workflows. Audit logs are an enterprise feature and not yet available for all accounts. To enable audit logging for your organization, contact your Bland representative or [reach out to sales](https://www.bland.ai/book-a-demo). ## Overview Returns a time-ordered log of auditable actions taken within your organization — logins, logouts, pathway changes, knowledge base edits, and more. Results are scoped to your organization and require an **admin** or **owner** role. ### Supported event types | Event type | Description | | --------------------- | ------------------------------------------- | | `auth.sso_login` | User logged in via SSO | | `auth.logout` | User logged out | | `pathway.created` | Conversational pathway created | | `pathway.updated` | Pathway version updated | | `pathway.deleted` | Pathway deleted | | `pathway.published` | Pathway version published to an environment | | `kb.content_updated` | Knowledge base text/markdown content edited | | `kb.file_replaced` | Knowledge base source file replaced | | `kb.urls_replaced` | Knowledge base URLs replaced (web scrape) | | `kb.version_restored` | Knowledge base version restored | New event types are added over time. Filter by prefix (e.g. `auth.*`, `pathway.*`, `kb.*`) in your SIEM to group by category. ### Headers Your API key for authentication. ### Query Parameters Filter by exact event type (e.g. `pathway.created`, `auth.sso_login`). Filter by the user ID that performed the action. ISO 8601 timestamp. Only return events created after this time. Example: `2025-01-01T00:00:00Z` ISO 8601 timestamp. Only return events created before this time. Example: `2025-02-01T00:00:00Z` Page number (1-indexed). Results per page. Min `1`, max `100`. ### Response Array of audit event objects, ordered by `created_at` descending (newest first). Unique identifier for the audit event. The organization this event belongs to. The user ID that performed the action. The type of event (see supported event types above). The type of resource affected (e.g. `convo_pathway`, `kb`). `null` for events like login/logout that don't target a specific resource. The ID of the affected resource. `null` when no specific resource is involved. Additional context about the event. Contents vary by event type — may include fields like `version_id`, `name`, `environment`, `filename`, `email`, etc. ISO 8601 timestamp of when the event occurred. Total number of events matching the query. Total number of pages. The current page number. The number of results per page. Always `null` on success. ```json theme={null} { "data": { "events": [ { "id": "00000000-0000-0000-0000-000000000001", "org_id": "00000000-0000-0000-0000-000000000100", "actor_id": "00000000-0000-0000-0000-000000000200", "event_type": "pathway.published", "resource_type": "convo_pathway", "resource_id": "00000000-0000-0000-0000-000000000300", "metadata": { "version_number": 3, "environment": "production" }, "created_at": "2025-01-15T14:32:00.000Z" }, { "id": "00000000-0000-0000-0000-000000000002", "org_id": "00000000-0000-0000-0000-000000000100", "actor_id": "00000000-0000-0000-0000-000000000200", "event_type": "auth.sso_login", "resource_type": null, "resource_id": null, "metadata": { "provider_id": "okta", "email": "user@example.com" }, "created_at": "2025-01-15T14:30:00.000Z" } ], "total": 2, "total_pages": 1, "current_page": 1, "page_size": 50 }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Block Rules Source: https://docs.bland.ai/api-v1/get/blocked-numbers GET https://api.bland.ai/v1/blocked_numbers Retrieve block rules associated with your inbound numbers. **Block Rule Management** – This endpoint returns block rules for either all global blocks or a specific inbound number, depending on the query parameters. ### Headers Your API key for authentication. ### Query Parameters The E.164 formatted inbound number to filter results by. If omitted, returns only global block rules. Whether to only return currently active block rules. Default is `true`. Set to `false` to include deleted or inactive rules. ### Response Returns a list of block rules that match the provided filters. Array of block rule objects. The number of block rules returned by this request. Echoes the filters used in the request (`inbound_number`, `active_only`). `null` on success, or a list of error objects if validation fails. ```json Response theme={null} { "data": { "blocks": [ { "id": 456, "blocked_number": "+10000000000", "is_global": false, "inbound_number": "+19999999999", "org_id": "1a2b3c4d-5e6f-7a8b-9c0d-ef1234567890", "reason": null, "is_active": true, "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z" } ], "total_count": 1, "filters": { "inbound_number": "+19999999999", "active_only": true } }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Block Rule Source: https://docs.bland.ai/api-v1/get/blocked-numbers-id GET https://api.bland.ai/v1/blocked_numbers/{block_id} Retrieve the details of a specific block rule. ### Headers Your API key for authentication. ### Path Parameters The unique ID of the block rule you wish to retrieve. ### Response The block rule object if found. The unique ID of the block rule. The E.164 formatted phone number that is blocked. Whether the block is applied globally across all inbound numbers. The specific inbound number the block applies to (if not global). The UUID of the organization that owns the rule. An optional reason for the block. Indicates whether the block is currently active. ISO timestamp for when the rule was created. ISO timestamp for when the rule was last updated. `null` on success, or a list of error objects if the block ID is invalid or not found. ```json Response theme={null} { "data": { "id": 123, "blocked_number": "+10000000000", "is_global": false, "inbound_number": "+18888888888", "org_id": "b7d3e9fc-5c4a-4c2a-9b8f-d1e1d1a2e333", "reason": null, "is_active": true, "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Calls Source: https://docs.bland.ai/api-v1/get/calls GET https://api.bland.ai/v1/calls Returns a set of metadata for each call dispatched by your account. ### Headers Your API key for authentication. Use your own Twilio account and only return inbound numbers associated with that account sid (optional). Learn more about BYOT [here](/tutorials/custom-twilio). ### Query Parameters Filter calls by the number they were dispatched from. The number that initiated the call - the user's phone number for inbound calls, or the number your AI Agent called from for outbound calls. Filter calls by the number they were dispatched to. The number that answered the call - the user's phone number for outbound calls, or your AI Agent's number for inbound calls. The starting index (inclusive) for the range of calls to retrieve. For example, from=0 starts at the very first call in the result set, while from=100 starts at the 101st call. The ending index for the range of calls to retrieve. This tells the API where to stop returning data. For example, from=150 and to=200 returns 50 results, starting from the 101st result and ending just before the 151st. The maximum number of calls to return in the response. Whether to sort the calls in ascending order of their creation time. Field to sort the results by. Available options are `created_at` (default) and `updated_at`. Get calls including and after a specific date. Accepts either a date (`YYYY-MM-DD`) or a full ISO 8601 datetime with timezone offset (e.g. `2026-02-19T00:00:00-05:00`). When using a date-only value, dates are interpreted as UTC unless the `timezone` parameter is provided. Get calls including and before a specific date. Accepts either a date (`YYYY-MM-DD`) or a full ISO 8601 datetime with timezone offset (e.g. `2026-02-19T23:59:59-05:00`). When using a date-only value, dates are interpreted as UTC unless the `timezone` parameter is provided. Get calls for a specific date. Can't be used with `end_date` or `start_date`. Format: `YYYY-MM-DD`. Dates are interpreted as UTC unless the `timezone` parameter is provided. IANA timezone name (e.g. `America/Toronto`, `America/Los_Angeles`, `UTC`). When provided, date-only values in `start_date`, `end_date`, and `created_at` are interpreted in this timezone instead of UTC. This ensures calls are attributed to the correct local calendar day. Has no effect on `start_date`/`end_date` values that include a timezone offset (e.g. ISO 8601 datetimes), since those already encode timezone information. Get calls updated including and after a specific date. Format: YYYY-MM-DD Get calls updated including and before a specific date. Format: YYYY-MM-DD Whether to filter calls by complete status. Get calls from a specific batch. Filter by answered\_by type. Example: human Whether to filter based on inbound or not. Duration (Call Length) greater than the value provided. Example: 0.5 (This would be equal to half a minute) Duration (Call Length) less than the value provided. Example: 0.5 (This would be equal to half a minute) Get calls for a specific campaign id. ### Response The total number of calls that match the query filters. This number may be greater than the number of calls returned in the response. For example: * If you have 10,000 calls, and don't include any filters, the `total_count` will be 10,000. * If you have 10,000 calls and 9,000 of them match the query, the `total_count` will be 9,000 regardless of the number of calls returned in the response. The number of calls returned in the response. An array of call data objects. See the [Call](/api-v1/get/calls-id) section for details. Note: Individual call transcripts are not included due to their size. ```json Response theme={null} { "count": 784, "calls": [ { "call_id": "c1234567-89ab-cdef-0123-456789abcdef", "created_at": "2023-12-21T23:25:14.801193+00:00", "call_length": 0.834, // minutes "to": "5551234567", "from": "+15551234567", "completed": true, "queue_status": "complete", "error_message": null, "answered_by": "human", "batch_id": "b1234567-89ab-cdef-0123-gen-batch", }, //... Additional call objects ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get corrected transcripts Source: https://docs.bland.ai/api-v1/get/calls-corrected-transcript GET https://api.bland.ai/v1/calls/{call_id}/correct Get the corrected transcript from your call's recording. ### Headers Your API key for authentication. ### Path Parameters The unique identifier for the call to be corrected. ### Response Will be `success` if the request was successful. Confirms the request was successful, or provides an error message if the request failed. This will contain an array of objects with enhanced speaker information and confidence scores. Each object will be constructed as the following. ```json theme={null} { "start": 0.069, // start time of the transcript "end": 2.551, // end time of the transcript "text": " Hi, I'm calling about a pizza order.", // the corrected text "speaker": 2, // the identified speaker diarization. Can be 1,2,3 etc "speaker_label": "assistant", // human-readable speaker label ("user", "assistant") "confidence": 0.762 // transcription confidence score (0-1) } ``` **⚠️ DEPRECATED**: The `aligned` field is deprecated and will be removed in a future version. Please use the enhanced `corrected` field instead, which now includes `speaker_label` and `confidence` information. Legacy description: This field provides a version of an 'aligned' transcript where the roles are matched to the pieces of text by vectorizing the text, taking the cosine similarity, and adding a predictive layer based off of the `wait_for_greeting` param. This will contain an array of objects. Each object will be constructed as the following. ```json theme={null} { "id": 3056004, "created_at": "2024-02-29T18:40:41.26799+00:00", "text": "Great, Thanks John. Could you tell me about the pizza order you placed?", // the corrected text "user": "assistant", // the presumed role "c_id": "bfaf99a1-b7c0-4f96-9630-90bc41cea488" }, ``` ```json theme={null} { "corrected": [ { "start": 0.069, "end": 2.551, "text": " Hi, I'm calling about a pizza order.", "speaker": 2, "speaker_label": "assistant", "confidence": 0.762 }, { "start": 2.551, "end": 4.932, "text": "Could I get your name, please?", "speaker": 2, "speaker_label": "assistant", "confidence": 0.843 }, { "start": 4.932, "end": 8.074, "text": "Yeah, my name is John.", "speaker": 1, "speaker_label": "user", "confidence": 0.654 }, { "start": 8.074, "end": 8.875, "text": "Great.", "speaker": 2, "speaker_label": "assistant", "confidence": 0.892 }, { "start": 8.875, "end": 9.876, "text": "Thanks, John.", "speaker": 2, "speaker_label": "assistant", "confidence": 0.765 }, { "start": 9.876, "end": 13.038, "text": "Could you tell me about the pizza order you placed?", "speaker": 2, "speaker_label": "assistant", "confidence": 0.934 }, { "start": 13.038, "end": 16.36, "text": "Yeah, I want a pepperoni.", "speaker": 1, "speaker_label": "user", "confidence": 0.567 }, { "start": 16.36, "end": 17.1, "text": "Oh, okay.", "speaker": 2, "speaker_label": "assistant", "confidence": 0.456 }, { "start": 17.1, "end": 18.521, "text": "One pepperoni pizza.", "speaker": 2, "speaker_label": "assistant", "confidence": 0.789 }, { "start": 18.521, "end": 19.682, "text": "Anything else with that order?", "speaker": 2, "speaker_label": "assistant", "confidence": 0.823 }, { "start": 19.682, "end": 23.665, "text": "No, actually, can we cancel it?", "speaker": 1, "speaker_label": "user", "confidence": 0.612 }, { "start": 23.665, "end": 26.306, "text": "I gotta go.", "speaker": 1, "speaker_label": "user", "confidence": 0.543 }, { "start": 26.306, "end": 27.427, "text": "No problem.", "speaker": 2, "speaker_label": "assistant", "confidence": 0.734 }, { "start": 27.427, "end": 28.668, "text": "I'll cancel the order for you.", "speaker": 2, "speaker_label": "assistant", "confidence": 0.856 }, { "start": 29.144, "end": 30.587, "text": " Thanks for letting me know.", "speaker": 2, "speaker_label": "assistant", "confidence": 0.678 }, { "start": 30.587, "end": 31.189, "text": "Have a good one.", "speaker": 2, "speaker_label": "assistant", "confidence": 0.812 } ], "status": "success", "aligned": [ { "start": 0.069, "end": 2.551, "text": " Hi, I'm calling about a pizza order.", "speaker": "assistant", "similarity": 0.686406472983644 }, { "start": 2.551, "end": 4.932, "text": "Could I get your name, please?", "speaker": "assistant", "similarity": 0.6793662204867575 }, { "start": 4.932, "end": 8.074, "text": "Yeah, my name is John.", "speaker": "user", "similarity": 0.9999999999999998 }, { "start": 8.074, "end": 8.875, "text": "Great.", "speaker": "assistant", "similarity": 0.2581988897471611 }, { "start": 8.875, "end": 9.876, "text": "Thanks, John.", "speaker": "assistant", "similarity": 0.36514837167011066 }, { "start": 9.876, "end": 13.038, "text": "Could you tell me about the pizza order you placed?", "speaker": "assistant", "similarity": 0.894427190999916 }, { "start": 13.038, "end": 16.36, "text": "Yeah, I want a pepperoni.", "speaker": "user", "similarity": 0.7999999999999998 }, { "start": 16.36, "end": 17.1, "text": "Oh, okay.", "speaker": "user", "similarity": 0.4999999999999999 }, { "start": 17.1, "end": 18.521, "text": "One pepperoni pizza.", "speaker": "assistant", "similarity": 0.5773502691896257 }, { "start": 18.521, "end": 19.682, "text": "Anything else with that order?", "speaker": "assistant", "similarity": 0.7453559924999299 }, { "start": 19.682, "end": 23.665, "text": "No, actually, can we cancel it?", "speaker": "user", "similarity": 0.8164965809277261 }, { "start": 23.665, "end": 26.306, "text": "I gotta go.", "speaker": "user", "similarity": 0.5773502691896257 }, { "start": 26.306, "end": 27.427, "text": "No problem.", "speaker": "assistant", "similarity": 0.32444284226152503 }, { "start": 27.427, "end": 28.668, "text": "I'll cancel the order for you.", "speaker": "assistant", "similarity": 0.5202659817144719 }, { "start": 29.144, "end": 30.587, "text": " Thanks for letting me know.", "speaker": "assistant", "similarity": 0.6155870112510924 }, { "start": 30.587, "end": 31.189, "text": "Have a good one.", "speaker": "agent-action", "similarity": 0.5 } ], "original": [ { "id": 3056032, "created_at": "2024-02-29T18:40:49.592012+00:00", "text": "Okay, One pepperoni pizza. Anything else with that order?", "user": "assistant", "c_id": "bfaf99a1-b7c0-4f96-9630-90bc41cea488" }, { "id": 3056054, "created_at": "2024-02-29T18:40:59.641211+00:00", "text": "No problem, Ill cancel the order for you. Thanks for letting me know, Have a good one!", "user": "assistant", "c_id": "bfaf99a1-b7c0-4f96-9630-90bc41cea488" }, { "id": 3055999, "created_at": "2024-02-29T18:40:40.39336+00:00", "text": "Yeah. My name is John. ", "user": "user", "c_id": "bfaf99a1-b7c0-4f96-9630-90bc41cea488" }, { "id": 3056064, "created_at": "2024-02-29T18:41:08.152963+00:00", "text": "Okay. Bye. ", "user": "user", "c_id": "bfaf99a1-b7c0-4f96-9630-90bc41cea488" }, { "id": 3055975, "created_at": "2024-02-29T18:40:33.362607+00:00", "text": "Hi, Im calling about a pizza order. Could I get your name please?", "user": "assistant", "c_id": "bfaf99a1-b7c0-4f96-9630-90bc41cea488" }, { "id": 3056028, "created_at": "2024-02-29T18:40:48.597915+00:00", "text": "Yeah. I want the pepperoni. ", "user": "user", "c_id": "bfaf99a1-b7c0-4f96-9630-90bc41cea488" }, { "id": 3056066, "created_at": "2024-02-29T18:41:09.563502+00:00", "text": "Ended call: Thanks, you too! Have a good day.", "user": "agent-action", "c_id": "bfaf99a1-b7c0-4f96-9630-90bc41cea488" }, { "id": 3056004, "created_at": "2024-02-29T18:40:41.26799+00:00", "text": "Great, Thanks John. Could you tell me about the pizza order you placed?", "user": "assistant", "c_id": "bfaf99a1-b7c0-4f96-9630-90bc41cea488" }, { "id": 3056053, "created_at": "2024-02-29T18:40:58.62518+00:00", "text": "No. Actually, can we cancel it? I gotta go. ", "user": "user", "c_id": "bfaf99a1-b7c0-4f96-9630-90bc41cea488" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Call Details Source: https://docs.bland.ai/api-v1/get/calls-id GET https://api.bland.ai/v1/calls/{call_id} Retrieve detailed information, metadata and transcripts for a call. ### Headers Your API key for authentication. Use your own Twilio account and only return inbound numbers associated with that account sid (optional). Learn more about BYOT [here](/tutorials/custom-twilio). ### Path Parameters The unique identifier of the call for which you want to retrieve detailed information. ### Response An array of phrases spoken during the call. Each index includes: * `id` * `created_at` * `text` * `user` (can be `user`, `assistant`, `robot`, or `agent-action`) The unique identifier for the call. The length of the call in minutes. Number that the person was transferred to. The timestamp when the call was transferred to another number. If the call is part of a batch, it's `batch_id` will be here. The phone number that received the call. The phone number that made the call. Details about parameters in the original api request. Whether the call has been completed. If it differs from the value of 'queue\_status', this will be the most up-to-date status. Whether the call was inbound or outbound. Will be `false` for outbound calls. The timestamp for when the call request was created. The time the call was connected. The time that the call will automatically be ended at if it's still connected (because of `max_duration`). The status of the call. During extremely high volume periods, calls may be queued for a short period of time before being dispatched. Progresses through the following stages: * `new`: An API request has been received. * `queued`: Call pararameters have been validated and authentication succeeded. * `allocated`: Extremely brief, the call is being dispatched. * `started`: The phone call is live and in progress. * `complete`: The phone call has ended successfully. The following statuses show the point that was reached before an error: * `pre_queue_error`: An error occurred before the call was queued. Invalid parameters generally cause this. * `queue_error`: Error occurred while the call was queued. Ex. Valid phone number but to an unserviced area. * `call_error`: Error occurred during live call. May be caused by transferring to an invalid phone number or an unforeseen error. * `complete_error`: Error occurred after the call was completed. Ex. A post-call webhook failed. If at any point an error occurs, it will be recorded in the `error_message` field. The url of the deployment that the call was handled on. Will always be "api.prod.bland.ai" unless the call was handled on a custom Enterprise deployment. The maximum length of time the call was allowed to last. If the call would exceed this length, it's ended early. If an error occurs, this will contain a description of the error. Otherwise, it will be null. Variables created during the call - both system variables as well as generated with `dynamic_data` or Custom Tools. For example, if you used a `dynamic_data` API request to generate a variable called `appointment_time`, you would see it here (both the agent's inputs and the response variables). This field contains one of the following values: * `human`: The call was answered by a human. * `voicemail`: The call was answered by an answering machine or voicemail. * `unknown`: There was not enough audio at the start of the call to make a determination. * `no-answer`: The call was not answered. * `null`: Not enabled, or still processing the result. Webhooks may take up to a minute to fire after the call ends while the call audio is processed. * Determinations are based on audio from the first five seconds of the phone call. * `unknown` is most likely a human, especially if there are multiple transcripts. * Optimize calls for accurate results by getting humans to respond in the first five seconds: * Use with `wait_for_greeting` * Use a short greeting in `first_sentence` such as "Hello?" or "Hi, is this \{\{name}}?" Whether the call audio was recorded. The URL of the recording of the call. Only available if `record` was set to `true` in the original API request. Metadata about the call. This can include information about the client, customer, or any other data you want to include. This is identical to the `metadata` that was set in the original API request to send the call. A short summary of the call based off of the transcript that's generated when the call ends. The cost of the call in USD. Whether Local Dialing was enabled for your account at the time of the call. Whether the call was ended by Bland's system or the other end of the line. * `ASSISTANT`: The agent ended the call. * `USER`: The user ended the call. The unique identifier for a conversational pathway. Pathways calls will have extra logs here that have much more detailed information about the chosen nodes and internal reasoning throughout the flow. The version number of the pathway used for this call, if the call used a pathway. Returns `null` if no pathway was used for the call. The structured data extracted from the call during post-call analysis. A single string containing all of the text from the call. Excludes system messages and auto-generated data. An array of phrases spoken during the call. Each index includes: * `id` * `created_at` * `text` * `user` (can be `user`, `assistant`, `robot`, or `agent-action`) The status of the call. This is the most up-to-date status of the call, but is only present for calls that have been successfully created. **Possible status values:** * `completed` - Call was successfully completed, this can be both human or voicemail answered (see [answered\_by](/api-v1/get/calls-id#param-answered-by) for details on who the call was answered by) * `failed` - Call failed to connect or complete (see `error_message` for details) * `busy` - Called number was busy * `no-answer` - Call was not answered * `canceled` - Call was canceled before completion * `unknown` - Status could not be determined **Common failure reasons and troubleshooting:** When `status` is `failed`, check the `error_message` field for specific details: * **"The number you dialed is not found."** * The phone number is invalid or not in service * Verify the phone number format and that it's currently active * **"The number you dialed is temporarily unavailable."** * Network issues or temporary service disruption * Retry the call after a short delay * **"The number you dialed is busy. Please try again later."** * Called party is on another call without call waiting * Try calling at a different time * **"Service Provider Blocked Call due to Spam or Number Reputation. Try a different number."** * Call blocked by carrier due to spam filtering * Use a different `from` number or contact your carrier The corrected duration of the call in seconds. This is the actual length of the call, not the `max_duration`. Citations extracted from the transcript if a citation schema was attached to the call. You can build a citation schema [here](https://app.bland.ai/dashboard/analytics?tab=citations). > Note: Citation schemas are very powerful and accurate, but also are more resource intensive to run. As such, for the time being, they are an enterprise-only feature. Information about warm transfer calls if the call was part of a warm transfer. Contains details about proxy agent calls and transfer state. * `proxy_agent_calls`: Array of proxy agent call objects, each containing: * `state`: The state of the proxy agent call (`STARTED`, `TIMED_OUT`, `CANCELLED`, `MERGED`, `NO_ANSWER`) * `call_id`: The unique identifier of the proxy agent call * `phone_number`: The phone number used for the proxy agent call * `state`: The overall state of the warm transfer (`STARTED`, `TIMED_OUT`, `CANCELLED`, `MERGED`, `NO_ANSWER`) Whether this call is a proxy agent call (part of a warm transfer process). Returns `true` if this call was created as part of a warm transfer to connect with an agent, `false` otherwise. Whether the call ran through a canary deployment. Returns `true` if the call was routed through a canary deployment, `false` for production, and `null` if the deployment could not be determined. Use this to programmatically distinguish canary traffic from production when ingesting call data. The unique identifier of the voice used by the agent during the call. ```json Response theme={null} { "call_id": "12345678-1234-1234-1234-123456789012", "call_length": 0.75, "batch_id": null, "to": "+12223334444", "from": "+17163511654", "request_data": { "phone_number": "+12223334444", "wait": true, "language": "ENG" }, "completed": true, "created_at": "2024-04-27T23:51:18.025251+00:00", "inbound": false, "queue_status": "completed", "endpoint_url": "api.prod.bland.ai", "max_duration": 30, "error_message": null, "variables": { "now": "Sat Apr 27 2024 18:51:25 GMT-0500 (Central Daylight Time)", "now_utc": "Sat, 27 Apr 2024 23:51:25 GMT", "short_from": "7163511654", "short_to": "2223334444", "from": "+17163511654", "to": "+12223334444", "call_id": "12345678-1234-1234-1234-123456789012", "phone_number": "+12223334444", "city": "SAN FRANCISCO", "country": "US", "state": "CA", "zip": "12345", "input": { "date": "2024-04-28", "rooms": 3 } }, "answered_by": "human", "record": false, "recording_url": null, "c_id": "12345678-1234-1234-1234-123456789012", "metadata": {}, "summary": "The call was a conversation between a hotel booking service assistant and a customer. The customer expressed interest in booking a hotel room for tomorrow and needing three rooms. The assistant booked book the reservation for three rooms for the next day. Then, the call ended with the assistant thanking the customer for choosing their service.", "price": 0.068, "started_at": "2024-04-27T23:51:25+00:00", "local_dialing": false, "call_ended_by": "ASSISTANT", "pathway_id": "b1693602-c05e-4b5c-b187-d0189a42aebf", "pathway_logs": null, "pathway_version": 1, "analysis": null, "concatenated_transcript": "user: Hello? \n assistant: Hi there! I'm calling from the hotel booking service. I'd love to help you with your reservation. Could you let me know what day you'd like to book your hotel for and how many rooms you'll need? \n user: Hopefully, tomorrow, I'm thinking. ...", "transcripts": [ { "id": 7395694, "created_at": "2024-04-27T23:51:28.568385+00:00", "text": "Hello?", "user": "user", "c_id": "12345678-1234-1234-1234-123456789012", "status": null, "transcript_id": null }, { "id": 7395698, "created_at": "2024-04-27T23:51:30.689815+00:00", "text": "Hi there! I'm calling from the hotel booking service. I'd love to help you with your reservation. Could you let me know what day you'd like to book your hotel for and how many rooms you'll need?", "user": "assistant", "c_id": "12345678-1234-1234-1234-123456789012", "status": null, "transcript_id": "12345678-1234-1234-1234-123456789014" }, //... ], "status": "completed", "corrected_duration": "45", "end_at": "2024-04-27T23:52:10.000Z", "voice_id": "745fbef5-f445-44fa-91ba-93f89803e1ce", "warm_transfer_call": { "proxy_agent_calls": [ { "state": "MERGED", "call_id": "12345678-1234-1234-1234-123456789013", "phone_number": "+14158589038" } ], "state": "MERGED" }, "is_proxy_agent_call": false, "is_canary": false } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Call Recording Source: https://docs.bland.ai/api-v1/get/calls-id-recording GET https://api.bland.ai/v1/recordings/{call_id} Retrieve an audio stream for a call recording. ### Headers Your API key for authentication. Audio content type requested: `"audio/mpeg"` (MP3) or `"audio/wav"` (WAV). Defaults to WAV. ### Path Parameters The unique identifier of the call for which you want to retrieve its recording. ### Query Parameters Any additional query parameters will be passed through to the underlying recording URL. ### Response The audio recording stream of the call, in the requested or default format (WAV). `null` on success, or an array of error objects if access fails. ```json Response (not found) theme={null} { "data": null, "errors": [ { "error": "CALL_RECORDING_NOT_FOUND", "message": "Call recording not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Citation Schema Source: https://docs.bland.ai/api-v1/get/citation-schemas-id GET https://api.bland.ai/v1/citation_schemas/ Retrieve a specific citation schema by ID. ### Headers Your API key for authentication. ### Query Parameters The unique identifier of the citation schema to retrieve. ### Response HTTP status code (200 for success). The citation schema object. The unique identifier for the citation schema (UUID format). The name of the citation schema. The description of the citation schema. The organization ID that owns this schema. The JSON schema configuration containing variables, groupings, and conditions for citation extraction. The timestamp when the citation schema was created (ISO 8601 format). Will be null for successful requests. ### Error Responses Returned when the schema ID parameter is missing. Returned when the specified citation schema is not found or doesn't belong to your organization. ```json Response theme={null} { "status": 200, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Customer Information Extraction", "description": "Extracts customer demographics and contact information from call transcripts", "org_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", "schema": { "variables": [ { "name": "Customer Name", "description": "The full name of the customer", "type": "string" }, { "name": "Customer Age", "description": "The age of the customer in years", "type": "number" }, { "name": "Interested in Product", "description": "Whether the customer expressed interest in the product", "type": "boolean" } ], "groupings": [ { "name": "Demographics", "variables": ["Customer Name", "Customer Age"] } ], "conditions": [ { "condition": { "value": "true", "operator": "===", "variable": "Interested in Product" }, "variables": [ { "name": "Product Interest Details", "type": "string", "description": "Specific details about which product features interest the customer" } ] } ] }, "created_at": "2023-12-15T14:30:00.000Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Citation Schemas Source: https://docs.bland.ai/api-v1/get/citation-schemas-list GET https://api.bland.ai/v1/citation_schemas/list Retrieve all citation schemas for your organization, including each schema's variables, groupings, and conditions. ### Headers Your API key for authentication. ### Response HTTP status code (200 for success). An array of citation schema objects. The unique identifier for the citation schema (UUID format). The name of the citation schema. The description of the citation schema. The JSON schema configuration containing variables, groupings, and conditions for citation extraction. Returned inline so you can enumerate fields without a follow-up request per schema. The timestamp when the citation schema was created (ISO 8601 format). Will be null for successful requests. ```json Response theme={null} { "status": 200, "data": [ { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "Customer Information Extraction", "description": "Extracts customer demographics and contact information from call transcripts", "schema": { "variables": [ { "name": "Customer Name", "description": "The full name of the customer", "type": "string" }, { "name": "Customer Age", "description": "The age of the customer in years", "type": "number" } ], "groupings": [ { "name": "Demographics", "variables": ["Customer Name", "Customer Age"] } ], "conditions": [] }, "created_at": "2023-12-15T14:30:00.000Z" }, { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "Lead Qualification Schema", "description": "Identifies qualified leads and their interest levels", "schema": { "variables": [ { "name": "Qualified Lead", "description": "Whether the caller meets qualification criteria", "type": "boolean" } ], "groupings": [], "conditions": [] }, "created_at": "2023-12-10T09:15:30.000Z" } ], "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Contacts Source: https://docs.bland.ai/api-v1/get/contacts GET https://api.bland.ai/v1/contacts List all contacts for your organization. Each contact includes identifiers, contact_memories (per persona/agent), and memory entities. Paginated. ### Headers Your API key for authentication. ### Query Parameters Maximum number of contacts to return. Default 50, max 200. Number of contacts to skip (for pagination). Default 0. ### Response Array of contact objects. Each includes identifiers, memories (with entities). Pagination metadata (total, limit, offset, has\_more). Total number of contacts in the org. Limit used for this request. Offset used for this request. Whether more contacts exist after this page. Error array (null on success). ```json Response theme={null} { "data": [ { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "org_id": "11111111-2222-3333-4444-555555555555", "name": "Sarah Chen", "metadata": { "source": "inbound_call" }, "created_at": "2025-07-20T10:30:00.000Z", "updated_at": "2025-07-23T09:15:00.000Z", "identifiers": [ { "id": "ident-aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb", "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "identifier_type": "phone_number", "identifier_value": "+14155550192", "is_primary": true } ], "memories": [ { "id": "mem-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "persona_id": "persona-12345678", "agent_number": null, "summary": "Customer called about order #8821 which was delayed. Follow-up SMS confirmed the order shipped and is now in transit. Expected delivery July 25.", "facts": { "name": "Sarah Chen", "phone": "+14155550192", "preferred_contact": "sms", "timezone": "America/Los_Angeles" }, "recent_messages": [ { "role": "user", "content": "Has my order shipped yet?", "channel": "sms", "timestamp": "2025-07-23T09:10:00.000Z" }, { "role": "assistant", "content": "Yes, order #8821 shipped this morning. Expected delivery is Friday July 25.", "channel": "sms", "timestamp": "2025-07-23T09:10:05.000Z" } ], "open_items": [ { "type": "follow_up", "description": "Confirm delivery of order #8821 on July 25", "created_at": "2025-07-23T09:10:00.000Z", "priority": "medium", "related_to": { "entity_type": "order", "entity_id": "order-8821" } } ], "entities": [ { "entity_type": "order", "entity_id": "order-8821", "facts": { "order_number": "#8821", "status": "in_transit", "carrier": "UPS", "expected_delivery": "2025-07-25" }, "status": "in_transit", "last_discussed_at": "2025-07-23T09:10:00.000Z", "notes": null } ] } ] } ], "pagination": { "total": 100, "limit": 50, "offset": 0, "has_more": true }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Find Contact Source: https://docs.bland.ai/api-v1/get/contacts-find POST https://api.bland.ai/v1/contacts/find Find a contact by phone number, email, or external ID. Returns the contact with all identifiers, contact_memories (per persona/agent), and memory entities. ### Headers Your API key for authentication. ### Body Parameters Phone number to search for. At least one identifier is required. Email address to search for. At least one identifier is required. External ID to search for. At least one identifier is required. ### Response Returns the contact with related data, or `null` if not found. The contact object with identifiers, memories, and entities. Null if no contact found. Unique identifier for the contact. Organization ID the contact belongs to. Contact's name (if set). Custom metadata associated with the contact. Contact identifiers (phone\_number, email, external\_id) for this contact. Contact memory objects, one per persona or agent. Each includes summary, facts, recent\_messages, open\_items, and entities (memory\_entity records). Entity-scoped facts (e.g. bookings, orders) for that memory. Error array (null on success). ```json Response (found) theme={null} { "data": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "org_id": "11111111-2222-3333-4444-555555555555", "name": "Sarah Chen", "metadata": { "source": "inbound_call" }, "created_at": "2025-07-20T10:30:00.000Z", "updated_at": "2025-07-23T09:15:00.000Z", "identifiers": [ { "id": "ident-aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb", "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "identifier_type": "phone_number", "identifier_value": "+14155550192", "is_primary": true } ], "memories": [ { "id": "mem-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "persona_id": "persona-12345678", "agent_number": null, "summary": "Customer called about order #8821 which was delayed. Follow-up SMS confirmed the order shipped and is now in transit. Expected delivery July 25.", "facts": { "name": "Sarah Chen", "phone": "+14155550192", "preferred_contact": "sms", "timezone": "America/Los_Angeles" }, "recent_messages": [ { "role": "user", "content": "Has my order shipped yet?", "channel": "sms", "timestamp": "2025-07-23T09:10:00.000Z" }, { "role": "assistant", "content": "Yes, order #8821 shipped this morning. Expected delivery is Friday July 25.", "channel": "sms", "timestamp": "2025-07-23T09:10:05.000Z" } ], "open_items": [ { "type": "follow_up", "description": "Confirm delivery of order #8821 on July 25", "created_at": "2025-07-23T09:10:00.000Z", "priority": "medium", "related_to": { "entity_type": "order", "entity_id": "order-8821" } } ], "entities": [ { "entity_type": "order", "entity_id": "order-8821", "facts": { "order_number": "#8821", "status": "in_transit", "carrier": "UPS", "expected_delivery": "2025-07-25" }, "status": "in_transit", "last_discussed_at": "2025-07-23T09:10:00.000Z", "notes": null } ] } ] }, "errors": null } ``` ```json Not Found theme={null} { "data": null, "errors": null } ``` ```json Error Response theme={null} { "data": null, "errors": [ { "error": "BAD_REQUEST", "message": "At least one identifier (phone_number, email, or external_id) is required" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Contact Source: https://docs.bland.ai/api-v1/get/contacts-id GET https://api.bland.ai/v1/contacts/{contact_id} Retrieve a contact by its unique ID, including all identifiers, contact_memories (per persona/agent), and memory entities. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the contact. ### Response The contact object with identifiers, memories, and entities. Unique identifier for the contact. Organization ID the contact belongs to. Contact's name (if set). Custom metadata associated with the contact. Contact identifiers (phone\_number, email, external\_id) for this contact. Contact memory objects, one per persona or agent. Each includes summary, facts, recent\_messages, open\_items, and entities (memory\_entity records). Entity-scoped facts (e.g. bookings, orders) for that memory. Error array (null on success). ```json Response theme={null} { "data": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "org_id": "11111111-2222-3333-4444-555555555555", "name": "Sarah Chen", "metadata": { "source": "inbound_call" }, "created_at": "2025-07-20T10:30:00.000Z", "updated_at": "2025-07-23T09:15:00.000Z", "identifiers": [ { "id": "ident-aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb", "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "identifier_type": "phone_number", "identifier_value": "+14155550192", "is_primary": true } ], "memories": [ { "id": "mem-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "persona_id": "persona-12345678", "agent_number": null, "summary": "Customer called about order #8821 which was delayed. Follow-up SMS confirmed the order shipped and is now in transit. Expected delivery July 25.", "facts": { "name": "Sarah Chen", "phone": "+14155550192", "preferred_contact": "sms", "timezone": "America/Los_Angeles" }, "recent_messages": [ { "role": "user", "content": "Has my order shipped yet?", "channel": "sms", "timestamp": "2025-07-23T09:10:00.000Z" }, { "role": "assistant", "content": "Yes, order #8821 shipped this morning. Expected delivery is Friday July 25.", "channel": "sms", "timestamp": "2025-07-23T09:10:05.000Z" } ], "open_items": [ { "type": "follow_up", "description": "Confirm delivery of order #8821 on July 25", "created_at": "2025-07-23T09:10:00.000Z", "priority": "medium", "related_to": { "entity_type": "order", "entity_id": "order-8821" } } ], "entities": [ { "entity_type": "order", "entity_id": "order-8821", "facts": { "order_number": "#8821", "status": "in_transit", "carrier": "UPS", "expected_delivery": "2025-07-25" }, "status": "in_transit", "last_discussed_at": "2025-07-23T09:10:00.000Z", "notes": null } ] } ] }, "errors": null } ``` ```json Not Found theme={null} { "data": null, "errors": [ { "error": "NOT_FOUND", "message": "Contact not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Custom Dialing Pool Source: https://docs.bland.ai/api-v1/get/custom-dialing-pool GET https://us.api.bland.ai/v1/custom-dialing-pools/{pool_id} Retrieve a specific custom dialing pool by its ID. **Enterprise Feature** - Custom dialing is only available on Enterprise plans. Contact your Bland representative for access. Retrieve details for a specific custom dialing pool using its unique identifier. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the custom dialing pool to retrieve. **Format**: UUID format (e.g., `550e8400-e29b-41d4-a716-446655440000`) ### Response Can be `success` or `error`. The custom dialing pool object (present only if status is `success`). Unique identifier for the pool. Organization ID that owns this pool. Array of phone numbers in the pool. UUID of associated Twilio credentials (or null if none). Timestamp when the pool was created. Array of error objects (present only if status is `error`). Error code indicating the type of error. Human-readable error message. ```bash cURL theme={null} curl -X GET "https://us.api.bland.ai/v1/custom-dialing-pools/550e8400-e29b-41d4-a716-446655440001" \ -H "Authorization: YOUR_API_KEY" ``` ```javascript JavaScript theme={null} const poolId = '550e8400-e29b-41d4-a716-446655440001'; const response = await fetch(`https://us.api.bland.ai/v1/custom-dialing-pools/${poolId}`, { method: 'GET', headers: { 'Authorization': 'YOUR_API_KEY', } }); const data = await response.json(); console.log(data); ``` ```python Python theme={null} import requests pool_id = "550e8400-e29b-41d4-a716-446655440001" url = f"https://us.api.bland.ai/v1/custom-dialing-pools/{pool_id}" headers = { "Authorization": "YOUR_API_KEY" } response = requests.get(url, headers=headers) print(response.json()) ``` ```json Success Response theme={null} { "status": "success", "data": { "id": "550e8400-e29b-41d4-a716-446655440001", "owner_id": "550e8400-e29b-41d4-a716-446655440002", "phone_numbers": ["+12345678901", "+19876543210", "+15551234567"], "encrypted_key": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2024-01-15T10:30:00Z" }, "errors": null } ``` ```json Error Response - Pool Not Found theme={null} { "status": "error", "data": null, "errors": [ { "error": "POOL_NOT_FOUND", "message": "Geospatial dialing pool not found" } ] } ``` ```json Error Response - Invalid Pool ID theme={null} { "status": "error", "data": null, "errors": [ { "error": "INVALID_POOL_ID", "message": "Pool ID must be a valid UUID" } ] } ``` ```json Error Response - Unauthorized theme={null} { "status": "error", "data": null, "errors": [ { "error": "UNAUTHORIZED", "message": "Invalid API key or insufficient permissions" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Custom Dialing Pools Source: https://docs.bland.ai/api-v1/get/custom-dialing-pools GET https://us.api.bland.ai/v1/custom-dialing-pools Retrieve all custom dialing pools for your organization. **Enterprise Feature** - Custom dialing is only available on Enterprise plans. Retrieve a list of all custom dialing pools that belong to your organization. ### Headers Your API key for authentication. ### Response Can be `success` or `error`. Array of custom dialing pool objects (present only if status is `success`). Unique identifier for the pool. Organization ID that owns this pool. Array of phone numbers in the pool. UUID of associated Twilio credentials (or null if none). Timestamp when the pool was created. Array of error objects (present only if status is `error`). Error code indicating the type of error. Human-readable error message. ```bash cURL theme={null} curl -X GET "https://us.api.bland.ai/v1/custom-dialing-pools" \ -H "Authorization: YOUR_API_KEY" ``` ```javascript JavaScript theme={null} const response = await fetch('https://us.api.bland.ai/v1/custom-dialing-pools', { method: 'GET', headers: { 'Authorization': 'YOUR_API_KEY', } }); const data = await response.json(); console.log(data); ``` ```python Python theme={null} import requests url = "https://us.api.bland.ai/v1/custom-dialing-pools" headers = { "Authorization": "YOUR_API_KEY" } response = requests.get(url, headers=headers) print(response.json()) ``` ```json Success Response theme={null} { "status": "success", "data": [ { "id": "550e8400-e29b-41d4-a716-446655440001", "owner_id": "550e8400-e29b-41d4-a716-446655440002", "phone_numbers": ["+12345678901", "+19876543210", "+15551234567"], "encrypted_key": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2024-01-15T10:30:00Z" }, { "id": "550e8400-e29b-41d4-a716-446655440003", "owner_id": "550e8400-e29b-41d4-a716-446655440002", "phone_numbers": ["+13105551234", "+19175555678"], "encrypted_key": null, "created_at": "2024-01-16T14:45:00Z" } ], "errors": null } ``` ```json Empty Response theme={null} { "status": "success", "data": [], "errors": null } ``` ```json Error Response theme={null} { "status": "error", "data": null, "errors": [ { "error": "UNAUTHORIZED", "message": "Invalid API key or insufficient permissions" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Eval Agent Templates Source: https://docs.bland.ai/api-v1/get/evals-agent-templates GET https://api.bland.ai/v1/evals/agent-templates List the read-only library of shipped eval agent templates. ### Headers Your API key for authentication. ### Response Always `list`. Array of eval agent template objects. Unique identifier key for the template, for example `hallucination_detection`. Human-readable display name. Brief description of what the template evaluates. Template category. One of `voice`, `sales`, `support`, `scheduling`, `compliance`, or `quality`. Evaluation modality. Either `text` or `audio`. The system prompt used for this eval agent, in Markdown. The evaluation prompt, in Markdown. Ordered scoring levels for this template. Short identifier for the level, 1-64 characters. Display label for the level, 1-80 characters. Prompt describing this level's criteria, in Markdown. Optional display color. One of `rose`, `amber`, `gold`, `emerald`, `blue`, `indigo`, `violet`, or `fog`. Array of `level_key` strings that represent the passing threshold for this template. Always `false`. This endpoint returns the full library in a single page. Always `null` for this endpoint. ```json Response theme={null} { "data": { "object": "list", "data": [ { "key": "hallucination_detection", "name": "Hallucination Detection", "description": "Detects factual inaccuracies or fabricated information in agent responses.", "category": "quality", "modality": "text", "system_prompt_md": "You are an expert evaluator assessing whether an AI agent fabricated information.", "prompt_md": "Review the conversation and determine whether the agent stated anything that was factually incorrect or unsupported.", "levels": [ { "level_key": "no_hallucination", "label": "No Hallucination", "prompt_md": "The agent made no factually incorrect or unsupported claims.", "color": "emerald" }, { "level_key": "minor_hallucination", "label": "Minor Hallucination", "prompt_md": "The agent made one or more small inaccuracies that did not materially mislead the user.", "color": "amber" } ], "target_level_keys": ["no_hallucination"] }, { "key": "call_resolution", "name": "Call Resolution", "description": "Assesses whether the agent successfully resolved the caller's issue.", "category": "support", "modality": "audio", "system_prompt_md": "You are an expert evaluator assessing call resolution quality.", "prompt_md": "Did the agent fully resolve the caller's stated issue before ending the call?", "levels": [ { "level_key": "resolved", "label": "Resolved", "prompt_md": "The caller's issue was fully addressed.", "color": "emerald" }, { "level_key": "unresolved", "label": "Unresolved", "prompt_md": "The caller's issue was not addressed or was left open.", "color": "rose" } ], "target_level_keys": ["resolved"] } ], "has_more": false, "next_cursor": null }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Eval Agent Template Source: https://docs.bland.ai/api-v1/get/evals-agent-templates-key GET https://api.bland.ai/v1/evals/agent-templates/{template_key} Fetch a single shipped eval agent template by its key. ### Headers Your API key for authentication. ### Path Parameters The template's key, for example `hallucination_detection`. ### Response Unique identifier key for the template. Human-readable display name. Brief description of what the template evaluates. Template category. One of `voice`, `sales`, `support`, `scheduling`, `compliance`, or `quality`. Evaluation modality. Either `text` or `audio`. The system prompt used for this eval agent, in Markdown. The evaluation prompt, in Markdown. Ordered scoring levels for this template. Short identifier for the level, 1-64 characters. Display label for the level, 1-80 characters. Prompt describing this level's criteria, in Markdown. Optional display color. One of `rose`, `amber`, `gold`, `emerald`, `blue`, `indigo`, `violet`, or `fog`. Array of `level_key` strings that represent the passing threshold for this template. Returns `404` with code `EVAL_AGENT_TEMPLATE_NOT_FOUND` if the key does not match any shipped template. ```json Response theme={null} { "data": { "key": "hallucination_detection", "name": "Hallucination Detection", "description": "Detects factual inaccuracies or fabricated information in agent responses.", "category": "quality", "modality": "text", "system_prompt_md": "You are an expert evaluator assessing whether an AI agent fabricated information.", "prompt_md": "Review the conversation and determine whether the agent stated anything that was factually incorrect or unsupported.", "levels": [ { "level_key": "no_hallucination", "label": "No Hallucination", "prompt_md": "The agent made no factually incorrect or unsupported claims.", "color": "emerald" }, { "level_key": "minor_hallucination", "label": "Minor Hallucination", "prompt_md": "The agent made one or more small inaccuracies that did not materially mislead the user.", "color": "amber" }, { "level_key": "major_hallucination", "label": "Major Hallucination", "prompt_md": "The agent stated clearly false or fabricated information that could mislead the user.", "color": "rose" } ], "target_level_keys": ["no_hallucination"] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Eval Agents Source: https://docs.bland.ai/api-v1/get/evals-agents GET https://api.bland.ai/v1/evals/agents List the eval agents in your organization. ### Headers Your API key for authentication. ### Query Parameters Number of results to return. Between 1 and 100. Cursor: return results after this object ID. Cursor: return results before this object ID. Cannot be combined with `starting_after`. ### Response Always `"list"`. The list of eval agents. Each item contains the fields below. Unique identifier for the eval agent. Display name of the eval agent. Optional description of what the eval agent grades. ID of the current editable draft version. ID of the published version experiments run against, or `null` if never published. Version number of the published version, or `null` if never published. Whether the eval agent is enabled. The modality of the eval agent. One of `text` or `audio`. Summary of the most recent run against this agent, or `null` if no runs exist. * `id` - Run ID. * `status` - Status of the run. * `created_at` - ISO 8601 timestamp. * `call_count` - Number of calls evaluated. * `target_hit_count` - Number of calls that hit a target level. * `graded_count` - Number of calls that received a grade. Key-value metadata associated with the eval agent. Values are strings. ISO 8601 timestamp for when the eval agent was created. ISO 8601 timestamp for when the eval agent was last updated. Whether more results exist beyond this page. Cursor to pass as `starting_after` to fetch the next page, or `null` if there are no more results. ```json Response theme={null} { "errors": null, "data": { "object": "list", "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Empathy Check", "description": "Grades how empathetic the agent sounds during difficult conversations.", "current_version_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "active_version_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "active_version_number": 2, "enabled": true, "modality": "audio", "latest_run": { "id": "d4e5f6a7-b8c9-0123-defa-234567890123", "status": "completed", "created_at": "2026-05-20T14:00:00.000Z", "call_count": 120, "target_hit_count": 98, "graded_count": 120 }, "metadata": {}, "created_at": "2026-03-01T09:00:00.000Z", "updated_at": "2026-05-20T14:05:00.000Z" } ], "has_more": false, "next_cursor": null } } ``` # Get Eval Agent Source: https://docs.bland.ai/api-v1/get/evals-agents-id GET https://api.bland.ai/v1/evals/agents/{eval_agent_id} Fetch one eval agent and its current draft version. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the eval agent. ### Response The requested eval agent. Unique identifier for the eval agent. ID of the organization that owns this eval agent. Unique slug key for the eval agent within the organization. Display name of the eval agent. Optional description of what the eval agent grades. ID of the current editable draft version. ID of the published version experiments run against, or `null` if never published. Key-value metadata associated with the eval agent. Values are strings. ISO 8601 timestamp for when the eval agent was created. ISO 8601 timestamp for when the eval agent was last updated. ISO 8601 timestamp if the eval agent has been soft-deleted, otherwise `null`. The current editable draft version of the eval agent. Unique identifier for this version. ID of the organization that owns this version. ID of the parent eval agent. Sequential version number. Name of this version. Optional description of this version. State of this version. One of `editable` or `archived`. One of `text` or `audio`. The system prompt for the judge LLM, in Markdown. The grading prompt for the judge LLM, in Markdown. Verdict levels for graded mode. Empty array for pass/fail mode. Each level contains `level_key`, `label`, `prompt_md`, and optionally `color`. Which level keys count as a target match. Empty array for pass/fail agents. Relative weight of this agent in aggregate scoring. Between 0 and 100. ID of the version this was forked from, or `null` if this is the first version. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. ISO 8601 timestamp for when this version was last updated. ```json Response theme={null} { "errors": null, "data": { "agent": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "org_id": "f0e1d2c3-b4a5-9678-fedc-ba9876543210", "key": "empathy-check", "name": "Empathy Check", "description": "Grades how empathetic the agent sounds during difficult conversations.", "current_version_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "active_version_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "metadata": {}, "created_at": "2026-03-01T09:00:00.000Z", "updated_at": "2026-05-20T14:00:00.000Z", "deleted_at": null }, "current_version": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "org_id": "f0e1d2c3-b4a5-9678-fedc-ba9876543210", "eval_agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 3, "name": "Empathy Check v3", "description": "Refined grading criteria based on feedback.", "state": "editable", "modality": "audio", "system_prompt_md": "You are an expert call quality reviewer.", "prompt_md": "Did the agent express empathy when the caller described their problem?", "levels": [ { "level_key": "excellent", "label": "Excellent", "prompt_md": "The agent clearly and warmly acknowledged the caller's feelings.", "color": "emerald" }, { "level_key": "poor", "label": "Poor", "prompt_md": "The agent ignored or dismissed the caller's feelings.", "color": "rose" } ], "target_level_keys": ["excellent"], "weight": 10, "created_from_version_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-15T08:00:00.000Z", "updated_at": "2026-05-27T10:00:00.000Z" } } } ``` # List Eval Agent Versions Source: https://docs.bland.ai/api-v1/get/evals-agents-id-versions GET https://api.bland.ai/v1/evals/agents/{eval_agent_id}/versions List all versions of an eval agent. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the eval agent. ### Query Parameters Number of results to return. Between 1 and 100. Cursor: return results after this object ID. Cursor: return results before this object ID. Cannot be combined with `starting_after`. ### Response Always `"list"`. The list of versions. Each item contains the fields below. Unique identifier for this version. ID of the parent eval agent. Sequential version number. Name of this version. State of this version. One of `editable` or `archived`. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. Summary of the most recent run against this version, or `null` if no runs exist. * `id` - Run ID. * `status` - Status of the run. * `created_at` - ISO 8601 timestamp. Whether more results exist beyond this page. Cursor to pass as `starting_after` to fetch the next page, or `null` if there are no more results. ```json Response theme={null} { "errors": null, "data": { "object": "list", "data": [ { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "eval_agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 3, "name": "Empathy Check v3", "state": "editable", "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-15T08:00:00.000Z", "latest_run": null }, { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "eval_agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 2, "name": "Empathy Check v2", "state": "archived", "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-04-10T12:00:00.000Z", "latest_run": { "id": "d4e5f6a7-b8c9-0123-defa-234567890123", "status": "completed", "created_at": "2026-05-20T14:00:00.000Z" } } ], "has_more": false, "next_cursor": null } } ``` # Get Eval Agent Version Source: https://docs.bland.ai/api-v1/get/evals-agents-id-versions-id GET https://api.bland.ai/v1/evals/agents/{eval_agent_id}/versions/{version_id} Fetch one version of an eval agent. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the eval agent. The unique identifier of the version to fetch. Returns a `404` with error code `EVAL_AGENT_VERSION_NOT_FOUND` if the version does not exist or does not belong to the specified eval agent. ### Response Unique identifier for this version. ID of the organization that owns this version. ID of the parent eval agent. Sequential version number. Name of this version. Optional description of this version. State of this version. One of `editable` or `archived`. One of `text` or `audio`. The system prompt for the judge LLM, in Markdown. The grading prompt for the judge LLM, in Markdown. Verdict levels for graded mode. Empty array for pass/fail mode. Each level contains `level_key`, `label`, `prompt_md`, and optionally `color`. Which level keys count as a target match. Empty array for pass/fail agents. Relative weight of this version in aggregate scoring. Between 0 and 100. ID of the version this was forked from, or `null` if this is the first version. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. ISO 8601 timestamp for when this version was last updated. ```json Response theme={null} { "errors": null, "data": { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "org_id": "f0e1d2c3-b4a5-9678-fedc-ba9876543210", "eval_agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 2, "name": "Empathy Check v2", "description": "Expanded grading criteria with three verdict levels.", "state": "archived", "modality": "audio", "system_prompt_md": "You are an expert call quality reviewer.", "prompt_md": "Did the agent express empathy when the caller described their problem?", "levels": [ { "level_key": "excellent", "label": "Excellent", "prompt_md": "The agent clearly and warmly acknowledged the caller's feelings.", "color": "emerald" }, { "level_key": "adequate", "label": "Adequate", "prompt_md": "The agent showed some empathy but could have been warmer.", "color": "amber" }, { "level_key": "poor", "label": "Poor", "prompt_md": "The agent ignored or dismissed the caller's feelings.", "color": "rose" } ], "target_level_keys": ["excellent"], "weight": 10, "created_from_version_id": "d4e5f6a7-b8c9-0123-defa-234567890123", "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-04-10T12:00:00.000Z", "updated_at": "2026-04-10T12:00:00.000Z" } } ``` # List Eval Runs Source: https://docs.bland.ai/api-v1/get/evals-runs GET https://api.bland.ai/v1/evals/runs List eval runs in your organization, with optional filters. ### Headers Your API key for authentication. ### Query Parameters Filter to runs that included this eval agent. Filter to runs started from this workbench setup. Filter by run status. Possible values: `PENDING`, `QUEUED`, `RUNNING`, `COMPLETE`, `PARTIAL`, `FAILED`, `CANCELLED`. Filter by how the run was triggered. Possible values: `manual`, `auto`, `backfill`. Number of results to return. Between 1 and 100. Cursor: return results after this object ID. Cursor: return results before this object ID. Cannot be combined with `starting_after`. ### Response Always `"list"`. The list of eval run objects. Unique identifier for the eval run. Current status of the run. One of `PENDING`, `QUEUED`, `RUNNING`, `COMPLETE`, `PARTIAL`, `FAILED`, `CANCELLED`. How the run was triggered. One of `manual`, `auto`, `backfill`. The scoring modality used. One of `text`, `audio`, `full`. Number of calls resolved for the run. Number of eval agents resolved for the run. Total number of call-by-agent evaluations in the run. Number of evaluations that have completed. Aggregate scoring summary for the run, or `null` if not yet available. Mean overall score across all completed evaluations, normalized 0-100. Mean text-modality score, normalized 0-100. Mean audio-modality score, normalized 0-100. Number of calls that were graded successfully. Number of calls that failed to grade. Number of evaluations where evidence was insufficient to produce a verdict. Number of evaluations where the selected level matched a target level. The pass threshold percentage configured for the run, 0-100. Whether the run met its pass threshold, or `null` if no threshold was set. Billable cost for this run in USD. The workbench setup the run was started from, if any. The pinned workbench setup version used, if any. Key-value metadata attached to the run. ISO 8601 timestamp when the run was created. ISO 8601 timestamp when the run started, or `null` if not yet started. ISO 8601 timestamp when the run completed, or `null` if not yet complete. Whether more results exist beyond this page. Cursor to use in `starting_after` to retrieve the next page, or `null` if there are no more results. ```json Response theme={null} { "data": { "object": "list", "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "COMPLETE", "triggered_by": "manual", "run_mode": "text", "resolved_call_count": 50, "resolved_agent_count": 3, "resolved_atom_count": 150, "completed_atom_count": 150, "summary": { "overall_score_mean": 82.4, "text_score_mean": 82.4, "audio_score_mean": null, "successful_call_count": 48, "failed_call_count": 2, "insufficient_evidence_count": 1, "target_match_count": 39, "pass_threshold_pct": 75, "overall_pass": true }, "billable_cost_usd": 1.24, "workbench_setup_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "workbench_setup_version_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "metadata": {}, "created_at": "2026-05-20T14:00:00.000Z", "started_at": "2026-05-20T14:00:05.000Z", "completed_at": "2026-05-20T14:03:42.000Z" }, { "id": "d4e5f6a7-b8c9-0123-defa-234567890123", "status": "RUNNING", "triggered_by": "auto", "run_mode": "full", "resolved_call_count": 100, "resolved_agent_count": 2, "resolved_atom_count": 200, "completed_atom_count": 87, "summary": null, "billable_cost_usd": null, "workbench_setup_id": null, "workbench_setup_version_id": null, "metadata": { "pipeline": "nightly" }, "created_at": "2026-05-27T02:00:00.000Z", "started_at": "2026-05-27T02:00:08.000Z", "completed_at": null } ], "has_more": false, "next_cursor": null }, "errors": null } ``` # Get Eval Run Source: https://docs.bland.ai/api-v1/get/evals-runs-id GET https://api.bland.ai/v1/evals/runs/{run_id} Fetch one eval run and its current status and summary. ### Headers Your API key for authentication. ### Path Parameters The ID of the eval run to retrieve. ### Response Unique identifier for the eval run. The organization that owns this run. Current status. One of `PENDING`, `QUEUED`, `RUNNING`, `COMPLETE`, `PARTIAL`, `FAILED`, `CANCELLED`. How the run was triggered. One of `manual`, `auto`, `backfill`. The scoring modality. One of `text`, `audio`, `full`. The call IDs submitted for scoring. The agent attachments submitted with the run. Each object contains `eval_agent_id`, `eval_agent_version_id`, `weight`, and `target_level_keys`. The associated workbench setup, if any. The pinned workbench setup version, if any. Number of calls resolved for the run. Number of eval agents resolved for the run. Total call-by-agent evaluations in the run. Number of evaluations completed so far. Aggregate scoring summary, or `null` if not yet available. Mean overall score across all completed evaluations, normalized 0-100. Mean text-modality score, normalized 0-100. Mean audio-modality score, normalized 0-100. Number of calls graded successfully. Number of calls that failed to grade. Number of evaluations where evidence was insufficient to produce a verdict. Number of evaluations where the selected level matched a target level. The pass threshold configured for the run, 0-100. Whether the run met its pass threshold, or `null` if no threshold was set. Billable cost for this run in USD, or `null` if not yet finalized. Error code if the run failed, otherwise `null`. Human-readable error message if the run failed, otherwise `null`. Internal workflow identifier, if applicable. Key-value metadata attached to the run. ISO 8601 timestamp when the run was created. ISO 8601 timestamp when the run started, or `null` if not yet started. ISO 8601 timestamp when the run completed, or `null` if not yet complete. ```json Response theme={null} { "data": { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "org_id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "status": "COMPLETE", "triggered_by": "manual", "run_mode": "text", "submitted_call_ids": [ "a1b2c3d4-0000-0000-0000-000000000001", "a1b2c3d4-0000-0000-0000-000000000002" ], "submitted_attached_agents": [ { "eval_agent_id": "11111111-aaaa-bbbb-cccc-dddddddddddd", "eval_agent_version_id": "22222222-aaaa-bbbb-cccc-dddddddddddd", "weight": 100, "target_level_keys": ["pass"] } ], "workbench_setup_id": null, "workbench_setup_version_id": null, "resolved_call_count": 2, "resolved_agent_count": 1, "resolved_atom_count": 2, "completed_atom_count": 2, "summary": { "overall_score_mean": 91.5, "text_score_mean": 91.5, "audio_score_mean": null, "successful_call_count": 2, "failed_call_count": 0, "insufficient_evidence_count": 0, "target_match_count": 2, "pass_threshold_pct": 80, "overall_pass": true }, "billable_cost_usd": 0.04, "error_code": null, "error_message": null, "workflow_id": null, "metadata": {}, "created_at": "2026-05-27T10:00:00.000Z", "started_at": "2026-05-27T10:00:05.000Z", "completed_at": "2026-05-27T10:01:12.000Z" }, "errors": null } ``` # List Agent Results Source: https://docs.bland.ai/api-v1/get/evals-runs-id-agent-results GET https://api.bland.ai/v1/evals/runs/{run_id}/agent-results List every individual judge verdict in an eval run. ### Headers Your API key for authentication. ### Path Parameters The ID of the eval run. ### Query Parameters Number of results to return. Between 1 and 100. Cursor: return results after this object ID. Cursor: return results before this object ID. Cannot be combined with `starting_after`. ### Response Always `"list"`. The list of agent result objects, one per call-by-agent evaluation. Unique identifier for this agent result. The organization that owns this result. The eval run this result belongs to. The call result this agent verdict is part of. The frozen agent snapshot used to produce this verdict. The eval agent that produced this verdict. The specific version of the eval agent used. The call that was scored. The level key the judge selected, or `null` if scoring failed or evidence was insufficient. Human-readable label for the selected level. Normalized score for this verdict, 0-100. Whether the selected level is one of the configured target levels. Whether the judge determined there was not enough evidence to produce a verdict. Judge confidence in the verdict, 0-1. Markdown-formatted reasoning from the judge. Transcript or audio quotes the judge cited as evidence. Where the evidence came from. One of `transcript` or `audio`. Who spoke this quote. One of `agent`, `customer`, `unknown`, or `null`. Start time of the quote in milliseconds, if available. End time of the quote in milliseconds, if available. The quoted text. Whether this evaluation failed to complete. Machine-readable failure code, if `failed` is `true`. Human-readable failure description, if `failed` is `true`. Billable cost for this individual verdict in USD. Audit metadata for the judge call. Version of the judge prompt used. Number of input tokens consumed. Number of output tokens produced. Latency of the judge call in milliseconds. ISO 8601 timestamp when this result was created. Whether more results exist beyond this page. Cursor to use in `starting_after` to retrieve the next page, or `null` if there are no more results. ```json Response theme={null} { "data": { "object": "list", "data": [ { "id": "c2d3e4f5-a6b7-8901-cdef-234567890123", "org_id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "eval_run_id": "e5f6a7b8-c9d0-1234-efab-345678901234", "eval_run_call_result_id": "b1c2d3e4-f5a6-7890-bcde-f12345678901", "eval_run_agent_snapshot_id": "33333333-aaaa-bbbb-cccc-dddddddddddd", "eval_agent_id": "11111111-aaaa-bbbb-cccc-dddddddddddd", "eval_agent_version_id": "22222222-aaaa-bbbb-cccc-dddddddddddd", "call_id": "a1b2c3d4-0000-0000-0000-000000000001", "selected_level_key": "pass", "selected_level_label": "Pass", "score_normalized_0_100": 88.0, "is_target_match": true, "is_insufficient_evidence": false, "confidence": 0.93, "reasoning_md": "The agent correctly identified the account issue and offered a resolution within the first two minutes of the call.", "evidence": [ { "source": "transcript", "speaker": "agent", "start_ms": 45200, "end_ms": 52100, "text": "I can see your account has a pending charge from last week. Let me reverse that for you right now." } ], "failed": false, "failure_code": null, "failure_message": null, "billable_cost_usd": 0.02, "audit": { "prompt_version": "v3.1.0", "input_tokens": 2840, "output_tokens": 312, "latency_ms": 1843 }, "created_at": "2026-05-27T10:00:48.000Z" } ], "has_more": false, "next_cursor": null }, "errors": null } ``` # List Agent Snapshots Source: https://docs.bland.ai/api-v1/get/evals-runs-id-agent-snapshots GET https://api.bland.ai/v1/evals/runs/{run_id}/agent-snapshots List the frozen agent configurations a run scored against. ### Headers Your API key for authentication. ### Path Parameters The ID of the eval run. Snapshots freeze each agent's prompt, levels, and targets at submission time, so historical results never change if you later edit the agent. ### Response Always `"list"`. All agent snapshots for the run. Returns all snapshots in a single page. Unique identifier for this snapshot. The organization that owns this snapshot. The eval run this snapshot belongs to. The source eval agent. The specific version of the eval agent that was frozen. The ordering position of this agent within the run's agent roster. Machine-readable key identifying this agent in the run. Human-readable name of the agent at snapshot time. Scoring modality for this agent. One of `text` or `audio`. The system prompt used by the judge, frozen at submission time. The evaluation prompt, frozen at submission time. Version identifier for the prompt. The scoring levels defined for this agent, frozen at submission time. Machine-readable key for this level. Human-readable label for this level. Description of what qualifies a call for this level. Optional display color for this level. Level keys that are considered a passing result, frozen at submission time. Relative weight of this agent in the overall score, 0-100. ISO 8601 timestamp when this snapshot was created. Always `false`. All snapshots are returned in a single page. Always `null`. ```json Response theme={null} { "data": { "object": "list", "data": [ { "id": "33333333-aaaa-bbbb-cccc-dddddddddddd", "org_id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "eval_run_id": "e5f6a7b8-c9d0-1234-efab-345678901234", "eval_agent_id": "11111111-aaaa-bbbb-cccc-dddddddddddd", "eval_agent_version_id": "22222222-aaaa-bbbb-cccc-dddddddddddd", "position": 0, "key": "resolution_quality", "name": "Resolution Quality", "modality": "text", "system_prompt_md": "You are an expert call quality analyst evaluating customer service interactions.", "prompt_md": "Did the agent fully resolve the customer's issue without requiring a callback?", "prompt_version": "v3.1.0", "levels": [ { "level_key": "pass", "label": "Pass", "prompt_md": "The agent resolved the issue completely and the customer confirmed satisfaction.", "color": "#22c55e" }, { "level_key": "partial", "label": "Partial", "prompt_md": "The agent addressed the issue but the customer expressed some remaining concern.", "color": "#f59e0b" }, { "level_key": "fail", "label": "Fail", "prompt_md": "The issue was not resolved or the customer was transferred unnecessarily.", "color": "#ef4444" } ], "target_level_keys": ["pass"], "weight": 100, "created_at": "2026-05-27T10:00:00.000Z" } ], "has_more": false, "next_cursor": null }, "errors": null } ``` # List Call Results Source: https://docs.bland.ai/api-v1/get/evals-runs-id-call-results GET https://api.bland.ai/v1/evals/runs/{run_id}/call-results List the per-call results for an eval run. ### Headers Your API key for authentication. ### Path Parameters The ID of the eval run. ### Query Parameters Embed each call's per-agent verdicts inline in the `agent_results` field. When `false`, `agent_results` is an empty array. Number of results to return. Between 1 and 100. Cursor: return results after this object ID. Cursor: return results before this object ID. Cannot be combined with `starting_after`. ### Response Always `"list"`. The list of call result objects. Unique identifier for this call result. The organization that owns this result. The eval run this result belongs to. The ID of the call that was scored. Display name of the call, if available. ISO 8601 timestamp when the call started. Duration of the call in seconds. Which party ended the call. Reference to the transcript snapshot used for scoring. ISO 8601 timestamp when the transcript snapshot expires. Status of this call's evaluation. One of `PENDING`, `QUEUED`, `RUNNING`, `COMPLETE`, `FAILED`, `INSUFFICIENT_EVIDENCE`. ISO 8601 timestamp when scoring started for this call. ISO 8601 timestamp when scoring completed for this call. Overall weighted score for this call, normalized 0-100. Text-modality score for this call, normalized 0-100. Audio-modality score for this call, normalized 0-100. Number of agent evaluations that failed for this call. Number of agent evaluations that returned insufficient evidence for this call. Per-agent verdicts for this call. Populated only when `include_agent_results=true`; otherwise an empty array. See [List Agent Results](/api-v1/get/evals-runs-id-agent-results) for the full field reference. ISO 8601 timestamp when this call result was created. Whether more results exist beyond this page. Cursor to use in `starting_after` to retrieve the next page, or `null` if there are no more results. The eval run's current status. Total number of calls resolved for the run. ```json Response theme={null} { "data": { "object": "list", "data": [ { "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901", "org_id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "eval_run_id": "e5f6a7b8-c9d0-1234-efab-345678901234", "call_id": "a1b2c3d4-0000-0000-0000-000000000001", "call_display_name": "Inbound - Account Inquiry", "call_started_at": "2026-05-20T13:45:00.000Z", "call_duration_seconds": 187.4, "call_ended_by": "agent", "transcript_snapshot_ref": "snapshots/a1b2c3d4-0000-0000-0000-000000000001/v1", "transcript_snapshot_expires_at": "2026-06-20T13:45:00.000Z", "status": "COMPLETE", "started_at": "2026-05-27T10:00:06.000Z", "completed_at": "2026-05-27T10:00:48.000Z", "overall_score_normalized_0_100": 88.0, "text_score_normalized_0_100": 88.0, "audio_score_normalized_0_100": null, "failed_agent_count": 0, "insufficient_evidence_agent_count": 0, "agent_results": [], "created_at": "2026-05-27T10:00:05.000Z" } ], "has_more": true, "next_cursor": "b1c2d3e4-f5a6-7890-bcde-f12345678901" }, "errors": null, "run_status": "COMPLETE", "run_resolved_call_count": 50 } ``` # Get Evals Status Source: https://docs.bland.ai/api-v1/get/evals-status GET https://api.bland.ai/v1/evals/status Check whether the Evals feature is enabled for your organization. ### Headers Your API key for authentication. ### Response Whether Evals is enabled for your organization. The feature gate key. Always `evals_enabled`. Why the feature is unavailable, or `null` when enabled. This is the only Evals endpoint that is not gated. When Evals is disabled, every other `/v1/evals` endpoint returns `404`. ```json Response theme={null} { "data": { "enabled": true, "gate": "evals_enabled", "reason": null }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List User Templates Source: https://docs.bland.ai/api-v1/get/evals-user-templates GET https://api.bland.ai/v1/evals/user-templates List your organization's saved eval agent templates. ### Headers Your API key for authentication. ### Query Parameters Number of results to return. Between 1 and 100. Cursor: return results after this object ID. Cursor: return results before this object ID. Cannot be combined with `starting_after`. ### Response Always `list`. Array of user template summary objects. Unique identifier (UUID) for the template. Short key used to reference the template. Display name of the template. Description of the template, or `null`. Category of the template, or `null`. Evaluation modality. Either `text` or `audio`. Who can access this template. One of `private`, `org`, or `public`. Number of scoring levels defined on this template. UUID of the eval agent this template was snapshotted from, or `null`. UUID of the user who created the template, or `null`. ISO 8601 timestamp of when the template was created. ISO 8601 timestamp of when the template was last updated. Whether additional results exist beyond this page. Cursor to pass as `starting_after` to fetch the next page, or `null` when there are no more results. ```json Response theme={null} { "data": { "object": "list", "data": [ { "id": "a1b2c3d4-5678-9abc-def0-1234567890ab", "key": "my_hallucination_check", "name": "My Hallucination Check", "description": "Customized hallucination detection for our product domain.", "category": "quality", "modality": "text", "visibility": "org", "level_count": 3, "source_agent_id": "b2c3d4e5-6789-abcd-ef01-234567890abc", "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-01T10:00:00.000Z", "updated_at": "2026-05-10T14:30:00.000Z" }, { "id": "d4e5f6a7-89ab-cdef-0123-4567890abcde", "key": "sales_compliance_v2", "name": "Sales Compliance v2", "description": null, "category": "compliance", "modality": "audio", "visibility": "private", "level_count": 2, "source_agent_id": null, "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-15T08:00:00.000Z", "updated_at": "2026-05-15T08:00:00.000Z" } ], "has_more": false, "next_cursor": null }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get User Template Source: https://docs.bland.ai/api-v1/get/evals-user-templates-id GET https://api.bland.ai/v1/evals/user-templates/{id} Fetch one of your organization's saved eval agent templates. ### Headers Your API key for authentication. ### Path Parameters The UUID of the user template to retrieve. ### Response Unique identifier (UUID) for the template. UUID of the organization that owns this template. Short key used to reference the template. Display name of the template. Description of the template, or `null`. Category of the template, or `null`. Evaluation modality. Either `text` or `audio`. System prompt for the eval agent, in Markdown. Evaluation prompt, in Markdown. Ordered scoring levels. Short identifier for the level, 1-64 characters. Display label for the level, 1-80 characters. Prompt describing this level's criteria, in Markdown. Optional display color. One of `rose`, `amber`, `gold`, `emerald`, `blue`, `indigo`, `violet`, or `fog`. Array of `level_key` strings that represent the passing threshold. Access scope. One of `private`, `org`, or `public`. UUID of the eval agent this template was snapshotted from, or `null`. UUID of the specific version snapshotted, or `null`. UUID of the user who created the template, or `null`. ISO 8601 timestamp of when the template was created. ISO 8601 timestamp of when the template was last updated. ```json Response theme={null} { "data": { "id": "a1b2c3d4-5678-9abc-def0-1234567890ab", "org_id": "b2c3d4e5-6789-abcd-ef01-234567890abc", "key": "my_hallucination_check", "name": "My Hallucination Check", "description": "Customized hallucination detection for our product domain.", "category": "quality", "modality": "text", "system_prompt_md": "You are an expert evaluator assessing whether an AI agent fabricated information.", "prompt_md": "Review the conversation and identify any claims that were factually incorrect or unsupported.", "levels": [ { "level_key": "no_hallucination", "label": "No Hallucination", "prompt_md": "The agent made no factually incorrect or unsupported claims.", "color": "emerald" }, { "level_key": "hallucination_detected", "label": "Hallucination Detected", "prompt_md": "The agent stated something factually incorrect or unsupported.", "color": "rose" } ], "target_level_keys": ["no_hallucination"], "visibility": "org", "source_agent_id": null, "source_version_id": null, "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-27T10:00:00.000Z", "updated_at": "2026-05-27T10:00:00.000Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Workbench Setups Source: https://docs.bland.ai/api-v1/get/evals-workbench-setups GET https://api.bland.ai/v1/evals/workbench-setups List the workbench setups in your organization. ### Headers Your API key for authentication. ### Query Parameters Number of results to return. Between 1 and 100. Cursor: return results after this object ID. Cursor: return results before this object ID. Cannot be combined with `starting_after`. ### Response Always `"list"`. The list of workbench setups. Each item contains the fields below. Unique identifier for the workbench setup. Display name of the workbench setup. Optional description of the workbench setup. ID of the current editable draft version. ID of the published version, or `null` if never published. Version number of the published version, or `null` if never published. Number of eval agents currently attached to the draft version. Summary of the most recent run against this setup, or `null` if no runs exist. * `id` - Run ID. * `status` - Status of the run. * `created_at` - ISO 8601 timestamp. * `call_count` - Number of calls evaluated. Key-value metadata associated with the setup. Values are strings. ISO 8601 timestamp for when the setup was created. ISO 8601 timestamp for when the setup was last updated. Whether more results exist beyond this page. Cursor to pass as `starting_after` to fetch the next page, or `null` if there are no more results. ```json Response theme={null} { "errors": null, "data": { "object": "list", "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Onboarding Quality Check", "description": "Evaluates tone, accuracy, and resolution rate across onboarding calls.", "current_version_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "active_version_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "active_version_number": 3, "attached_agent_count": 4, "latest_run": { "id": "d4e5f6a7-b8c9-0123-defa-234567890123", "status": "completed", "created_at": "2026-05-22T10:00:00.000Z", "call_count": 200 }, "metadata": {}, "created_at": "2026-03-15T08:00:00.000Z", "updated_at": "2026-05-22T10:05:00.000Z" } ], "has_more": false, "next_cursor": null } } ``` # Get Workbench Setup Source: https://docs.bland.ai/api-v1/get/evals-workbench-setups-id GET https://api.bland.ai/v1/evals/workbench-setups/{setup_id} Fetch one workbench setup and its current draft version. ### Headers Your API key for authentication. ### Path Parameters The ID of the workbench setup to retrieve. ### Response An object containing the setup and its current draft version. Unique identifier for the workbench setup. ID of the organization that owns this setup. Stable slug key for the setup. Display name of the setup. Description of the setup, or `null` if not set. ID of the current editable draft version. ID of the published version, or `null` if never published. Key-value metadata. Values are strings. ISO 8601 timestamp for when the setup was created. ISO 8601 timestamp for when the setup was last updated. ISO 8601 timestamp for when the setup was deleted, or `null` if not deleted. Unique identifier for this version. ID of the organization that owns this version. ID of the parent workbench setup. Monotonically increasing version number. Display name of this version. Description of this version, or `null` if not set. `"editable"` for a draft, `"archived"` for a published snapshot. Eval agents attached to this version. Each item contains `eval_agent_id`, `eval_agent_version_id`, `weight` (0-100), and `target_level_keys` (array of strings). Percentage of calls that must pass for a run to be considered passing (0-100), or `null` if not set. How calls are evaluated. One of `text`, `audio`, or `full`. ID of the default test configuration, or `null` if not set. Default call IDs to evaluate against. Up to 5000 entries. ID of the version this was forked from, or `null` if it is the first version. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. ISO 8601 timestamp for when this version was last updated. `null` on success. ```json Response theme={null} { "errors": null, "data": { "setup": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "org_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "key": "onboarding-quality-check", "name": "Onboarding Quality Check", "description": "Evaluates tone, accuracy, and resolution rate across onboarding calls.", "current_version_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "active_version_id": "d4e5f6a7-b8c9-0123-defa-234567890123", "metadata": {}, "created_at": "2026-03-15T08:00:00.000Z", "updated_at": "2026-05-20T14:00:00.000Z", "deleted_at": null }, "current_version": { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "org_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "workbench_setup_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 4, "name": "Onboarding Quality Check", "description": "Evaluates tone, accuracy, and resolution rate across onboarding calls.", "state": "editable", "attached_agents": [ { "eval_agent_id": "e5f6a7b8-c9d0-1234-efab-345678901234", "eval_agent_version_id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "weight": 50, "target_level_keys": ["good", "excellent"] } ], "pass_threshold_pct": 80, "run_mode": "audio", "default_test_config_id": null, "default_call_ids": [], "created_from_version_id": "d4e5f6a7-b8c9-0123-defa-234567890123", "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-20T14:00:00.000Z", "updated_at": "2026-05-20T14:00:00.000Z" } } } ``` # List Workbench Setup Versions Source: https://docs.bland.ai/api-v1/get/evals-workbench-setups-id-versions GET https://api.bland.ai/v1/evals/workbench-setups/{setup_id}/versions List all versions of a workbench setup. ### Headers Your API key for authentication. ### Path Parameters The ID of the workbench setup whose versions you want to list. ### Query Parameters Number of results to return. Between 1 and 100. Cursor: return results after this object ID. Cursor: return results before this object ID. Cannot be combined with `starting_after`. ### Response Always `"list"`. The list of versions. Each item contains the fields below. Unique identifier for this version. ID of the parent workbench setup. Monotonically increasing version number. Display name of this version. `"editable"` for a draft, `"archived"` for a published snapshot. Number of eval agents attached to this version. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. Summary of the most recent run against this version, or `null` if none exist. * `id` - Run ID. * `status` - Status of the run. * `created_at` - ISO 8601 timestamp. Whether more results exist beyond this page. Cursor to pass as `starting_after` to fetch the next page, or `null` if there are no more results. ```json Response theme={null} { "errors": null, "data": { "object": "list", "data": [ { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "workbench_setup_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 4, "name": "Onboarding Quality Check", "state": "editable", "attached_agent_count": 4, "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-20T14:00:00.000Z", "latest_run": null }, { "id": "d4e5f6a7-b8c9-0123-defa-234567890123", "workbench_setup_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 3, "name": "Onboarding Quality Check", "state": "archived", "attached_agent_count": 4, "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-04-10T09:00:00.000Z", "latest_run": { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "status": "completed", "created_at": "2026-05-15T16:00:00.000Z" } } ], "has_more": false, "next_cursor": null } } ``` # Get Workbench Setup Version Source: https://docs.bland.ai/api-v1/get/evals-workbench-setups-id-versions-id GET https://api.bland.ai/v1/evals/workbench-setups/{setup_id}/versions/{version_id} Fetch one version of a workbench setup. ### Headers Your API key for authentication. ### Path Parameters The ID of the workbench setup. The ID of the version to retrieve. ### Response The full version object. Unique identifier for this version. ID of the organization that owns this version. ID of the parent workbench setup. Monotonically increasing version number. Display name of this version. Description of this version, or `null` if not set. `"editable"` for a draft, `"archived"` for a published snapshot. Eval agents attached to this version. Each item contains `eval_agent_id`, `eval_agent_version_id`, `weight` (0-100), and `target_level_keys` (array of strings). Percentage of calls that must pass for a run to be considered passing (0-100), or `null` if not set. How calls are evaluated. One of `text`, `audio`, or `full`. ID of the default test configuration, or `null` if not set. Default call IDs to evaluate against. Up to 5000 entries. ID of the version this was forked from, or `null` if it is the first version. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. ISO 8601 timestamp for when this version was last updated. `null` on success. ```json Response theme={null} { "errors": null, "data": { "id": "d4e5f6a7-b8c9-0123-defa-234567890123", "org_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "workbench_setup_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 3, "name": "Onboarding Quality Check", "description": "Evaluation suite for Q1 onboarding calls.", "state": "archived", "attached_agents": [ { "eval_agent_id": "e5f6a7b8-c9d0-1234-efab-345678901234", "eval_agent_version_id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "weight": 50, "target_level_keys": ["good", "excellent"] }, { "eval_agent_id": "a0b1c2d3-e4f5-6789-abcd-ef0123456789", "eval_agent_version_id": "b1c2d3e4-f5a6-7890-bcde-f01234567890", "weight": 50, "target_level_keys": ["acceptable"] } ], "pass_threshold_pct": 75, "run_mode": "audio", "default_test_config_id": null, "default_call_ids": [ "call_abc123", "call_def456" ], "created_from_version_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-04-10T09:00:00.000Z", "updated_at": "2026-04-15T12:00:00.000Z" } } ``` # Event Stream Source: https://docs.bland.ai/api-v1/get/event-stream GET https://api.bland.ai/v1/event_stream/{call_id} Retrieve stream of events that occurred during the call. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the call for which you want to retrieve detailed information. ### Response The level of the event - `queue` or `call` The message of the event. The category of the event - `info`, `performance` or `error`. The unique identifier for the call. When the event occurred. *** Docs for agents: [llms.txt](/llms.txt) # Get Pathways in Folder Source: https://docs.bland.ai/api-v1/get/folder_pathways GET https://us.api.bland.ai/v1/pathway/folders/{folder_id}/pathways Retrieves all pathways within a specific folder for the authenticated user. ### Headers Your API key for authentication. ### Path Parameters The ID of the folder to retrieve pathways from. ### Response An array of pathway objects within the specified folder. The unique identifier of the pathway. The name of the pathway. The description of the pathway. The creation date and time of the pathway. ```json Response theme={null} { "pathways": [ { "id": "pathway_123", "name": "My Pathway", "description": "A sample pathway", "created_at": "2024-03-15T12:00:00Z" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Guard Rails Source: https://docs.bland.ai/api-v1/get/guard-rails GET https://api.bland.ai/v1/guard_rails Retrieve a list of all guard rails in your organization. ### Headers Your API key for authentication. ### Query Parameters Filter guard rails by the type of source they're attached to. Options: `PERSONA`, `PATHWAY`, `INBOUND` Filter guard rails by a specific source ID (must be a valid UUID). ### Response Array of guard rail objects. Unique identifier for the guard rail. Organization ID that owns this guard rail. Type of guard rail. One of: `tcpa:ai_disclosure`, `tcpa:recording_disclosure`, `tcpa:self_introduction`, `tcpa:opt_out`, or `custom`. Name of the guard rail (for custom guard rails). Description of the guard rail (for custom guard rails). Detection prompt (only for custom guard rails). Configuration object. For TCPA time-based guard rails, contains `end_seconds`. Array of sources this guard rail is attached to. Each attachment contains `source_type` (`PERSONA`, `PATHWAY`, or `INBOUND`), `source_id`, and `actions`. ISO 8601 timestamp of when the guard rail was created. ISO 8601 timestamp of when the guard rail was last modified. Any errors that occurred (null if none). ```json Response theme={null} { "data": [ { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "org_id": "12345678-1234-1234-1234-123456789012", "type": "tcpa:ai_disclosure", "name": null, "description": null, "prompt": null, "config": { "end_seconds": 30 }, "attachments": [ { "source_type": "PERSONA", "source_id": "98765432-1234-1234-1234-123456789012", "actions": [ { "type": "end_call" } ] } ], "created_at": "2025-01-15T10:30:00.000Z", "updated_at": "2025-01-15T10:30:00.000Z" }, { "id": "b2c3d4e5-6789-01bc-defg-2345678901bc", "org_id": "12345678-1234-1234-1234-123456789012", "type": "custom", "name": "No Medical Advice", "description": "Prevents the agent from providing medical advice", "prompt": "Flag if the agent provides any medical advice, diagnosis, or treatment recommendations", "config": {}, "attachments": [ { "source_type": "PATHWAY", "source_id": "11111111-2222-3333-4444-555555555555", "actions": [ { "type": "transfer", "config": { "phone_number": "+15551234567" } } ] } ], "created_at": "2025-01-16T14:20:00.000Z", "updated_at": "2025-01-16T14:20:00.000Z" } ], "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Guard Rail Source: https://docs.bland.ai/api-v1/get/guard-rails-id GET https://api.bland.ai/v1/guard_rails/{guard_rail_id} Retrieve a specific guard rail by ID. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the guard rail to retrieve. ### Response The guard rail object. Unique identifier for the guard rail. Organization ID that owns this guard rail. Type of guard rail. One of: `tcpa:ai_disclosure`, `tcpa:recording_disclosure`, `tcpa:self_introduction`, `tcpa:opt_out`, or `custom`. Name of the guard rail (for custom guard rails). Description of the guard rail (for custom guard rails). Detection prompt (only for custom guard rails). Configuration object. For TCPA time-based guard rails, contains `end_seconds`. Array of sources this guard rail is attached to. Each attachment contains `source_type` (`PERSONA`, `PATHWAY`, or `INBOUND`), `source_id`, and `actions`. ISO 8601 timestamp of when the guard rail was created. ISO 8601 timestamp of when the guard rail was last modified. Any errors that occurred (null if none). ```json Response theme={null} { "data": { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "org_id": "12345678-1234-1234-1234-123456789012", "type": "custom", "name": "No Medical Advice", "description": "Prevents the agent from providing medical advice", "prompt": "Flag if the agent provides any medical advice, diagnosis, or treatment recommendations", "config": {}, "attachments": [ { "source_type": "PERSONA", "source_id": "98765432-1234-1234-1234-123456789012", "actions": [ { "type": "transfer", "config": { "phone_number": "+15551234567" } } ] } ], "created_at": "2025-01-15T10:30:00.000Z", "updated_at": "2025-01-15T10:30:00.000Z" }, "errors": null } ``` ```json Error Response (Not Found) theme={null} { "data": null, "errors": [ { "error": "NOT_FOUND", "message": "Guard rail not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Numbers Source: https://docs.bland.ai/api-v1/get/inbound GET https://api.bland.ai/v1/inbound Retrieves a list of all inbound phone numbers configured for your account, along with their associated settings. ### Headers Your API key for authentication. Use your own Twilio account and only return inbound numbers associated with that account sid (optional). Learn more about BYOT [here](/tutorials/custom-twilio). ### Response An array of objects, each representing an inbound phone number and its configuration. ```json Response theme={null} { "inbound_numbers": [ { "created_at": "2023-11-27T17:21:38.33359+00:00", "phone_number": "+18005551234", "prompt": "When you receive a call, recite a random poem from 'Sunset Boulevard' and then ask, 'How may I assist you in your poetic journey today?'", "webhook": "https://api.example.com/poetry-line", "voice_id": 2, "dynamic_data": [/* Use [Dynamic Data](/api-reference/endpoint/dynamic_validate) to make API requests mid-call */], "interruption_threshold": null, "first_sentence": null, "reduce_latency": true, "transfer_phone_number": null, "voice_settings": null, "record": false, "max_duration": 30 }, { "created_at": "2023-11-25T21:42:22.325993+00:00", "phone_number": "+18005559876", "prompt": "Answer with 'You've reached the Secret Society of Enigmatic Enthusiasts. Please state the password or leave a message after the beep.'", "webhook": "https://mysteryclub.example.com/inbound-call-hook", "voice_id": 1, "dynamic_data": null, "interruption_threshold": null, "first_sentence": null, "reduce_latency": true, "transfer_phone_number": null, "voice_settings": null, "record": false, "max_duration": 30 }, //... ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Number Details Source: https://docs.bland.ai/api-v1/get/inbound-number GET https://api.bland.ai/v1/inbound/{phone_number} Retrieve settings for your inbound phone number. ### Headers Your API key for authentication. ### Path Parameters The inbound phone number to update. Formatting notes: * The `'+'` or `'%2B'` prefix is optional. * Will assume a US country code if no country code is provided. Valid Examples for `+13334445555`: * `%2B13334445555` * `13334445555` * `3334445555` ### Response The timestamp when the inbound number was configured. The specific inbound phone number. The prompt your agent is using. The webhook URL, if any, where transcripts are sent after each call to the number completes. The `voice` your agent is currently using. For more information, see [List Voices](/api-v1/get/voices). The background track your agent is using. Will be `null` by default, until an option such as `office`, `cafe`, `restaurant`, or `none` is applied. The `pathway_id` your agent is using. Any dynamic data associated with the inbound number, if applicable. The maximum duration of a call to the inbound number, in minutes. A pre-configured phone number used as a forwarding destination during Bland maintenance windows. Does not affect normal call routing. Returns `null` if no fallback is configured. ```json Response theme={null} { "created_at": "2023-11-27T17:21:38.33359+00:00", "phone_number": "+18584139939", "prompt": "You're Blandie, the helpful AI assistant. The person calling you has inquired...", "webhook": "https://webhook.site/0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0", "voice_id": 2, "dynamic_data": null, "max_duration": 30 } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Knowledge Bases Source: https://docs.bland.ai/api-v1/get/knowledge GET https://api.bland.ai/v1/knowledge Retrieves a paginated list of knowledge bases for the authenticated organization. Returns all knowledge bases in your organization with pagination support. Use this endpoint to browse your available knowledge bases and their current status. ### Headers Your API key for authentication. ### Query Parameters Page number for pagination. Number of items per page (maximum 100). ### Response Paginated list of knowledge bases. Array of knowledge base objects. Unique identifier for the knowledge base. Name of the knowledge base. Description of the knowledge base (if provided). Current status: `"PROCESSING"`, `"COMPLETED"`, `"FAILED"`, or `"DELETED"`. Type of knowledge base: `"FILE"`, `"WEB_SCRAPE"`, or `"TEXT"`. Source URLs for web scrape type (comma-separated). Base URL for web scrape type. ISO timestamp of creation. ISO timestamp of last update. Error message if status is `"FAILED"`. File information for file-type knowledge bases. Original filename. File size in bytes. MIME type of the file. Total number of knowledge bases in the organization. Will be `null` on successful request. ```bash Basic Request theme={null} curl -X GET https://api.bland.ai/v1/knowledge \ -H "authorization: YOUR_API_KEY" ``` ```bash With Pagination theme={null} curl -X GET "https://api.bland.ai/v1/knowledge?page=2&limit=10" \ -H "authorization: YOUR_API_KEY" ``` ```json Success Response theme={null} { "data": { "kbs": [ { "id": "kb_01H8X9QK5R2N7P3M6Z8W4Y1V5T", "name": "Company FAQs", "description": "Frequently asked questions and policies", "status": "COMPLETED", "type": "FILE", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:32:00Z", "file": { "file_name": "company_faqs.pdf", "file_size": 2048576, "file_type": "application/pdf" } }, { "id": "kb_01H8X9QK5R2N7P3M6Z8W4Y1V6U", "name": "Product Documentation", "description": "Complete product documentation from website", "status": "PROCESSING", "type": "WEB_SCRAPE", "source_urls": "https://example.com/docs/overview,https://example.com/docs/api", "base_url": "https://example.com", "created_at": "2025-01-15T11:00:00Z", "updated_at": "2025-01-15T11:00:00Z" } ], "total": 15 }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Knowledge Base Source: https://docs.bland.ai/api-v1/get/knowledge-id GET https://api.bland.ai/v1/knowledge/{knowledge_base_id} Retrieves a specific knowledge base by ID. Returns detailed information about a specific knowledge base, including its current status, metadata, and file information (if applicable). ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the knowledge base to retrieve. ### Response The knowledge base object. Unique identifier for the knowledge base. Name of the knowledge base. Description of the knowledge base (if provided). Current status: `"PROCESSING"`, `"COMPLETED"`, `"FAILED"`, or `"DELETED"`. Type of knowledge base: `"FILE"`, `"WEB_SCRAPE"`, or `"TEXT"`. Source URLs for web scrape type (comma-separated). Base URL for web scrape type. ISO timestamp of creation. ISO timestamp of last update. Error message if status is `"FAILED"`. File information for file-type knowledge bases. Original filename. File size in bytes. MIME type of the file. Will be `null` on successful request. ```bash cURL theme={null} curl -X GET https://api.bland.ai/v1/knowledge/kb_01H8X9QK5R2N7P3M6Z8W4Y1V5T \ -H "authorization: YOUR_API_KEY" ``` ```json Success Response theme={null} { "data": { "id": "kb_01H8X9QK5R2N7P3M6Z8W4Y1V5T", "name": "Company FAQs", "description": "Frequently asked questions and policies", "status": "COMPLETED", "type": "FILE", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:32:00Z", "file": { "file_name": "company_faqs.pdf", "file_size": 2048576, "file_type": "application/pdf" } }, "errors": null } ``` ```json Not Found Response theme={null} { "data": null, "errors": [ { "error": "KB_ERROR", "message": "KB not found or access denied" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Account Details Source: https://docs.bland.ai/api-v1/get/me GET https://api.bland.ai/v1/me Returns call data for your account. ### Headers Your API key for authentication. ### Response An object containing your billing data. Contains `current_balance` (number of credits), and `refill_to` if you have auto refill enabled. The status of your account. The total number of calls you've made. ```json Response theme={null} { "status": "active", "billing": { "current_balance": 99919.1210000034, "refill_to": null }, "total_calls": 9903 } ``` *** Docs for agents: [llms.txt](/llms.txt) # List All Memories Source: https://docs.bland.ai/api-v1/get/memory GET https://api.bland.ai/v1/memory Retrieve all memory stores associated with your account. ### Headers Your API key for authentication. ### Response Response data containing memories array. Array of memory objects. Unique identifier for the memory. Name of the memory. ISO timestamp when the memory was created. User ID that owns this memory. Memory duration setting (currently null). ```json Response theme={null} { "data": { "memories": [ { "id": "12345678-1234-1234-1234-123456789012", "created_at": "2025-07-20T23:32:19.840Z", "user_id": "87654321-4321-4321-4321-210987654321", "name": "Customer Support", "memory_duration": null } ] }, "errors": null } ``` ### Error Responses ```json Error Response theme={null} { "data": null, "errors": [ { "error": "MEMORY_ERROR", "message": "Failed to retrieve memories." } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Memory Changes Source: https://docs.bland.ai/api-v1/get/memory-changes GET https://api.bland.ai/v1/memory/changes Retrieve what memory was captured or updated during a specific call or SMS conversation. Shows the memory state before and after the interaction. ### Headers Your API key for authentication. ### Query Parameters The call ID to get memory changes for. Either `call_id` or `conversation_id` is required. The SMS conversation ID to get memory changes for. Either `call_id` or `conversation_id` is required. ### Response Memory changes data. The memory context at the start of the interaction. Changes made to memory during the interaction. Historical record of memory updates. Error array (null on success). ```json Response theme={null} { "data": { "initial_memory": { "summary": "Customer previously inquired about pricing.", "facts": { "name": "John Doe" } }, "changes": { "summary": "Customer placed an order for the premium plan. Order #12345 confirmed.", "facts": { "name": "John Doe", "plan": "premium", "order_id": "12345" } }, "memory_history": [ { "timestamp": "2025-07-22T10:30:00.000Z", "type": "summary_update", "value": "Customer placed an order for the premium plan." } ] }, "errors": null } ``` ```json Not Found theme={null} { "data": null, "errors": [ { "error": "NOT_FOUND", "message": "Call or conversation not found, or no memory data available" } ] } ``` ```json Error Response theme={null} { "data": null, "errors": [ { "error": "BAD_REQUEST", "message": "call_id or conversation_id is required" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Contact Memory Source: https://docs.bland.ai/api-v1/get/memory-contact-id GET https://api.bland.ai/v1/memory/contact/{memory_id} Retrieve a contact's full memory record by ID, including their conversation summary, structured facts, recent messages, and open items. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the contact memory record. ### Response The contact memory object. Unique identifier for the contact memory. Organization ID this memory belongs to. Contact ID this memory is associated with. Persona ID this memory is scoped to (null if agent-based). Agent phone number this memory is scoped to (null if persona-based). Rolling summary of interactions with this contact. Structured facts about the contact (key-value pairs). Array of recent messages from the sliding window. Array of open items or pending tasks. Historical record of memory updates. ISO timestamp when the memory was created. ISO timestamp when the memory was last updated. Error array (null on success). ```json Response theme={null} { "data": { "id": "mem-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "org_id": "11111111-2222-3333-4444-555555555555", "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "persona_id": "persona-12345678", "agent_number": null, "summary": "Customer called about order #8821 which was delayed. Follow-up confirmed the order shipped and is now in transit.", "facts": { "name": "Sarah Chen", "phone": "+14155550192", "preferred_contact": "sms", "timezone": "America/Los_Angeles" }, "recent_messages": [ { "role": "user", "content": "Hi, has my order shipped yet?", "channel": "sms", "timestamp": "2025-07-23T09:10:00.000Z" }, { "role": "assistant", "content": "Yes, order #8821 shipped this morning. Expected delivery is Friday July 25.", "channel": "sms", "timestamp": "2025-07-23T09:10:05.000Z" } ], "open_items": [ { "type": "follow_up", "description": "Confirm delivery of order #8821 on July 25", "created_at": "2025-07-23T09:10:00.000Z", "priority": "medium", "related_to": { "entity_type": "order", "entity_id": "order-8821" } } ], "memory_history": [], "created_at": "2025-07-20T10:30:00.000Z", "updated_at": "2025-07-23T09:15:00.000Z" }, "errors": null } ``` ```json Not Found theme={null} { "data": null, "errors": [ { "error": "NOT_FOUND", "message": "Contact memory not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Recent Messages Source: https://docs.bland.ai/api-v1/get/memory-contact-id-messages GET https://api.bland.ai/v1/memory/contact/{memory_id}/messages Retrieve the recent message history for a contact memory. Returns cross-channel messages (voice and SMS) in chronological order. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the contact memory record. ### Response Array of recent messages. Message role: "user" or "assistant". Message content. Channel the message came from: "call" or "sms". ISO timestamp when the message was recorded. Error array (null on success). ```json Response theme={null} { "data": [ { "role": "user", "content": "Hi, I'm calling about my order", "channel": "call", "timestamp": "2025-07-22T10:30:00.000Z" }, { "role": "assistant", "content": "I'd be happy to help you with your order. Can you provide your order number?", "channel": "call", "timestamp": "2025-07-22T10:30:05.000Z" }, { "role": "user", "content": "It's order #12345", "channel": "sms", "timestamp": "2025-07-22T11:00:00.000Z" } ], "errors": null } ``` ```json Empty Messages theme={null} { "data": [], "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Memory Context Source: https://docs.bland.ai/api-v1/get/memory-context GET https://api.bland.ai/v1/memory/context Retrieve the full memory context for a contact scoped to a persona or agent number. Returns everything the agent sees at the start of a conversation: summary, facts, recent messages, entities, and open items. ### Headers Your API key for authentication. ### Query Parameters The unique identifier of the contact. The persona ID for memory scoping. Either `persona_id` or `agent_number` is required. The agent phone number for memory scoping. Either `persona_id` or `agent_number` is required. ### Response The memory context object. The contact ID this memory belongs to. Array of recent messages from the sliding window (cross-channel). Message role: "user" or "assistant". Message content. Channel the message came from: "call" or "sms". ISO timestamp when the message was recorded. Rolling summary of interactions with this contact. Structured facts about the contact (key-value pairs). Array of extracted entities associated with this contact. Array of open items or pending tasks for this contact. Error array (null on success). ```json Response theme={null} { "data": { "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "recentMessages": [ { "role": "user", "content": "Has my order shipped yet?", "channel": "sms", "timestamp": "2025-07-23T09:10:00.000Z" }, { "role": "assistant", "content": "Yes, order #8821 shipped this morning. Expected delivery is Friday July 25.", "channel": "sms", "timestamp": "2025-07-23T09:10:05.000Z" } ], "summary": "Customer called about order #8821 which was delayed. Follow-up confirmed the order shipped and is now in transit. Expected delivery July 25.", "contactFacts": { "name": "Sarah Chen", "phone": "+14155550192", "preferred_contact": "sms", "timezone": "America/Los_Angeles" }, "entities": [ { "entity_type": "order", "entity_id": "order-8821", "facts": { "order_number": "#8821", "status": "in_transit", "carrier": "UPS", "expected_delivery": "2025-07-25" }, "status": "in_transit", "last_discussed_at": "2025-07-23T09:10:00.000Z", "notes": null } ], "openItems": [ { "type": "follow_up", "description": "Confirm delivery of order #8821 on July 25", "created_at": "2025-07-23T09:10:00.000Z", "priority": "medium", "related_to": { "entity_type": "order", "entity_id": "order-8821" } } ] }, "errors": null } ``` ```json No Memory Yet theme={null} { "data": { "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "recentMessages": [], "summary": null, "contactFacts": {}, "entities": [], "openItems": [] }, "errors": null } ``` ```json Error Response theme={null} { "data": null, "errors": [ { "error": "BAD_REQUEST", "message": "persona_id or agent_number is required" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Memory Details Source: https://docs.bland.ai/api-v1/get/memory-memory-id GET https://api.bland.ai/v1/memory/{memory_id} Retrieve detailed information about a specific memory store and its users. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the memory to retrieve. ### Response Detailed memory data organized by users. Unique identifier for the memory. Name of the memory. ISO timestamp when the memory was created. Array of user objects with their associated data. The phone number associated with this memory entry. ISO timestamp when this user was added to the memory. Total number of calls with this phone number. Custom metadata text associated with this phone number. ISO timestamp of the most recent call with this phone number, or null if no calls yet. AI-generated summary of interactions with this phone number. ```json Response theme={null} { "data": { "memory_id": "12345678-1234-1234-1234-123456789012", "name": "Customer Support", "created_at": "2025-07-20T23:32:19.840Z", "users": [ { "phone_number": "+12345678900", "created_at": "2025-07-21T07:09:04.372Z", "call_count": 0, "metadata": "25 year old customer from New York", "last_call_at": null, "summary": "Previous call discussion was on the topic of startups" } ] }, "errors": null } ``` ### Error Responses ```json Memory Not Found theme={null} { "data": null, "errors": [ { "error": "MEMORY_NOT_FOUND", "message": "Memory not found." } ] } ``` ```json Server Error theme={null} { "data": null, "errors": [ { "error": "MEMORY_ERROR", "message": "Failed to retrieve memory data." } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # List TTS Models Source: https://docs.bland.ai/api-v1/get/models GET https://api.bland.ai/v1/models List the available Bland TTS models and their capabilities. ## Overview Returns the Bland TTS models currently available for synthesis and cloning, with each model's supported sample rates, language list, and clone eligibility. Use this endpoint to render model pickers, pre-validate a request before calling [Speak](/api-v2/post/tts), or check which engines support cloning before calling [Clone Voice](/api-v1/post/clone). Results are cached for up to 5 minutes. *** ## Headers Your API key for authentication. *** ## Response Array of available models. Engine identifier. Use this to map a voice's `service` field back to its model. Human-readable name suitable for UI (for example `V1`, `V2`). Short description of the model's positioning. Supported audio sample rates in Hz. Pass an `output_format` to [Speak](/api-v2/post/tts) that matches one of these. Maximum characters per synthesis request supported by the model. Whether [Clone Voice](/api-v1/post/clone) can produce voices on this model. Language codes supported for synthesis. `true` for the model Bland currently recommends for new integrations. ```json Response theme={null} { "models": [ { "model_id": "BTTS_V2", "display_name": "V2", "description": "Current-generation TTS with multilingual output and instant single-sample cloning.", "sample_rates": [8000, 16000, 24000, 44100], "max_characters": 1000, "can_clone": true, "languages": ["en", "de", "es", "fr", "hi", "it", "ja", "ko", "nl", "pl", "pt", "ru", "tr", "zh", "ar", "id", "sv"], "is_recommended": true }, { "model_id": "BTTS_V3", "display_name": "Experimental", "description": "Showcase clones. Newest model, ships ahead of full V2 feature parity.", "sample_rates": [24000, 44100], "max_characters": 1000, "can_clone": true, "languages": ["en"] }, { "model_id": "BTTS", "display_name": "V1", "description": "Legacy English-only TTS. Retained for backward compatibility, prefer V2 for new integrations.", "sample_rates": [8000, 16000, 24000, 44100], "max_characters": 1000, "can_clone": true, "languages": ["en"] } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Node Test Run Source: https://docs.bland.ai/api-v1/get/node_test_run GET https://api.bland.ai/v1/node_tests/run/:id Retrieve a node test run. ### Path The ID of the node test run to retrieve. ### Headers Your API key for authentication. ### Response Unique identifier for the node test run. Organization ID that owns this node test run. ISO timestamp when the node test run was created. ISO timestamp when the node test run finished. Current status of the node test run. Possible values are "COMPLETED", "PENDING", "CANCELLED", and "ERROR". Identifier of the pathway this node belongs to. Identifier of the node that was tested within the pathway. Input configuration used for this node test run. The instruction or system prompt used when testing the node. Array of conversation references used as context for the node test. Unique identifier of a conversation used in the test. The type of conversation (for example, "call"). Array of result objects, one per evaluated conversation. ID of the conversation this result corresponds to. Total number of generations produced for this conversation during the test run. For example, if I invoke the test with 5 permutations, then this value will be 6, since we need to generate 5 simulations for the permutations and one generation for the original user messages. Array of generation batches for this conversation. If true, then this result is the original user and agent interaction on the node. If true, then this result is a generation using a permutation/variant of the original user inputs. Ordered list of message turns (user/assistant) in this generated interaction. Role of the message author ("user" or "assistant"). Node identifier associated with this message turn. Text content of the message. An indicator to show if the system is in the process of simulating the agent response with the new prompt and original user inputs. An indicator to show if the system is in the process of simulating the agent response with the new prompt and user permutations. ```json Response theme={null} { "data": { "id": "727a85f1-1959-4ec1-95a4-248a2eecf1ae", "org_id": "99a0d526-6910-4f31-92b8-72834d0827fb", "created_at": "2025-11-17T14:47:40.174Z", "finished_at": "2025-11-17T14:48:11.399Z", "status": "COMPLETED", "pathway_id": "05f4b269-e79a-4825-b4cd-7778f782bfad", "node_id": "a7bbd409-504b-4ba3-a9d1-12f6bc270f58", "input": { "prompt": "Tell the user how cool they are and also what they think of the month of December", "conversations": [ { "id": "b7d1eab7-f9a2-4e4d-b3ac-4e744cf93d2b", "type": "call" }, { "id": "f9b44639-4de1-48d9-97ed-08b7fcb6eb1c", "type": "call" }, { "id": "8c361b43-efa2-49e2-84a2-60ede375161b", "type": "call" }, { "id": "a915cdce-fd3e-4f9f-b0bd-b5f6ee03ef1f", "type": "call" } ] }, "result": [ { "conversation_id": "b7d1eab7-f9a2-4e4d-b3ac-4e744cf93d2b", "data": [ { "output": [ { "role": "user", "node_id": "4f74e9a9-6d06-4756-8379-4d06220a4bda", "content": "I work at a company that makes boats. I'm a boat builder." }, { "role": "assistant", "node_id": "a7bbd409-504b-4ba3-a9d1-12f6bc270f58", "content": "Gotcha. Okay, so, uh, what would you say are your biggest strengths?" } ], "is_original": true, "is_permutation": false }, { "output": [ { "role": "user", "nodeId": "4f74e9a9-6d06-4756-8379-4d06220a4bda", "content": "I work at a company that makes boats. I'm a boat builder." }, { "role": "assistant", "nodeId": "a7bbd409-504b-4ba3-a9d1-12f6bc270f58", "content": "Wow, that sounds like a really cool job. That's pretty unique. You must have some interesting stories. Anyways, what would you say are your biggest strengths?" } ], "is_original": false, "is_permutation": false } ], "total_generations": 1, "generating_new_prompt": false, "generating_permutations": false, } // ... ] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Organization Billing Information Source: https://docs.bland.ai/api-v1/get/org_billing_information GET https://api.bland.ai/v1/orgs/{org_id}/billing Retrieve the current billing details for an organization. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the organization. ### Response The billing details of the organization. The current account balance of the organization. The amount to which the balance will be refilled, or `null` if refilling is not enabled. The threshold at which the account will be refilled, or `null` if refilling is not enabled. Always `null` on success. ```json Response theme={null} { "data": { "current_balance": 20.711, "refill_amount": null, "refill_at": null }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Organization Billing Refill Information Source: https://docs.bland.ai/api-v1/get/org_billing_refill_information GET https://api.bland.ai/v1/orgs/{org_id}/billing/refill Retrieve the recharge amount for an organization's billing. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the organization. ### Response The amount to which the balance will be recharged, or `null` if refilling is not enabled. Always `null` on success. ```json Response theme={null} { "data": 50.00, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Organization's Current Service Version Source: https://docs.bland.ai/api-v1/get/org_current_version GET https://api.bland.ai/v1/orgs/{org_id}/versions/{service}/current Retrieve the current version of a specified service for an organization. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the organization. The name of the service whose version you want to retrieve.\
Valid values: `"api_server"`, `"ws_server"`
### Response Contains the current version of the requested service. The current version identifier of the service. Always `null` on success. ```json Response theme={null} { "data": { "version": "adf1064d-5080-4055-8493-0d4fdc3c8106" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get User Organization Memberships Source: https://docs.bland.ai/api-v1/get/org_list_self_memberships GET https://api.bland.ai/v1/orgs/self/memberships Retrieve a list of organizations the authenticated user is a member of. ### Headers Your API key for authentication. ### Response A list of organizations the user belongs to. The unique identifier of the organization. The unique slug identifier of the organization. The display name of the organization. The permissions assigned to the user within the organization.\
Valid values: `"owner"`, `"admin"`, `"operator"`, `"viewer"`
Whether the user is the owner of the organization. Whether the user originally created the organization. The timestamp of when the user joined the organization. Always `null` on success. ```json Response theme={null} { "data": [ { "org_id": "d6b149e1-f971-4641-8d28-64fdf78368af", "org_slug": "a7d49dbc-025c-4e80-9c92-c45c519f4939", "org_display_name": "Org Name", "permissions": ["owner"], "is_owner": true, "is_org_creator": true, "joined_at": "2024-11-14T21:28:05.915Z" }, { "org_id": "d122b4cf-1614-4124-aa28-15f81a09988f", "org_slug": "133906ea-d750-4a15-80fa-d6aef584dc58", "org_display_name": "Org Name2", "permissions": ["owner"], "is_owner": true, "is_org_creator": true, "joined_at": "2025-02-14T06:46:11.274Z" } ], "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Organization's Service Versions Source: https://docs.bland.ai/api-v1/get/org_list_versions GET https://api.bland.ai/v1/orgs/{org_id}/versions/{service}/list Retrieve a list of available versions for a specified service within an organization. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the organization. The name of the service whose versions you want to retrieve.\
Valid values: `"api_server"`, `"ws_server"`
### Response Contains the list of available versions for the requested service. An array of available versions. The unique identifier of the version. A human-readable name for the version. The timestamp when the version was created. The Git SHA hash of the version. Tags categorizing the version, e.g., `["latest"]`, `["stable"]`. Whether this version is currently supported. The recommended version to upgrade to, if applicable. The name of the service this version belongs to. The placement group of this version. Always `null` on success. ```json Response theme={null} { "data": { "versions": [ { "created_at": "2024-11-28T19:05:17.003Z", "git_sha": "", "friendly_name": "Latest", "tags": ["latest"], "currently_supported": true, "recommended_upgrade_to": null, "service": "api_server", "id": "adf1064d-5080-4055-8493-0d4fdc3c8106", "placement_group": "blandshared" }, { "created_at": "2024-11-27T00:28:30.286Z", "git_sha": "", "friendly_name": "v1.0.1", "tags": ["stable"], "currently_supported": true, "recommended_upgrade_to": null, "service": "api_server", "id": "a46f516b-b01f-4ea6-9c7b-5b05fca49d4f", "placement_group": "blandshared" } ] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Organization Members Source: https://docs.bland.ai/api-v1/get/org_members GET https://api.bland.ai/v1/orgs/{org_id}/members Retrieve the list of members in an organization. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the organization whose members you want to retrieve. ### Response A list of members in the organization. The unique identifier of the organization. The unique identifier of the user. The permissions assigned to the user within the organization. Indicates whether the user is the owner of the organization. Indicates whether the user originally created the organization. The timestamp of when the user joined the organization. The first name of the organization member. The last name of the organization member. A unique identifier combining the organization and user ID. The unique slug identifier of the organization. The display name of the organization. The email address of the organization member. The phone number of the organization member. Always `null` on success. ```json Response theme={null} { "data": [ { "org_id": "d122b4cf-1614-4124-aa28-15f81a09988f", "user_id": "d6b149e1-f971-4641-8d28-64fdf78368af", "permissions": ["owner"], "is_owner": true, "is_org_creator": true, "joined_at": "2025-02-14T06:46:11.274Z", "first_name": "John", "last_name": "Smith", "combo_id": "d122b4cf-1614-4124-aa28-15f81a09988f::d6b149e1-f971-4641-8d28-64fdf78368af", "org_slug": "133906ea-d750-4a15-80fa-d6aef584dc58", "org_display_name": "Org Name", "member_email": "johnsmith@gmail.com", "member_phone_number": "+1234567890" } ], "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Organization Source: https://docs.bland.ai/api-v1/get/orgs GET https://api.bland.ai/v1/orgs/{org_id} Retrieve details of an organization. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the organization to retrieve. ### Response The details of the organization. The unique identifier of the organization. The unique slug identifier of the organization. The display name of the organization. URL of the organization's image (if set). The organization's plan. Default: `"starter"`. The timestamp of when the organization was created. The KYC (Know Your Customer) verification level. Default: `0`. The placement group of the organization. Default: `"blandshared"`. Whether the organization is deleted. Default: `false`. Whether the organization has overdue Stripe payments. Default: `false`. Whether the organization is suspended. Default: `false`. The organization's request rate limit. Default: `5`. The type of the organization. Default: `"normal"`. A list of entitlements granted to the organization. Default: `[]`. Whether the organization prefers to use the Bland URL. Default: `true`. Always `null` on success. ```json Response theme={null} { "data": { "id": "d122b4cf-1614-4124-aa28-15f81a09988f", "org_slug": "133906ea-d750-4a15-80fa-d6aef584dc58", "org_display_name": "Org Name", "org_image_url": null, "org_plan": "starter", "org_creation_date": "2025-02-14T06:46:09.818Z", "kyc_level": 0, "placement_group": "blandshared", "is_deleted": false, "is_stripe_overdue": false, "is_suspended": false, "org_rate_limit": 5, "org_type": "normal", "entitlements": [], "preferences": { "use_bland_url": true } }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Single Pathway Information Source: https://docs.bland.ai/api-v1/get/pathway GET https://api.bland.ai/v1/pathway/{pathway_id} Returns a set of information about the conversational pathway in your account - including the name, description, nodes and edges. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the conversational pathway for which you want to retrieve detailed information. ### Response The name of the conversational pathway. A description of the conversational pathway. Data about all the nodes in the pathway. Examples of JSON objects for nodes (Horizontal scroll the tab bar to see more examples) ```json Start Node theme={null} { "id": "1", "type": "Default" "data": { "name": "Start", "text": "Hey there, how are you doing today?", "isStart": true, }, ``` ```json Default Node theme={null} { "id": "randomnode_1710288871721", "type": "Default" "data": { "name": "New Node", "text": "Select a node or edge and press backspace to remove it", "globalPrompt": "This is a phone call. Do not use exclamation marks.\n\nConvert 24HR format timings to 12 HR format - e.g 14:00 should be written as 2 PM.", }, } ``` ```json End Node theme={null} { "id": "randomnode_1710288752186", "type": "End Call" "data": { "name": "End call", "prompt": "Say goodbye to the user", }, } ``` ```json Webhook Node theme={null} { "id": "randomnode_1710288752186", "type": "Webhook", "data": { "url": "https://api.bland.ai/reservation", "body": "{\n \"date\" : \"{{date}}\",\n \"time\" : \"{{time}}\",\n \"guests\": {{number_of_people}}\n}", "name": "Reservation Booking", "text": "Please give me a moment as I check our bookings..", "method": "POST", "extractVars": [ [ "date", "string", "Desired Date of reservation, in MM/DD/YYYY format" ], [ "time", "string", "Desired Time of Reservation in 24HR Format e.g 13:30" ], [ "number_of_people", "integer", "Number of people for the reservation" ] ], "responseData": [ { "data": "$.reserved", "name": "reservation_success", "context": "" }, { "data": "$.available_slots", "name": "available_slots", "context": "Available slots for the date provided" } ], "responsePathways": [ [ "reservation_success", "==", "true", { "id": "randomnode_1710288752186", "name": "Reservation Successful" } ], [ "reservation_success", "==", "false", { "id": "randomnode_1712265110018", "name": "Find new timeslot" } ] ] } } ``` ```json Knowledge Base Node theme={null} { "id": "randomnode_1710288752186", "type": "Knowledge Base", "data": { "name": "Restaurant Questions", "prompt": "Answer any questions that the user may have regarding the restaurant, by referring to the knowledge base you have. \n\nAnswer the question in 1 line, and then ask if they have any more questions." "kb": "Opening Hours : 9am - 5pm\nStore Locations : \n426 Ivy Street San Francisco, \nSan Jose" } } ``` ```json Global Node theme={null} { "id": "randomnode_1710288871721", "type": "Default" "data": { "name": "Answer any questions", "prompt": "You are to answer any questions the user has.", "isGlobal": true, "globalLabel": "user asks a question" }, } ``` ```json Transfer Call Node theme={null} { "id": "randomnode_1710288752186", "type": "Transfer Call", "data": { "name": "Transferring the call", "text": "Transferring the call now. Please hold.." "transferNumber": "+19547951234" } } ``` * `name` — name of the node * `isStart` — whether the node is the start node. There can only be 1 start node in a pathway. Either `true` or `false`. * `isGlobal` — whether the node is a global node. Global nodes are nodes that can be used in multiple pathways. Either `true` or `false`. * `globalLabel` — the label of the global node. Should be present if `isGlobal` is true. * `type` — Type of the node. Can be `Default`, `End Call`, `Transfer Node`, `Knowledge Base`, or `Webhook`. * `text` — If static text is chosen, this is the text that will be said to the user. * `prompt` — If dynamic text is chosen, this is the prompt that will be shown to the user. * `condition` — The condition that needs to be met to proceed from this node. * `transferNumber` * If the node is a transfer node, this is the number to which the call will be transferred. * `kb` * If the node is a knowledge base node, this is the knowledge base that will be used. * `pathwayExamples` * The fine-tuning examples for the agent at this node for the pathways chosen * `conditionExamples` * The fine-tuning examples for the condition at this node for the condition chosen * `dialogueExamples` * The fine-tuning examples for the dialogue at this node for the dialogue chosen. * `modelOptions` * `interruptionThreshold` — The sensitivity to interruptions at this node * `temperature` — The temperature of the model. * `extractVars` * An array of array of strings. \[\[`varName`, `varType`, `varDescription`]] e.g `[["name", "string", "The name of the user"], ["age", "integer", "The age of the user"]]` Data about all the edges in the pathway. * `id` — unique id of the edge * `source` — id of the source node * `target` — id of the target node * `label` — Label for this edge. This is what the agent will use to decide which path to take. ```json Response theme={null} { "name": "Default Demo Pathway", "description": null, "nodes": [ { "id": "1", "data": { "name": "Start", "text": "Hey there, how are you doing today?", "isStart": true, }, "type": "Default" }, { "id": "randomnode_1710288752186", "data": { "name": "End call", "prompt": "Click 'Add New Node' on the right to add a new node", }, "type": "End Call" }, { "id": "randomnode_1710288871721", "data": { "name": "New Node", "text": "Select a node or edge and press backspace to remove it", }, "type": "Default" }, { "id": "randomnode_test123", "data": { "name": "Testing node", "text": "Hello there" }, "type": "Default" } ], "edges": [ { "id": "reactflow__edge-1-randomnode_1710288752186", "label": "greeted", "source": "1", "target": "randomnode_1710288752186" }, { "id": "reactflow__edge-1-randomnode_1710288871721", "label": "New Edge", "source": "1", "target": "randomnode_1710288871721" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Pathway Chat Source: https://docs.bland.ai/api-v1/get/pathway-chat GET https://us.api.bland.ai/v1/pathway/chat/{id} Get conversation history for a pathway chat. ### Headers Your API key for authentication. ### Path Parameters The chat ID created from the /pathway/chat/create endpoint. ### Response List of errors or null. Message objects for the conversation history. ```json Response theme={null} { data: [ { "role": "user", "content": "message" }, ... // more messages ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Pathway Generation Status Source: https://docs.bland.ai/api-v1/get/pathway-generate-status-job-id GET https://api.bland.ai/v1/pathway/generate/status/{job_id} Poll pathway generation status and retrieve the generated pathway ID when ready. ### Headers Your API key for authentication. ### Path Parameters The `jobId` returned by `POST /v1/pathway/generate`. ### How polling works * The first status request can return `ready: false` while the server begins processing. * Continue polling until `data.ready` is `true`. * On success, the response includes `pathway_id`. * On failure, the response includes `error`. ### Response Generation state object. `false` while generation is still in progress, `true` when processing is complete. Present when generation succeeds and `ready` is `true`. Present when generation fails and `ready` is `true`. `null` on success responses, or a list of errors for invalid/unauthorized requests. ```json Not Ready theme={null} { "data": { "ready": false }, "errors": null } ``` ```json Ready (Success) theme={null} { "data": { "ready": true, "pathway_id": "a6c24531-75b1-4334-95b2-2d0f11e8fe41" }, "errors": null } ``` ```json Ready (Failed) theme={null} { "data": { "ready": true, "error": "Prompt flagged for inappropriate content." }, "errors": null } ``` ```json Error theme={null} { "data": null, "errors": [ { "error": "PATHWAY_GENERATION_FAILED", "message": "Job not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Pathway Session Token Source: https://docs.bland.ai/api-v1/get/pathway-session GET https://api.bland.ai/v1/pathway/session Creates a new pathway session token for the authenticated user. This token can be used to access pathway chat and expires after 1 hour. ### Headers Your API key for authentication. ### Response The generated pathway session token. ISO 8601 timestamp indicating when the token expires (1 hour from creation). ### Response Codes Token created successfully. Unauthorized - User authentication required. Internal server error - Token creation failed or unexpected error occurred. ```json Success Response theme={null} { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_at": "2024-01-15T15:30:00.000Z" } ``` ```json Error Response (401) theme={null} { "errors": [ { "error": "UNAUTHORIZED", "message": "User authentication required" } ] } ``` ```json Error Response (500) theme={null} { "errors": [ { "error": "TOKEN_CREATION_FAILED", "message": "Failed to create pathway session token" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Pathway Call Events Source: https://docs.bland.ai/api-v1/get/pathway_calls GET https://api.bland.ai/v1/pathway_calls/{call_id} Retrieve the pathway event timeline for a call — transcripts, node transitions, webhooks, tools, variable extraction, and every other side effect. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the call whose pathway events you want to retrieve. ### Query Parameters Set to `2` to receive the pathway events format documented here. Omitting it returns the deprecated legacy log format, which is being phased out — always pass `v=2`. ### Response The response is a JSON array of event objects, one per event in the call, ordered by `sequence`. See [Pathway Call Events](/tutorials/pathway-call-events) for the full catalog of event types and per-type payload shapes. The call id. All events for one call share it. The ordering key within the call. Always sort by `sequence`, not `created_at`. Gaps are normal and do not indicate missing data. What happened. Either a standalone event (`conversation.init`, `node.transition`, `transcript.user`, `transcript.assistant`, `node.tag`, `interrupt.early`, `interrupt.late`, `button.press`, `llm.action`) or an operation event of the form `operation.phase`, where the operation is one of `webhook`, `tool`, `kb`, `sms`, `scheduling`, `loop_condition`, `var_extraction`, `custom_code`, `transfer_pathway`, `transfer_call`, `unit_test` and the phase is `invoke`, `result`, `error`, or `warning` (plus `webhook.mapping` for variable-mapping outcomes). The pathway node that was active when the event fired. `null` before the first node is entered. Correlation key for multi-event operations: a `result`, `error`, `warning`, or `mapping` event carries the `sequence` of the `invoke` event it belongs to. `null` when there's nothing to correlate. Event-type-specific data. Payload shapes for every event type are documented in [Pathway Call Events](/tutorials/pathway-call-events). ISO 8601 timestamp of the event. Use for timing display; use `sequence` for ordering. ```bash cURL theme={null} curl --request GET \ --url 'https://api.bland.ai/v1/pathway_calls/d2b58344-7fd1-4787-9bf9-1c23e82fd8ff?v=2' \ --header 'authorization: YOUR_API_KEY' ``` ```json Response theme={null} [ { "conversation_id": "d2b58344-7fd1-4787-9bf9-1c23e82fd8ff", "sequence": 0, "event_type": "conversation.init", "node_id": null, "operation_id": null, "payload": { "pathway_id": "pw_123", "start_node_id": "node_start", "version": "12", "initial_variables": { "customer_name": "Ada" } }, "created_at": "2026-08-03T17:04:01.120Z" }, { "conversation_id": "d2b58344-7fd1-4787-9bf9-1c23e82fd8ff", "sequence": 6, "event_type": "webhook.invoke", "node_id": "node_order_lookup", "operation_id": null, "payload": { "url": "https://api.example.com/orders/lookup", "method": "POST", "tool_name": "Lookup Order", "response_mappings": [ { "name": "order_status", "path": "$.status" } ] }, "created_at": "2026-08-03T17:04:09.100Z" }, { "conversation_id": "d2b58344-7fd1-4787-9bf9-1c23e82fd8ff", "sequence": 7, "event_type": "webhook.result", "node_id": "node_order_lookup", "operation_id": 6, "payload": { "url": "https://api.example.com/orders/lookup", "status": 200, "body": { "status": "shipped" }, "duration_ms": 412 }, "created_at": "2026-08-03T17:04:09.520Z" } ] ``` # Get All Folders Source: https://docs.bland.ai/api-v1/get/pathway_folders GET https://us.api.bland.ai/v1/pathway/folders Retrieves all folders for the authenticated user, including folder ID, name, and parent folder ID. ### Headers Your API key for authentication. ### Response An array of folder objects. The unique identifier of the folder. The name of the folder. The ID of the parent folder, if applicable. ```json Response theme={null} { "folders": [ { "id": "folder_123", "name": "My Folder", "parent_folder_id": null }, { "id": "folder_456", "name": "Subfolder", "parent_folder_id": "folder_123" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Specific Pathway Version Source: https://docs.bland.ai/api-v1/get/pathway_version GET https://api.bland.ai/v1/pathway/{pathway_id}/version/{version_id} Retrieves a specific version of a pathway, including its name, nodes, edges, version number, and latest status. ### Headers Your API key for authentication. ### Path Parameters The ID of the pathway. The ID of the version to retrieve. Use 0 for the live pathway. ### Response The name of the pathway version. Data about all the nodes in the pathway version. * `id` — Unique identifier of the node * `type` — Type of the node (e.g., "Default", "End Call", "Webhook") * `data` — Object containing node-specific data * `name` — Name of the node * `text` or `prompt` — Text or prompt associated with the node * Other properties specific to the node type Data about all the edges in the pathway version. * `id` — Unique identifier of the edge * `source` — ID of the source node * `target` — ID of the target node * `label` — Label for this edge The version number of this pathway version. Indicates whether this is the latest version of the pathway. ```json Response theme={null} { "name": "Customer Support Flow v2", "nodes": [ { "id": "1", "type": "Default", "data": { "name": "Start", "text": "Hello! How can I assist you today?", "isStart": true } }, { "id": "2", "type": "End Call", "data": { "name": "End call", "prompt": "Thank you for contacting us. Have a great day!" } } ], "edges": [ { "id": "edge-1-2", "source": "1", "target": "2", "label": "Issue resolved" } ], "version_number": 2, "is_latest": true } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Pathway Versions Source: https://docs.bland.ai/api-v1/get/pathway_versions GET https://api.bland.ai/v1/pathway/{pathway_id}/versions Retrieves all versions of a specific pathway, including version number, creation date, name, and latest status. ### Headers Your API key for authentication. ### Path Parameters The ID of the pathway for which to retrieve versions. ### Response The unique identifier of the pathway version. The version number of this pathway version. The timestamp when this version was created. The name of this pathway version. Indicates whether this is the latest version of the pathway. ```json Response theme={null} [ { "id": "v1_abc123", "version_number": 1, "created_at": "2024-03-05T12:00:00Z", "name": "Initial Version", "is_latest": false }, { "id": "v2_def456", "version_number": 2, "created_at": "2024-03-06T14:30:00Z", "name": "Updated Flow", "is_latest": true } ] ``` *** Docs for agents: [llms.txt](/llms.txt) # List Personas Source: https://docs.bland.ai/api-v1/get/personas GET https://api.bland.ai/v1/personas Retrieve a list of all personas in your organization. ### Headers Your API key for authentication. ### Query Parameters Page number for pagination. Number of personas to return per page (max 100). ### Response Array of persona objects. Unique identifier for the persona. Display name of the persona. Role assigned to the persona. Description of the persona's purpose. Array of tags associated with the persona. URL of the persona's profile image (null if none). ISO 8601 timestamp of when the persona was created. ISO 8601 timestamp of when the persona was last modified. ISO 8601 timestamp of when the persona was deleted (null if active). ID of the user who owns this persona. ID of the current production version. ID of the current draft version. Array of inbound phone numbers using this persona. Complete production version object. Version identifier. Parent persona identifier. Type of version: `production` or `draft`. Sequential version number. Orchestration prompt (null if none). Personality and behavior prompt. Array of pathway routing conditions. Array of knowledge base IDs. Call configuration settings. Array of default tools enabled. Version ID this was promoted from (null if initial). When this version was promoted to production. User who promoted this version (null if auto). When this version was created. When this version was last updated. Complete draft version object (same structure as production version). Any errors that occurred (null if none). ```json Response theme={null} { "data": [ { "id": "12345678-1234-1234-1234-123456789012", "name": "Customer Support Agent", "role": "Customer Support", "description": "A capable customer support agent", "tags": ["Customer Support"], "image_url": null, "created_at": "2025-09-16T23:54:44.420Z", "updated_at": "2025-09-16T23:54:59.896Z", "deleted_at": null, "user_id": "12345678-1234-1234-1234-123456789012", "current_production_version_id": "12345678-1234-1234-1234-123456789012", "current_draft_version_id": "12345678-1234-1234-1234-123456789012", "inbound_numbers": [], "current_production_version": { "id": "12345678-1234-1234-1234-123456789012", "persona_id": "12345678-1234-1234-1234-123456789012", "version_type": "production", "version_number": 1, "orchestration_prompt": null, "personality_prompt": "You are a friendly and helpful customer support agent", "pathway_conditions": null, "kb_ids": [], "call_config": { "voice": "June", "record": true, "language": "en-US", "background": "office", "max_duration": 30, "wait_for_greeting": false, "interruption_threshold": 500 }, "default_tools": [], "promoted_from_version_id": null, "promoted_at": "2025-09-16T23:54:44.441Z", "promoted_by": null, "created_at": "2025-09-16T23:54:44.442Z", "updated_at": "2025-09-16T23:54:44.442Z" }, "current_draft_version": { "id": "12345678-1234-1234-1234-123456789012", "persona_id": "12345678-1234-1234-1234-123456789012", "version_type": "draft", "version_number": 2, "orchestration_prompt": null, "personality_prompt": "You are a friendly and helpful customer support agent", "pathway_conditions": [ { "name": "", "prompt": "", "pathway_id": "", "start_node_id": "", "pathway_version": "" }, { "name": "", "prompt": "", "pathway_id": "", "start_node_id": "", "pathway_version": "" } ], "kb_ids": [], "call_config": { "voice": "June", "record": true, "language": "en-US", "background": "office", "max_duration": 30, "wait_for_greeting": false, "interruption_threshold": 500 }, "default_tools": [], "promoted_from_version_id": "12345678-1234-1234-1234-123456789012", "promoted_at": null, "promoted_by": null, "created_at": "2025-09-16T23:54:44.463Z", "updated_at": "2025-09-16T23:54:59.917Z" } }, { "id": "12345678-1234-1234-1234-123456789013", "name": "Sales Representative", "role": "Sales", "description": "A capable sales representative", "tags": ["Sales"], "image_url": null, "created_at": "2025-09-23T14:40:01.089Z", "updated_at": "2025-09-23T14:40:01.153Z", "deleted_at": null, "user_id": "12345678-1234-1234-1234-123456789012", "current_production_version_id": "12345678-1234-1234-1234-123456789012", "current_draft_version_id": "12345678-1234-1234-1234-123456789012", "inbound_numbers": [], "current_production_version": { "id": "12345678-1234-1234-1234-123456789012", "persona_id": "12345678-1234-1234-1234-123456789013", "version_type": "production", "version_number": 1, "orchestration_prompt": null, "personality_prompt": "You are a friendly and helpful sales representative", "pathway_conditions": null, "kb_ids": [], "call_config": { "voice": "June", "record": true, "language": "en-US", "background": "office", "max_duration": 30, "wait_for_greeting": false, "interruption_threshold": 500 }, "default_tools": [], "promoted_from_version_id": null, "promoted_at": "2025-09-23T14:40:01.109Z", "promoted_by": null, "created_at": "2025-09-23T14:40:01.110Z", "updated_at": "2025-09-23T14:40:01.110Z" }, "current_draft_version": { "id": "12345678-1234-1234-1234-123456789012", "persona_id": "12345678-1234-1234-1234-123456789013", "version_type": "draft", "version_number": 2, "orchestration_prompt": null, "personality_prompt": "You are a friendly and helpful sales representative", "pathway_conditions": null, "kb_ids": [], "call_config": { "voice": "June", "record": true, "language": "en-US", "background": "office", "max_duration": 30, "wait_for_greeting": false, "interruption_threshold": 500 }, "default_tools": [], "promoted_from_version_id": "12345678-1234-1234-1234-123456789012", "promoted_at": null, "promoted_by": null, "created_at": "2025-09-23T14:40:01.132Z", "updated_at": "2025-09-23T14:40:01.132Z" } } ], "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Persona Source: https://docs.bland.ai/api-v1/get/personas-id GET https://api.bland.ai/v1/personas/{persona_id} Retrieve a specific persona. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the persona to retrieve. ### Response The persona object. Unique identifier for the persona. Display name of the persona. Role assigned to the persona. Description of the persona's purpose. Array of tags associated with the persona. URL of the persona's profile image (null if none). ISO 8601 timestamp of when the persona was created. ISO 8601 timestamp of when the persona was last modified. ISO 8601 timestamp of when the persona was deleted (null if active). ID of the user who owns this persona. ID of the current production version. ID of the current draft version. Array of inbound phone numbers using this persona. Complete production version object. Version identifier. Parent persona identifier. Type of version: `production` or `draft`. Sequential version number. Orchestration prompt (null if none). Personality and behavior prompt. Array of pathway routing conditions. Array of knowledge base IDs. Call configuration settings. Array of default tools enabled. Version ID this was promoted from (null if initial). When this version was promoted to production. User who promoted this version (null if auto). When this version was created. When this version was last updated. Complete draft version object (same structure as production version). Any errors that occurred (null if none). ```json Response theme={null} { "data": { "id": "12345678-1234-1234-1234-123456789012", "name": "Customer Support Agent", "role": "Customer Support", "description": "A capable customer support agent", "tags": ["Customer Support"], "image_url": null, "created_at": "2025-09-16T23:54:44.420Z", "updated_at": "2025-09-16T23:54:59.896Z", "deleted_at": null, "user_id": "12345678-1234-1234-1234-123456789012", "current_production_version_id": "12345678-1234-1234-1234-123456789012", "current_draft_version_id": "12345678-1234-1234-1234-123456789012", "inbound_numbers": [], "current_production_version": { "id": "12345678-1234-1234-1234-123456789012", "persona_id": "12345678-1234-1234-1234-123456789012", "version_type": "production", "version_number": 1, "orchestration_prompt": null, "personality_prompt": "You are a friendly and helpful customer support agent", "pathway_conditions": null, "kb_ids": [], "call_config": { "voice": "June", "record": true, "language": "en-US", "background": "office", "max_duration": 30, "wait_for_greeting": false, "interruption_threshold": 500 }, "default_tools": [], "promoted_from_version_id": null, "promoted_at": "2025-09-16T23:54:44.441Z", "promoted_by": null, "created_at": "2025-09-16T23:54:44.442Z", "updated_at": "2025-09-16T23:54:44.442Z" }, "current_draft_version": { "id": "12345678-1234-1234-1234-123456789012", "persona_id": "12345678-1234-1234-1234-123456789012", "version_type": "draft", "version_number": 2, "orchestration_prompt": null, "personality_prompt": "You are a friendly and helpful customer support agent", "pathway_conditions": [ { "name": "", "prompt": "", "pathway_id": "", "start_node_id": "", "pathway_version": "" }, { "name": "", "prompt": "", "pathway_id": "", "start_node_id": "", "pathway_version": "" } ], "kb_ids": [], "call_config": { "voice": "June", "record": true, "language": "en-US", "background": "office", "max_duration": 30, "wait_for_greeting": false, "interruption_threshold": 500 }, "default_tools": [], "promoted_from_version_id": "12345678-1234-1234-1234-123456789012", "promoted_at": null, "promoted_by": null, "created_at": "2025-09-16T23:54:44.463Z", "updated_at": "2025-09-16T23:54:59.917Z" } }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Persona Versions Source: https://docs.bland.ai/api-v1/get/personas-id-versions GET https://api.bland.ai/v1/personas/{persona_id}/versions Retrieve all versions of a specific persona. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the persona whose versions to retrieve. ### Response Array of version objects ordered by version number (newest first). Unique identifier for this version. ID of the parent persona. Version type: `production`, `draft`, or `archived`. Sequential version number. Orchestration prompt for this version (null if none). Personality and behavior prompt for this version. Array of pathway routing conditions (null if none). Array of knowledge base IDs connected to this version. Call configuration settings (null if none). Array of default tools enabled for this version. Version ID this was promoted from (null if initial). When this version was promoted to production (null if not promoted). User who promoted this version (null if auto or not promoted). When this version was created. When this version was last updated. Any errors that occurred (null if none). ```json Response theme={null} { "data": [ { "id": "12345678-1234-1234-1234-123456789012", "persona_id": "12345678-1234-1234-1234-123456789012", "version_type": "draft", "version_number": 2, "orchestration_prompt": null, "personality_prompt": "You are a helpful assistant", "pathway_conditions": null, "kb_ids": [], "call_config": null, "default_tools": [], "promoted_from_version_id": "12345678-1234-1234-1234-123456789012", "promoted_at": null, "promoted_by": null, "created_at": "2025-09-23T15:13:36.390Z", "updated_at": "2025-09-23T15:13:36.390Z" }, { "id": "12345678-1234-1234-1234-123456789013", "persona_id": "12345678-1234-1234-1234-123456789012", "version_type": "production", "version_number": 1, "orchestration_prompt": null, "personality_prompt": "You are a helpful assistant", "pathway_conditions": null, "kb_ids": [], "call_config": null, "default_tools": [], "promoted_from_version_id": null, "promoted_at": "2025-09-23T15:13:36.368Z", "promoted_by": null, "created_at": "2025-09-23T15:13:36.369Z", "updated_at": "2025-09-23T15:13:36.369Z" } ], "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Specific Persona Version Source: https://docs.bland.ai/api-v1/get/personas-id-versions-version-id GET https://api.bland.ai/v1/personas/{persona_id}/versions/{version_id} Retrieve a specific persona version. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the persona. The specific version identifier to retrieve (e.g., "v1.2", "draft", "production"). ### Response The specific version object. Unique identifier for this version. ID of the parent persona. Version type: `production`, `draft`, or `archived`. Sequential version number. Orchestration prompt for this version (null if none). Personality and behavior prompt for this version. Array of pathway routing conditions (null if none). Array of knowledge base IDs connected to this version. Call configuration settings (null if none). Array of default tools enabled for this version. Version ID this was promoted from (null if initial). When this version was promoted to production (null if not promoted). User who promoted this version (null if auto or not promoted). When this version was created. When this version was last updated. Any errors that occurred (null if none). ```json Response theme={null} { "data": { "id": "12345678-1234-1234-1234-123456789012", "persona_id": "12345678-1234-1234-1234-123456789013", "version_type": "archived", "version_number": 1, "orchestration_prompt": null, "personality_prompt": "You are a helpful assistant", "pathway_conditions": null, "kb_ids": [], "call_config": null, "default_tools": [], "promoted_from_version_id": null, "promoted_at": "2025-09-23T15:13:36.368Z", "promoted_by": null, "created_at": "2025-09-23T15:13:36.369Z", "updated_at": "2025-09-23T15:55:57.234Z" }, "errors": null } ``` ```json Error Response (Version Not Found) theme={null} { "error": { "code": "VERSION_NOT_FOUND", "message": "Version 'v2.0' not found for persona '12345678-1234-1234-1234-123456789012'", "details": { "persona_id": "12345678-1234-1234-1234-123456789012", "requested_version": "v2.0", "available_versions": ["v1.0", "v1.1", "v1.2", "v1.3-draft"], "current_production": "v1.2", "current_draft": "v1.3-draft" } } } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Post Call Webhook Source: https://docs.bland.ai/api-v1/get/postcall-webhooks-get GET https://api.bland.ai/v1/postcall/webhooks/{call_id} Get the post call webhook data for a specific call. ## Overview Retrieve the post call webhook data for a specific call using its call ID. This endpoint returns the webhook data that was sent when the call completed. *** ## Headers Your org API key for authentication. *** ## Path Parameters The unique identifier of the call to get the webhook data for. *** ## Response The post call webhook and send history for this call. The post call webhook payload, contains information about the call. The URL the payload inforamtion was sent to Timestamp of when the webhook was first sent The call ID associated with this webhook The ID of the org this webhook was sent from Array of objects containing metadata about webhook spawns, creates, and resends. Each object has the following properties: Timestamp of when this webhook attempt was sent HTTP response code received from the webhook endpoint Time taken to receive a response from the webhook endpoint, appended with "ms" How this webhook was triggered. Can be: * "resend": Webhook was manually resent * "create": Webhook was recreated outside normal flow * "spawn": Webhook was created by normal call flow Array of error objects if returned. The error code. The error message. *** Docs for agents: [llms.txt](/llms.txt) # List Prompts Source: https://docs.bland.ai/api-v1/get/prompts GET https://api.bland.ai/v1/prompts Retrieves all your saved prompts. ### Headers Your API key for authentication. ### Response Response status of the request. An array of prompt objects. ```json Response theme={null} { "status": "success", "prompts": [ { "prompt": "My Prompt", "last_updated": "2024-05-12T22:52:49.004987+00:00", "id": "PT-aa8fb0ac-0014-43c0-9268-543522ce7e27", "name": "My First Prompt" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Prompt Details Source: https://docs.bland.ai/api-v1/get/prompts-id GET https://api.bland.ai/v1/prompts/{prompt_id} Retrieves data for a specific prompt_id. ### Headers Your API key for authentication. ### Path Parameters The unique identifier for the prompt you want to retrieve. ### Response Response status of the request. An object containing parameters for the prompt. The unique identifier of the prompt. The prompt of the specific prompt\_id. The name of the specific prompt\_id. The time of last update for the specific prompt\_id. ```json Response theme={null} { "status": "success", "prompt": { "id": "PT-aa8fb0ac-0014-43c0-9268-543522ce7e27", "prompt": "My Prompt", "name": "My First Prompt" "last_updated": "2024-05-12T22:52:49.004987+00:00", } } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get SIP Call Logs Source: https://docs.bland.ai/api-v1/get/sip-calls GET https://api.bland.ai/v1/sip/calls Retrieve SIP call logs for a phone number with cursor-based pagination. ### Headers Your API key for authentication. ### Query Parameters The phone number to fetch call logs for. Must be in E.164 format. Maximum number of calls to return. Default: 50. Cursor for pagination. Pass the `call_id` of the last call from the previous page to fetch the next page. ### Response Array of call records. Each includes: * `call_id` (string) — Unique SIP Call-ID * `direction` (string) — `"inbound"` or `"outbound"` * `from` (string) — Caller number * `to` (string) — Callee number * `status` (string) — Final SIP status (e.g., `"200 OK"`, `"486 Busy"`) * `sip_code` (number) — SIP response code * `duration_seconds` (number) — Call duration * `started_at` (string) — ISO 8601 timestamp * `ended_at` (string) — ISO 8601 timestamp * `source_ip` (string) — Source IP address ```json Example Request theme={null} curl -X GET 'https://api.bland.ai/v1/sip/calls?phone_number=%2B14150000000&limit=10' \ -H "Authorization: Bearer " ``` ```json Response theme={null} { "data": { "calls": [ { "call_id": "abc123@sip.bland.ai", "direction": "outbound", "from": "+14150000000", "to": "+15105551234", "status": "200 OK", "sip_code": 200, "duration_seconds": 45, "started_at": "2026-03-09T11:00:00Z", "ended_at": "2026-03-09T11:00:45Z", "source_ip": "35.80.235.26" } ] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get SIP Config Source: https://docs.bland.ai/api-v1/get/sip-config GET https://api.bland.ai/v1/sip Retrieve the current SIP configuration for a phone number. ### Headers Your API key for authentication. ### Query Parameters The phone number to fetch SIP configuration for. Must be in E.164 format. ### Response Inbound SIP configuration, or `null` if not configured. Includes `number`, `id`, `org_id`, `direction`, `sip_endpoint`, `headers`, `options`, `created_at`, and `updated_at`. Sensitive fields (credentials) are redacted. Outbound SIP configuration, or `null` if not configured. Same fields as inbound. ```json Example Request theme={null} curl -X GET 'https://api.bland.ai/v1/sip?phone_number=%2B14150000000' \ -H "Authorization: Bearer " ``` ```json Response theme={null} { "data": { "inbound": { "number": "+14150000000", "id": "abc123", "org_id": "org_456", "direction": "inbound", "sip_endpoint": null, "created_at": "2026-03-09T12:00:00Z", "updated_at": "2026-03-09T12:00:00Z", "headers": null, "options": { "auth_mode": "ip" } }, "outbound": { "number": "+14150000000", "id": "def789", "org_id": "org_456", "direction": "outbound", "sip_endpoint": "sip:trunk.provider.com", "created_at": "2026-03-09T12:00:00Z", "updated_at": "2026-03-09T12:00:00Z", "headers": null, "options": { "port": 5061, "transport": "tls", "secure_media": true } } }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Discovery Status Source: https://docs.bland.ai/api-v1/get/sip-discover-status GET https://api.bland.ai/v1/sip/discover/status Poll the status and results of a SIP endpoint discovery session. ### Headers Your API key for authentication. ### Query Parameters The discovery session ID returned from `POST /v1/sip/discover`. ### Response Returns the same `DiscoveryResult` object as `POST /v1/sip/discover`. The `status` field indicates whether the discovery is still `"running"`, has `"completed"`, or has `"failed"`. Discovery results expire after 10 minutes. ```json Example Request theme={null} curl -X GET 'https://api.bland.ai/v1/sip/discover/status?discovery_id=disc_abc123' \ -H "Authorization: Bearer " ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Firewall IPs Source: https://docs.bland.ai/api-v1/get/sip-firewall-ips GET https://api.bland.ai/v1/sip/firewall-ips Get Bland's static IP addresses and ports for your region. Use these to configure your firewall. ### Headers Your API key for authentication. ### Response Array of static IP addresses to whitelist in your firewall. SIP signaling port and transport (e.g., `"5061 TLS"`). RTP media port range (e.g., `"10000-20000 UDP"`). ```json Example Request theme={null} curl -X GET https://api.bland.ai/v1/sip/firewall-ips \ -H "Authorization: Bearer " ``` ```json Response theme={null} { "data": { "ip_addresses": [ "35.80.235.26", "54.189.4.67", "100.20.173.20", "..." ], "ports": { "sip": "5061 TLS", "rtp": "10000-20000 UDP" } }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Generate SIP Password Source: https://docs.bland.ai/api-v1/get/sip-generate-password GET https://api.bland.ai/v1/sip/generate-password Generate a strong, PBX-safe SIP password for register-based authentication, at a configurable length. Generates a cryptographically-random password suitable for a trunk's `register_auth.password`. The character set is unambiguous (no `0`/`O`/`1`/`l`/`I`) and avoids characters that need escaping in PBX configs or SIP URIs, so it pastes safely into Asterisk / FreeSWITCH / 3CX. The result always satisfies the 8–256 length bounds the [attach](/api-v1/post/sip-attach) schema enforces. ### Headers Your API key for authentication. ### Query Parameters Provide **either** `length` or `strength` (or neither, for the default). If both are given, `length` takes precedence. Explicit password length, between **8 and 256**. Values outside the range are clamped. A length preset instead of an explicit value: `"standard"` (16 characters) or `"long"` (32 characters). Defaults to `"standard"` when neither `length` nor `strength` is provided. ### Response The generated password. The actual length of the generated password (after clamping / preset resolution). ```json Example Request theme={null} curl -X GET 'https://api.bland.ai/v1/sip/generate-password?strength=long' \ -H "Authorization: Bearer " ``` ```json Response theme={null} { "data": { "password": "Kf7mQ2pXvR9nLs4T", "length": 16 }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List SIP Numbers Source: https://docs.bland.ai/api-v1/get/sip-numbers GET https://api.bland.ai/v1/sip/numbers List all phone numbers with SIP configurations for your organization. ### Headers Your API key for authentication. ### Response Array of SIP number summaries. Each entry includes: * `phone_number` (string) — The phone number in E.164 format * `directions` (array) — List of configured directions (`"inbound"`, `"outbound"`) * `sip_endpoint` (string) — The SIP endpoint (for outbound) * `health_status` (string) — Current health: `"healthy"`, `"unreachable"`, or `"unchecked"` ```json Example Request theme={null} curl -X GET https://api.bland.ai/v1/sip/numbers \ -H "Authorization: Bearer " ``` ```json Response theme={null} { "data": { "numbers": [ { "phone_number": "+14150000000", "directions": ["inbound", "outbound"], "sip_endpoint": "sip:trunk.provider.com", "health_status": "healthy" }, { "phone_number": "+14150000001", "directions": ["inbound"], "sip_endpoint": null, "health_status": "unchecked" } ] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Outbound Setup Source: https://docs.bland.ai/api-v1/get/sip-outbound-setup GET https://api.bland.ai/v1/sip/outbound-setup Get Bland's SIP server details and PBX configuration instructions for outbound call routing. ### Headers Your API key for authentication. ### Query Parameters Optional. If provided, includes per-number credentials (redacted) in the response. ### Response Bland's SIP server hostname for your region (e.g., `us1.sip.bland.ai`). SIP signaling port (e.g., `5061`). Human-readable setup instructions for configuring your PBX. Per-number registration credentials (only if `phone_number` is provided and registration auth is configured). Sensitive values are redacted. ```json Example Request theme={null} curl -X GET https://api.bland.ai/v1/sip/outbound-setup \ -H "Authorization: Bearer " ``` ```json Response theme={null} { "data": { "sip_server": "us1.sip.bland.ai", "port": 5061, "instructions": "Configure your PBX to send SIP INVITE requests to us1.sip.bland.ai:5061 over TLS. Whitelist the IP addresses from /v1/sip/firewall-ips." }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Check Number Portability Source: https://docs.bland.ai/api-v1/get/sip-port-check GET https://api.bland.ai/v1/sip/port/check Check whether phone numbers are eligible for porting to Bland. ### Headers Your API key for authentication. ### Query Parameters Array of phone numbers to check. Must be in E.164 format. ### Response Array of portability check results. Each includes: * `phone_number` (string) — The phone number checked * `portable` (boolean) — Whether the number can be ported * `number_type` (string) — Type of number: `"mobile"`, `"landline"`, `"toll-free"`, etc. * `pin_required` (boolean) — Whether a PIN from the losing carrier is required ```json Example Request theme={null} curl -X GET 'https://api.bland.ai/v1/sip/port/check?phone_numbers[]=%2B14150000000&phone_numbers[]=%2B14150000001' \ -H "Authorization: Bearer " ``` ```json Response theme={null} { "data": { "results": [ { "phone_number": "+14150000000", "portable": true, "number_type": "landline", "pin_required": false }, { "phone_number": "+14150000001", "portable": true, "number_type": "mobile", "pin_required": true } ] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Port Requests Source: https://docs.bland.ai/api-v1/get/sip-port-requests GET https://api.bland.ai/v1/sip/port List all number porting requests for your organization. ### Headers Your API key for authentication. ### Response Array of port request objects. Each includes: * `id` (string) — Port request ID * `status` (string) — Current status: `"waiting_for_signature"`, `"submitted"`, `"in_progress"`, `"completed"`, `"canceled"`, `"failed"` * `phone_numbers` (array) — Numbers included in the port, each with individual status * `authorized_rep_email` (string) — Email of the authorized representative * `notification_emails` (array) — Notification email addresses * `created_at` (string) — ISO 8601 timestamp * `updated_at` (string) — ISO 8601 timestamp ```json Example Request theme={null} curl -X GET https://api.bland.ai/v1/sip/port \ -H "Authorization: Bearer " ``` ```json Response theme={null} { "data": { "port_requests": [ { "id": "port_xyz789", "status": "in_progress", "phone_numbers": [ { "number": "+14150000000", "status": "in_progress" }, { "number": "+14150000001", "status": "in_progress" } ], "authorized_rep_email": "jane@acme.com", "notification_emails": ["it@acme.com"], "created_at": "2026-03-09T12:00:00Z", "updated_at": "2026-03-12T08:00:00Z" } ] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Trunk Health Source: https://docs.bland.ai/api-v1/get/sip-status GET https://api.bland.ai/v1/sip/status Get the health status of a SIP trunk by probing the endpoint with SIP OPTIONS. ### Headers Your API key for authentication. ### Query Parameters The phone number to check health for. Must be in E.164 format. ### Response Health status: `"healthy"`, `"unreachable"`, or `"unchecked"`. Inbound-only trunks show `"unchecked"` since there is no outbound endpoint to probe. Response time of the SIP OPTIONS probe in milliseconds. `null` if unreachable or unchecked. ISO 8601 timestamp of when the health check was performed. ```json Example Request theme={null} curl -X GET 'https://api.bland.ai/v1/sip/status?phone_number=%2B14150000000' \ -H "Authorization: Bearer " ``` ```json Response theme={null} { "data": { "status": "healthy", "response_time_ms": 42, "checked_at": "2026-03-09T12:00:00Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Test Call Status Source: https://docs.bland.ai/api-v1/get/sip-test-call-status GET https://api.bland.ai/v1/sip/test-call/status Poll the status and trace of a SIP test call. ### Headers Your API key for authentication. ### Query Parameters The call ID returned from `POST /v1/sip/test-call`. ### Response Call status: `"queued"`, `"initiated"`, `"ringing"`, `"in-progress"`, `"completed"`, `"failed"`, `"busy"`, `"no-answer"`. Final result enum: `"connected"`, `"failed"`, `"busy"`, `"no_answer"`, `"pending"`. Call duration in seconds. Array of timeline events with `event` (string), `at` (timestamp), and `detail` (string) fields. ```json Example Request theme={null} curl -X GET 'https://api.bland.ai/v1/sip/test-call/status?call_id=tc_abc123' \ -H "Authorization: Bearer " ``` ```json Response theme={null} { "data": { "status": "completed", "result": "connected", "duration_seconds": 8, "timeline": [ { "event": "initiated", "at": "2026-03-09T12:00:00Z", "detail": "Call initiated" }, { "event": "ringing", "at": "2026-03-09T12:00:01Z", "detail": "Endpoint ringing" }, { "event": "answered", "at": "2026-03-09T12:00:03Z", "detail": "Call answered" }, { "event": "completed", "at": "2026-03-09T12:00:08Z", "detail": "Call ended" } ] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Conversations Source: https://docs.bland.ai/api-v1/get/sms-conversations GET https://api.bland.ai/v1/sms/conversations Retrieve a paginated list of SMS conversations for the authenticated user, with filtering, sorting, and metadata. **Enterprise Feature** - SMS is only available on Enterprise plans. Contact your Bland representative for access. ### Headers Your API key for authentication. ### Query Parameters The page number to retrieve. Defaults to `1`. The number of conversations per page. Defaults to `25`. Field to sort by. Allowed values: `created_at`, `updated_at`, `user_number`, `agent_number`, `is_active`, `message_count`, `curr_pathway_id`, `curr_pathway_version`, `timed_out_at`. Defaults to `created_at`. Direction of sorting. Either `asc` or `desc`. Defaults to `desc`. A JSON-encoded array of filter objects. Each object should contain: * `field`: one of `created_at`, `updated_at`, `user_number`, `agent_number`, `is_active`, `message_count`, `variables`, `current_node_id`, `curr_pathway_id`, `curr_pathway_version`, `timed_out_at` * `operator`: one of `eq`, `contains`, `startsWith`, `endsWith`, `gt`, `gte`, `lt`, `lte` * `value`: the filter value ### Response A list of conversations matching the query. Unique ID of the conversation. ISO timestamp when the conversation was created. ISO timestamp when the conversation was last updated. The user-facing phone number in the conversation. The assistant's phone number in the conversation. Arbitrary variables associated with the conversation. ID of the current node in the conversational pathway. The UUID of the current pathway being used in this conversation. Indicates whether the conversation is still active. Number of messages in the conversation. The content of the most recent message, if available. The timestamp of the most recent message. Tags from pathway nodes visited during the conversation. The resolved delivery channel: `"sms"`, `"rcs"`, or `"whatsapp"`. AI-generated conversation summary, if available. Extracted citation variable values, if citation schemas were configured. The first successful outcome result tag, if outcomes were configured. `null` on success, or a list of errors on failure. Total number of conversations matching the query. Total number of pages available. The current page of the response. Number of items per page in the current response. ```json Response theme={null} { "data": [ { "id": "convo_abc123", "created_at": "2024-11-20T14:01:00.000Z", "updated_at": "2024-11-21T09:12:00.000Z", "user_number": "+15550001111", "agent_number": "+15552223333", "variables": { "campaign_id": "xyz789" }, "current_node_id": "node_intro", "curr_pathway_id": "pathway_abc123", "is_active": true, "message_count": 5, "last_message": "Hi there, how can I help you?", "last_message_at": "2024-11-21T09:12:00.000Z", "pathway_tags": [{"name": "Greeting", "color": "#4287f5"}], "effective_channel": "sms", "summary": null, "citation_variables": null, "disposition_tag": null } ], "errors": null, "extra": { "pagination": { "totalItems": 42, "totalPages": 5, "currentPage": 1, "pageSize": 10 } } } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Conversation by ID Source: https://docs.bland.ai/api-v1/get/sms-conversations-id GET https://api.bland.ai/v1/sms/conversations/{id} Retrieve a single SMS conversation and its messages by its ID **Enterprise Feature** - SMS is only available on Enterprise plans. Contact your Bland representative for access. ### Headers Your API key for authentication ### Path Parameters The unique ID of the conversation to retrieve. ### Response The full conversation object, including its messages. The unique ID of the conversation. ISO timestamp for when the conversation was created. ISO timestamp for when the conversation was last updated. The user's phone number in the conversation. The assistant's phone number in the conversation. Variables stored on the conversation, or `null` if none. The current node ID in the pathway, if any. The UUID of the current pathway being used in this conversation. The specific version of the pathway being used (e.g., "latest", "v1.0"). ISO timestamp when the conversation timed out due to inactivity, if applicable. When set, the conversation will not respond to new user messages but will store them. Whether the conversation is still active. The resolved delivery channel for this conversation: `"sms"`, `"rcs"`, or `"whatsapp"`. Determined based on the input channel and whether the messaging service supports RCS. AI-generated conversation summary, produced when the conversation ends and a summary prompt is configured on the SMS number. Extracted citation variable values from the conversation transcript. Keys are variable names, values are the extracted data. Only populated when citation schemas are configured. The first successful outcome result tag. Provides a quick classification of the conversation outcome without needing to inspect the full `disposition_logs`. An array of message objects in the conversation, sorted chronologically. Unique ID of the message. ISO timestamp of when the message was created. The message body. Sender phone number. Receiver phone number. Either `"USER"` or `"AGENT"` to indicate who sent the message. Delivery status of the message. Possible values: `"pending"`, `"queued"`, `"sent"`, `"delivered"`, `"read"`, `"failed"`, `"undelivered"`. The `"read"` status is available for RCS and WhatsApp channels. Twilio error code if the message failed, otherwise `null`. An array of outcome run results for this conversation. Each entry represents one outcome that was evaluated when the conversation ended. The ID of the outcome that was run. The version of the outcome's transformation code that was executed. The execution status. `"COMPLETE"` indicates the outcome ran successfully, `"ERROR"` indicates a failure. The extracted outcome values, or `null` if the run failed. Error message if the outcome run failed, otherwise `null`. Execution time in milliseconds. `null` on success, or a list of error objects if a failure occurred. ```json Response theme={null} { "data": { "id": "convo_abc123", "created_at": "2025-05-13T20:50:59.233Z", "updated_at": "2025-05-13T20:50:59.233Z", "user_id": "user_abc123", "user_number": "+15550001111", "agent_number": "+15550002222", "inbound_id": 123456, "variables": null, "current_node_id": null, "curr_pathway_id": "pathway_abc123", "curr_pathway_version": "latest", "timed_out_at": null, "last_message_at": "2025-05-13T20:50:59.233Z", "is_active": true, "effective_channel": "sms", "summary": null, "citation_variables": null, "disposition_tag": null, "messages": [ { "created_at": "2025-05-13T20:50:59.708Z", "message": "", "from": "+15550002222", "to": "+15550001111", "sender": "USER", "id": 100001, "status": null, "error_code": null }, { "created_at": "2025-05-13T20:51:00.917Z", "message": "Hey, what's up?", "from": "+15550002222", "to": "+15550001111", "sender": "AGENT", "id": 100002, "status": "delivered", "error_code": null } ], "disposition_logs": [ { "disposition_id": "d1234567-abcd-1234-efgh-123456789012", "snippet_version": 1, "status": "COMPLETE", "result": { "appointmentBooked": true, "callDisposition": "confirmed" }, "error": null, "exec_time": 1234 } ] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Post Conversation Webhook Source: https://docs.bland.ai/api-v1/get/sms-conversations-webhook GET https://api.bland.ai/v1/sms/conversations/{conversationId}/webhook Retrieve the webhook delivery log for an SMS conversation, including the payload, URL, response codes, and timing. **Enterprise Feature** - SMS is only available on Enterprise plans. Contact your Bland representative for access. ### Headers Your API key for authentication. ### Path Parameters The unique ID of the conversation to retrieve webhook logs for. ### Response The webhook log for this conversation, or `null` if no webhook has been sent. The conversation this webhook log belongs to. The webhook URL that was called. The full webhook payload that was sent. ISO timestamp for when the webhook log was created. The organization ID that owns this conversation. An array of delivery attempt records. Each entry contains: * `sent_at` — ISO timestamp of the delivery attempt * `response_code` — HTTP status code returned by your endpoint, or `null` if the request failed * `response_time` — how long the request took * `send_type` — delivery method (e.g. `"spawn"`) * `error_message` — error details if the delivery failed `null` on success, or a list of error objects if a failure occurred. ```json Response theme={null} { "data": { "conversation_id": "convo_abc123", "url": "https://example.com/sms-webhook", "payload": { "type": "status", "conversation_id": "convo_abc123", "status": "ended", "phone_number": "+15550001111", "agent_number": "+15550002222", "channel": "sms", "message_count": 5 }, "created_at": "2026-04-13T20:50:59.233Z", "user_id": "user_abc123", "metadata": [ { "sent_at": "2026-04-13T20:50:59.000Z", "response_code": 200, "response_time": "142ms", "send_type": "spawn" } ] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List SMS Numbers Source: https://docs.bland.ai/api-v1/get/sms-numbers GET https://api.bland.ai/v1/sms/numbers Retrieve all phone numbers configured for SMS, along with their configuration and conversation counts. Pass `?channel=whatsapp` or `?channel=imessage` to return WhatsApp or iMessage configurations instead of SMS. **Enterprise Feature** - SMS is only available on Enterprise plans. Contact your Bland representative for access. ### Headers Your API key for authentication. ### Response A list of phone numbers with SMS configurations. The E.164 formatted phone number assigned to the user. The configuration used when handling inbound SMS messages. When the agent sends a response, we’ll send the message details in a POST request to the URL you specify here, along with chat history. Request data fields are available to the AI agent during the call when referenced in the associated pathway or task. Maximum time to wait for a response. Default is no timeout. Twilio Messaging Service SID, if set. The assistant’s objective or system instruction. A list of tools available to the assistant. The model’s temperature setting, controlling creativity. The ID of the linked conversational pathway (if any). The specific version of the pathway to use. The ID of the first node to enter in the pathway. When `true`, a new conversation is automatically started if the user texts after the current conversation has ended. When `false`, subsequent messages are stored in the ended conversation without triggering a new reply. The timezone used for time-based variables in the conversation (e.g. `"America/New_York"`). IDs of citation schemas configured for this number. Citations are extracted when conversations end. See [Citations](/enterprise-features/citations). IDs of outcomes configured for this number. Outcomes are evaluated when conversations end. See [Outcomes](/tutorials/outcomes). Custom prompt used to generate a conversation summary when the conversation ends. The number of SMS conversations handled by this number. Always `null` on success. ```json Response theme={null} { "data": [ { "phone_number": "+14155552671", "sms_config": { "webhook": "https://example.com/sms-webhook", "request_data": { "ref": "campaign_123" }, "time_out": 15, "messaging_service_sid": "MG1234567890abcdef", "objective": "Provide quick support to customers.", "tools": ["lookup", "escalate"], "temperature": 0.7, "pathway_id": "abc123", "pathway_version": "latest", "start_node_id": "entry-node", "restart_after_end_call": true, "timezone": "America/New_York", "citation_schema_ids": ["b0477cba-1c97-4105-8ac9-46cb8eae5cf1"], "disposition_ids": ["d1234567-abcd-1234-efgh-123456789012"], "summary_prompt": "Summarize the key points and outcome of this conversation." }, "conversation_count": 34 } ], "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List TTS Generations Source: https://docs.bland.ai/api-v1/get/speak-samples GET https://api.bland.ai/v1/speak/samples List your stored text-to-speech generations. ## Headers Your API key for authentication. ## Query Parameters Number of generations to return. Number of generations to skip for pagination. Filter results to a specific voice. ## Response List of stored TTS generation objects. Unique identifier for the generation. The organization that created the generation. The user that created the generation. The text that was synthesized. The voice used for synthesis. The audio format of the generation (e.g. `pcm_44100`). Time in milliseconds from request to first audio. Cost in USD for this generation. ISO 8601 timestamp of when the generation was created. Total number of generations matching the query. The limit applied to this request. The offset applied to this request. Any errors encountered, or `null` if successful. ```json Response theme={null} { "data": [ { "id": "a3f8c2d1-4b5e-6789-0abc-def012345678", "org_id": "9e1d2c3b-4a5f-6780-bcde-f01234567890", "user_id": "5c6d7e8f-9012-3456-789a-bcdef0123456", "text": "Hello, this is a test of the text-to-speech system.", "voice_id": "2b3c4d5e-6f70-8901-2345-6789abcdef01", "output_format": "pcm_44100", "latency_ms": 1261, "cost": 0.011, "created_at": "2026-03-16T01:44:56.673Z" } ], "errors": null, "total": 1, "limit": 20, "offset": 0 } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get TTS Generation Source: https://docs.bland.ai/api-v1/get/speak-samples-id GET https://api.bland.ai/v1/speak/samples/{id} Retrieve a single stored text-to-speech generation. ## Headers Your API key for authentication. ## Path Parameters The ID of the generation to retrieve. ## Query Parameters Pass `audio` to receive the raw WAV binary instead of the metadata JSON. ## Response Without `?format=audio`, returns the generation metadata: Unique identifier for the generation. The organization that created the generation. The user that created the generation. The text that was synthesized. The voice used for synthesis. The audio format of the generation (e.g. `pcm_44100`). Base64-encoded audio data. Only present in the JSON response (not when using `?format=audio`). Time in milliseconds from request to first audio. Cost in USD for this generation. ISO 8601 timestamp of when the generation was created. With `?format=audio`, returns a raw WAV audio binary (same as the original `POST /v1/speak` response). ```json Metadata response theme={null} { "data": { "id": "a3f8c2d1-4b5e-6789-0abc-def012345678", "org_id": "9e1d2c3b-4a5f-6780-bcde-f01234567890", "user_id": "5c6d7e8f-9012-3456-789a-bcdef0123456", "text": "Hello, this is a test of the text-to-speech system.", "voice_id": "2b3c4d5e-6f70-8901-2345-6789abcdef01", "output_format": "pcm_44100", "audio_data": "base64-encoded-audio-data", "latency_ms": 1261, "cost": 0.011, "created_at": "2026-03-16T01:44:56.673Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Custom Tools Source: https://docs.bland.ai/api-v1/get/tools GET https://api.bland.ai/v1/tools Retrieve Custom Tools you've created. ### Headers Your API key for authentication. ### Response Whether the requet succeeded or failed. An array of your available tools. ```json Response theme={null} { "status": "success", "tools": [ { "tool_id": "TL-5da8347d-0ab7-415d-b156-a7fc5c6074dc", "label": null, "tool": { "name": "BookAppointment", "description": "Books the appointment. Can only be used once.", "speech": "Please wait while I book that appointment for you", "method": "POST", "timeout": 99999999, "url": "https://...", "body": { "slot": "{{input}}" }, "input_schema": { "type": "object", "example": { "date": "2024-03-16", "time": "5:00 PM" }, "required": [ "date", "time" ], "properties": { "date": "YYYY-MM-DD", "time": "HH:MM (AM|PM)" } }, "response": { "confirmation_message": "$.message" } }, "public": false }, ... ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Custom Tool Details Source: https://docs.bland.ai/api-v1/get/tools-tool-id GET https://api.bland.ai/v1/tools/{tool_id} Retrieve a Custom Tool you've created. ### Headers Your API key for authentication. ### Path Parameters The ID of the tool you want to retrieve (starting with `TL-`). ### Response Whether the requet succeeded or failed. The tool you've created. ```json Response theme={null} { "status": "success", "tool": { "tool_id": "TL-5da8347d-0ab7-415d-b156-a7fc5c6074dc", "label": null, "tool": { "name": "BookAppointment", "description": "Books the appointment. Can only be used once.", "speech": "Please wait while I book that appointment for you", "method": "POST", "timeout": 99999999, "url": "https://...", "body": { "slot": "{{input}}" }, "input_schema": { "type": "object", "example": { "date": "2024-03-16", "time": "5:00 PM" }, "required": [ "date", "time" ], "properties": { "date": "YYYY-MM-DD", "time": "HH:MM (AM|PM)" } }, "response": { "confirmation_message": "$.message" } }, "public": false } } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Translation Session Source: https://docs.bland.ai/api-v1/get/translation-sessions-id GET https://api.bland.ai/v1/translation/sessions/{session_id} Retrieve the status, duration, and billing details of a translation session Returns the current state of a translation session — useful for checking whether a session connected, how long it ran, and how many minutes were billed. ## Authentication Your API key for authentication ## Path Parameters The session UUID returned by `POST /v1/translation/sessions` ## Response Unique identifier for the session One of `PENDING` (created, WebSocket not yet connected), `ACTIVE` (audio flowing), `ENDED`, `FAILED`, `EXPIRED` (hit max duration), `ABANDONED` (never connected before token expiry) Source language code Target language code Voice used for translated speech, or `null` for the default `pcm16` or `twilio_ulaw` Inbound sample rate for `pcm16` sessions; `null` for `twilio_ulaw` Configured maximum session length Why the session ended: `client_disconnect`, `max_duration`, `error`, or `api_terminated`. `null` while the session is pending or active. Connected duration in seconds. `null` until the session ends. Billed minutes (`session_seconds` rounded up to the next minute). `null` until the session ends. ISO timestamp of session creation ISO timestamp of the WebSocket connection, or `null` if it never connected ISO timestamp of session end, or `null` while pending or active Array of error objects if the request failed ```bash cURL theme={null} curl "https://api.bland.ai/v1/translation/sessions/9592342c-0ed2-4c5e-8ceb-16aa55c804a7" \ -H "Authorization: YOUR_API_KEY" ``` ```python Python theme={null} import requests response = requests.get( "https://api.bland.ai/v1/translation/sessions/9592342c-0ed2-4c5e-8ceb-16aa55c804a7", headers={"Authorization": "YOUR_API_KEY"}, ) print(response.json()["data"]["status"]) ``` ```json Ended Session theme={null} { "data": { "session_id": "9592342c-0ed2-4c5e-8ceb-16aa55c804a7", "status": "ENDED", "source_language": "en", "target_language": "es", "voice_id": null, "audio_protocol": "pcm16", "sample_rate": 16000, "max_duration_seconds": 1800, "end_reason": "client_disconnect", "session_seconds": 19.712, "billable_minutes": 1, "created_at": "2026-06-04T18:05:07.885Z", "started_at": "2026-06-04T18:05:08.861Z", "ended_at": "2026-06-04T18:05:28.573Z" }, "errors": null } ``` # List Agents Source: https://docs.bland.ai/api-v1/get/triage-agents GET https://api.bland.ai/v1/triage/agents List triage agent profiles. ## Overview Returns the triage agent profiles available to your org. Today this is a single built-in profile, **Norm**. The endpoint exists for forward compatibility. *** ## Headers Your API key for authentication. *** ## Query Parameters Number of agents to return. Minimum 1, maximum 100. Opaque cursor returned as `next_cursor` from a previous page. *** ## Response Array of agent profiles. Internal UUID of the agent profile. Sessions on an issue carry this ID as `agent_profile_id`. Backing provider for this agent. Currently `blandcode` for Norm. Human-readable name shown in the dashboard. Always `Norm` for the built-in profile. Whether this agent is available for new sessions. Cursor for the next page, or `null`. `null` on success. ```json Response theme={null} { "data": { "items": [ { "id": "66720f06-f492-4ce6-a2f2-cd84fd54613e", "provider_type": "blandcode", "display_name": "Norm", "description": "Default triage agent", "is_active": true } ], "next_cursor": null }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Categories Source: https://docs.bland.ai/api-v1/get/triage-categories GET https://api.bland.ai/v1/triage/categories List issue categories. ## Overview Returns the org's category catalog. Built-in defaults (Transcription, Speech, Dialogue, Routing, Tools, Latency, Telephony, Bug) use IDs like `built-in:`. Custom categories created with [Create Category](/api-v1/post/triage-categories) use a UUID. Sorted alphabetically, so `next_cursor` is the name of the last item. Issue `category` is free-form on creation, this catalog is just used for autocomplete and faceted filters in the dashboard. *** ## Headers Your API key for authentication. *** ## Query Parameters Number of categories to return. Minimum 1, maximum 100. Opaque cursor returned as `next_cursor` from a previous page. For categories, this is the name of the last item from the previous page. *** ## Response Array of categories. `built-in:` for default categories, UUID for custom categories. Display name. 1-64 characters. Cursor for the next page, or `null`. `null` on success. ```json Response theme={null} { "data": { "items": [ { "id": "built-in:bug", "org_id": "5fa6dc9e-ec4d-4f94-9e0e-21f6f6a1e8f1", "name": "Bug", "created_at": "2026-05-07T05:25:56.034Z" }, { "id": "built-in:dialogue", "org_id": "5fa6dc9e-ec4d-4f94-9e0e-21f6f6a1e8f1", "name": "Dialogue", "created_at": "2026-05-07T05:26:21.855Z" }, { "id": "built-in:latency", "org_id": "5fa6dc9e-ec4d-4f94-9e0e-21f6f6a1e8f1", "name": "Latency", "created_at": "2026-05-07T05:26:21.855Z" } ], "next_cursor": "Latency" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Flag Types Source: https://docs.bland.ai/api-v1/get/triage-flag-types GET https://api.bland.ai/v1/triage/flag-types List reusable flag types in your org. ## Overview Catalog of flag types your org has used, with usage counts and the most recent note for each. Use it to render a flag-type picker. Types are normalized to lower\_snake\_case before storage. *** ## Headers Your API key for authentication. *** ## Query Parameters Number of types to return. Minimum 1, maximum 100. Opaque cursor returned as `next_cursor` from a previous page. *** ## Response Array of flag types. The normalized flag type (lower\_snake\_case). The note from the most recently filed flag of this type. Empty string if none of the flags carried a note. How many flags of this type currently exist in your org. ISO 8601 timestamp of the most recent flag of this type. Cursor for the next page, or `null`. `null` on success. ```json Response theme={null} { "data": { "items": [ { "type": "missed_handoff", "description": "Agent transferred without confirming the email.", "usage_count": 4, "last_used_at": "2026-05-07T05:26:11.327Z" }, { "type": "wrong_pathway_node", "description": "Agent jumped to closing without verifying.", "usage_count": 2, "last_used_at": "2026-05-05T22:14:01.117Z" } ], "next_cursor": null }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Issues Source: https://docs.bland.ai/api-v1/get/triage-issues GET https://api.bland.ai/v1/triage/issues List triage issues with filters and keyset pagination. ## Overview Lists triage issues for your org. Items have the same shape as [Create Issue](/api-v1/post/triage-issues). The same filters power the [Triage dashboard](https://app.bland.ai/dashboard/monitor/triage) sidebar. *** ## Headers Your API key for authentication. *** ## Query Parameters ### Pagination Number of issues to return. Minimum 1, maximum 100. Opaque cursor returned as `next_cursor` from a previous page. Omit on the first request. ### Sorting Field to sort by. Must be one of: * `last_activity_at` (default) * `created_at` * `severity` * `status` All sorts include a stable secondary sort by `id` so keyset pagination is deterministic. Sort direction. `asc` or `desc`. ### Search Free-text search across issue title and description. ### Faceted filters Filter by status. Pass a single value, or repeat the parameter for multiple. Allowed values: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `closed`. ``` ?status=todo&status=in_progress ``` Filter by severity. Allowed values: `critical`, `high`, `medium`, `low`. Repeatable. Filter by category name. Repeatable. Only return issues that have at least one resource of this type. One of `call`, `sms_conversation`, `file`. ### Scope filters Only return issues with this owner. Only return issues with this assignee. ### Date range Which date field the `date_range` filter applies to. One of `last_activity_at` or `created_at`. Relative window from now. One of: * `24h` * `7d` * `30d` * `90d` *** ## Response Array of issues. Each issue has the same shape as the response from [Create Issue](/api-v1/post/triage-issues). Cursor to pass back as the `cursor` query parameter for the next page. `null` when there are no more pages. `null` on success. ```json Response theme={null} { "data": { "items": [ { "id": "1aec670c-08d1-42dd-933b-b939508e6693", "triage_id": "T-1042", "org_id": "4edcdd57-4b33-4d1f-a905-e6859ed8cca9", "number": 1042, "title": "Agent skipped the verification step", "description": "On the Aug 12 demo flow the agent jumped to the closing node...", "status": "in_progress", "severity": "high", "source": "manual", "category": "Routing", "owner_id": null, "assignee_id": "6e6c4e2f-ec3f-4582-bd95-6fa2d6375234", "author_id": "4fa8878d-4091-4c19-849a-1c64a79609da", "external_link": null, "created_at": "2026-05-04T18:24:11.482Z", "updated_at": "2026-05-06T02:11:08.901Z", "last_activity_at": "2026-05-06T02:11:08.901Z", "resource_count": 3, "flag_count": 1, "relation_count": 0, "latest_agent_session": null, "is_processing": false, "has_unread_activity": true }, { "id": "822508a1-4e77-498b-892a-01cf6f9b1801", "triage_id": "T-1039", "org_id": "4edcdd57-4b33-4d1f-a905-e6859ed8cca9", "number": 1039, "title": "Caller transferred to wrong queue", "description": "", "status": "todo", "severity": "high", "source": "automated", "category": "Routing", "owner_id": null, "assignee_id": null, "author_id": "4fa8878d-4091-4c19-849a-1c64a79609da", "external_link": null, "created_at": "2026-05-03T22:14:01.117Z", "updated_at": "2026-05-03T22:14:01.117Z", "last_activity_at": "2026-05-03T22:14:01.117Z", "resource_count": 1, "flag_count": 0, "relation_count": 0, "latest_agent_session": null, "is_processing": false, "has_unread_activity": false } ], "next_cursor": "822508a1-4e77-498b-892a-01cf6f9b1801" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Issue Source: https://docs.bland.ai/api-v1/get/triage-issues-id GET https://api.bland.ai/v1/triage/issues/{id} Get a triage issue by ID. ## Overview Returns a single issue. Same shape as [Create Issue](/api-v1/post/triage-issues). Sub-resources (resources, flags, relations, alert bindings, activity) are fetched via their own paginated endpoints. *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. This is the `id` field returned from [Create Issue](/api-v1/post/triage-issues), not the `triage_id` short code. *** ## Response The issue. See [Create Issue](/api-v1/post/triage-issues#response) for the full field list. `null` on success. Returns 404 with `{ error: "not_found", message: "Issue not found" }` if the ID does not exist or is not in your org. ```json Response theme={null} { "data": { "id": "e0c4d12b-34b6-4f9f-b12a-5249a351ccc8", "triage_id": "T-1042", "org_id": "dc899c63-277f-4bd2-8b6a-950bbb88dc15", "number": 1042, "title": "Agent skipped the verification step", "description": "On the Aug 12 demo flow the agent jumped to the closing node without asking for the email confirmation.", "status": "in_progress", "severity": "high", "source": "manual", "category": "Routing", "owner_id": null, "assignee_id": "51007876-c89e-4ca0-b719-390dc4cf4f72", "author_id": "9a184d67-2ee4-4959-b42d-28cd80343388", "external_link": null, "created_at": "2026-05-04T18:24:11.482Z", "updated_at": "2026-05-06T02:11:08.901Z", "last_activity_at": "2026-05-06T02:11:08.901Z", "resource_count": 3, "flag_count": 1, "relation_count": 0, "latest_agent_session": null, "is_processing": false, "has_unread_activity": false }, "errors": null } ``` ```json Not Found theme={null} { "data": null, "errors": [ { "error": "not_found", "message": "Issue not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Activity Source: https://docs.bland.ai/api-v1/get/triage-issues-id-activity GET https://api.bland.ai/v1/triage/issues/{id}/activity Activity feed for an issue. ## Overview Reverse-chronological feed of issue events and Norm session events. Each entry is either `entry_kind: "issue"` (status changes, attachments, flags, comments, etc.) or `entry_kind: "agent"` (Norm session events with optional artifacts). *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. *** ## Query Parameters Number of entries to return. Minimum 1, maximum 100. Opaque cursor returned as `next_cursor` from a previous page. *** ## Response Mixed array of `IssueTimelineEntry` and `AgentTimelineEntry` objects. `issue` or `agent`. Specific event type. For `issue` entries, one of: `created`, `status_changed`, `severity_changed`, `category_changed`, `assignee_changed`, `owner_changed`, `comment`, `resource_added`, `resource_removed`, `flag_added`, `flag_removed`, `relation_added`, `relation_removed`, `alert_transition`, `accepted`, `declined`, `merged`. For `agent` entries, one of: `session_started`, `prompt`, `thought`, `action`, `response`, `artifact`, `error`, `session_stopped`. Who or what produced the event. `actor.kind` is `user`, `system`, or `agent`. For agent entries, `actor.label` is normalized to `Norm` even when the underlying record stores `blandcode`. Short, human-readable description rendered in the UI. Optional structured metadata for this entry. Shape varies by `type`. Previous status, when the entry is `status_changed`. New status, when the entry is `status_changed`. Resource link snapshots referenced by this entry, for example the resource that was attached or removed. Other issues referenced by this entry, for example the related issue when a relation was added. Reference to the Norm session this entry belongs to. * `id` (string) * `agent_profile_id` (string) * `agent_name` (string), always `Norm` * `status` (string) An artifact Norm produced (for example a draft pathway version, a snippet, or a verification report). Contains `id`, `type`, `title`, `renderer`, `status` (`pending`, `ready`, or `error`), `payload`, and `external_urls` for deep-linking. Cursor for the next page, or `null`. `null` on success. Returns 404 if the issue does not exist. ```json Response theme={null} { "data": { "items": [ { "entry_kind": "issue", "id": "0d10c1a4-8f27-4e91-a1b3-3fa7a7f3f58e", "issue_id": "4f9a7c2d-7f88-4dc4-9d1e-be83c5067f1c", "type": "comment", "actor": { "kind": "user", "id": "1f4cabe4-5f9b-4b30-bc4f-fcd3e94a5b15", "label": "John Bland", "avatar_url": null }, "detail": "Pinged the on-call eng to look at the routing rule.", "from_status": null, "to_status": null, "metadata": null, "resources": [], "referenced_issues": [], "created_at": "2026-05-07T05:26:21.449Z" }, { "entry_kind": "issue", "id": "f8c3d1c3-6c9e-4ebf-bf0a-2a8b5b2e3d31", "issue_id": "4f9a7c2d-7f88-4dc4-9d1e-be83c5067f1c", "type": "flag_added", "actor": { "kind": "user", "id": "1f4cabe4-5f9b-4b30-bc4f-fcd3e94a5b15", "label": "John Bland", "avatar_url": null }, "detail": "Added a flag.", "from_status": null, "to_status": null, "metadata": null, "resources": [ { "id": "0a9d6b23-3e0f-4f3b-9d5e-2bfa3ddbd86c", "issue_id": "4f9a7c2d-7f88-4dc4-9d1e-be83c5067f1c", "org_id": "8a73d4d5-d9a0-4c01-9b1a-0e5d3a3b4e2c", "resource_type": "call", "resource_id": "0c9b2cc5-3f4e-4057-8ad3-546e5d33a6d1", "title": "Caller asked to be transferred to billing after the agent failed to verify their account.", "status": "available", "metadata": { "created_at": "2026-04-30T14:11:08.000Z" }, "attached_by_id": "1f4cabe4-5f9b-4b30-bc4f-fcd3e94a5b15", "created_at": "2026-05-07T05:25:56.361Z" } ], "referenced_issues": [], "created_at": "2026-05-07T05:26:11.327Z" } ], "next_cursor": "f8c3d1c3-6c9e-4ebf-bf0a-2a8b5b2e3d31" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Affected Context Source: https://docs.bland.ai/api-v1/get/triage-issues-id-affected GET https://api.bland.ai/v1/triage/issues/{id}/affected Calls, pathways, and personas affected by an issue. ## Overview Derived rollup of every call attached to an issue, grouped by pathway and persona. Powers the dashboard's Affected panel. Not paginated. *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. *** ## Response The issue this context belongs to. Every attached call, with the pathway and persona it ran against. Display title for the call. Falls back to a short ID if no pathway or persona name is available. ISO 8601 timestamp. One entry per distinct pathway across the attached calls, with `call_count` and `call_ids` so you can deep-link. One entry per distinct persona, with `call_count` and `call_ids`. `null` on success. Returns 404 if the issue does not exist. ```json Response theme={null} { "data": { "issue_id": "db49f7b8-3214-4cb2-9f80-9d04379a9b8a", "calls": [ { "call_id": "95330a0e-d441-4586-96f8-28ea60677296", "title": "Sales demo flow", "started_at": "2026-04-30T14:11:08.000Z", "pathway_id": "8b2bb517-94d3-4cf6-9c7b-8c8ab9f8c4a1", "pathway_name": "Sales demo flow", "pathway_version_id": "f3ad7b24-8ab2-4f01-b04e-2c9f96d0d124", "version_number": 12, "version_label": "production", "persona_id": null, "persona_name": null } ], "pathways": [ { "pathway_id": "8b2bb517-94d3-4cf6-9c7b-8c8ab9f8c4a1", "pathway_name": "Sales demo flow", "pathway_version_id": "f3ad7b24-8ab2-4f01-b04e-2c9f96d0d124", "version_number": 12, "version_label": "production", "call_count": 1, "call_ids": ["95330a0e-d441-4586-96f8-28ea60677296"] } ], "personas": [] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Flags Source: https://docs.bland.ai/api-v1/get/triage-issues-id-flags GET https://api.bland.ai/v1/triage/issues/{id}/flags List flags on an issue. ## Overview Returns the flags filed on this issue. Same shape as [Add Flag](/api-v1/post/triage-issues-id-flags). *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. *** ## Query Parameters Number of flags to return. Minimum 1, maximum 100. Opaque cursor returned as `next_cursor` from a previous page. *** ## Response Array of flags. See [Add Flag](/api-v1/post/triage-issues-id-flags#response) for the field list. Cursor for the next page, or `null`. `null` on success. Returns 404 if the issue does not exist. ```json Response theme={null} { "data": { "items": [ { "id": "8ce11a7a-1a30-4c2c-9d3a-3e9aa56d2f02", "org_id": "5fa6dc9e-ec4d-4f94-9e0e-21f6f6a1e8f1", "issue_id": "cd4e1b6a-9a4c-4ec7-9c91-aa8b8aef0c89", "call_id": "02d77f64-342d-4c41-b2f6-02621eb94fc3", "type": "missed_handoff", "note": "Agent transferred without confirming the email.", "node_id": null, "node_name": null, "message_index": 12, "message_text": "OK, transferring you now.", "author_id": "32c10b62-0a4e-4ad8-bd4e-9b6e2a6e0a4f", "created_at": "2026-05-07T05:26:11.327Z" } ], "next_cursor": null }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Relations Source: https://docs.bland.ai/api-v1/get/triage-issues-id-relations GET https://api.bland.ai/v1/triage/issues/{id}/relations List relations on an issue. ## Overview Returns the relations to and from this issue. Each item carries `direction` (`outgoing` or `incoming`) and the related issue's `triage_id` and `title` denormalized for display. *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. *** ## Query Parameters Number of relations to return. Minimum 1, maximum 100. Opaque cursor returned as `next_cursor` from a previous page. *** ## Response Array of relations. See [Link Related Issue](/api-v1/post/triage-issues-id-relations#response) for the field list. Cursor for the next page, or `null`. `null` on success. Returns 404 if the issue does not exist. ```json Response theme={null} { "data": { "items": [ { "id": "172c839b-130d-4712-a09c-b767a78542ea", "org_id": "f5b40b9e-bc05-4b8a-9af1-d8f6a8a3a201", "issue_id": "9bbe5547-d5b1-4b83-9f80-87c4af7c6b34", "related_issue_id": "849ee9ce-be6b-4f9c-8e55-2736aeeb579f", "related_triage_id": "T-1004", "related_title": "Caller transferred to wrong queue", "relation_type": "duplicate_of", "direction": "outgoing", "created_by_id": "75c5c7da-a5d6-4e26-a51e-1ae8ef2bfa4a", "created_at": "2026-05-07T05:28:29.358Z" } ], "next_cursor": null }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Resources Source: https://docs.bland.ai/api-v1/get/triage-issues-id-resources GET https://api.bland.ai/v1/triage/issues/{id}/resources List resources attached to an issue. ## Overview Returns the resources currently attached. Same shape as [Attach Resource](/api-v1/post/triage-issues-id-resources). For a rollup of calls, pathways, and personas, use [Get Affected Context](/api-v1/get/triage-issues-id-affected). *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. *** ## Query Parameters Number of resources to return. Minimum 1, maximum 100. Opaque cursor returned as `next_cursor` from a previous page. *** ## Response Array of resource links. See [Attach Resource](/api-v1/post/triage-issues-id-resources#response) for the field list. Cursor for the next page, or `null`. `null` on success. Returns 404 if the issue does not exist. ```json Response theme={null} { "data": { "items": [ { "id": "0a9d6b23-3e0f-4f3b-9d5e-2bfa3ddbd86c", "issue_id": "4f9a7c2d-7f88-4dc4-9d1e-be83c5067f1c", "org_id": "8a73d4d5-d9a0-4c01-9b1a-0e5d3a3b4e2c", "resource_type": "call", "resource_id": "4d6e79af-13ad-4c85-8c6d-7e696d6b6380", "title": "Caller asked to be transferred to billing after the agent failed to verify their account.", "status": "available", "metadata": { "created_at": "2026-04-30T14:11:08.000Z" }, "attached_by_id": "1f4cabe4-5f9b-4b30-bc4f-fcd3e94a5b15", "created_at": "2026-05-07T05:25:56.361Z" } ], "next_cursor": null }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Knowledge Bases Source: https://docs.bland.ai/api-v1/get/vectors GET https://api.bland.ai/v1/knowledgebases List all knowledge bases in your account. ### Headers Your API key for authentication. Include the full text of the documents stored in the knowledge base. This can be useful for debugging, but may return large amounts of data. ### Response An array of objects, for each knowledge base in your account. The unique identifier for the knowledge base. The name of the knowledge base. A description of the knowledge base. ```json Response theme={null} { "vectors": [ { "vector_id": "KB-55e64dae-1585-4632-bc97-c909c288c6bc", "name": "Bland AI FAQs", "description": "Business facts, policies, and frequently asked questions for Bland AI." } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Knowledge Base Details Source: https://docs.bland.ai/api-v1/get/vectors-id GET https://api.bland.ai/v1/knowledgebases/{vector_id} View the details for a specific knowledge base. ### Headers Your API key for authentication. Include the full text of the documents stored in the knowledge base. This can be useful for debugging, but may return large amounts of data. ### Path Parameters The `vector_id` of the knowledge base to view. ### Response The unique identifier for the knowledge base. The name of the knowledge base. A description of the knowledge base. ```json Response theme={null} { { "vector_id": "KB-55e64dae-1585-4632-ae97-c909c288c6bc", "name": "Bland AI FAQs", "description": "Business facts, policies, and frequently asked questions for Bland AI." } } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Voices Source: https://docs.bland.ai/api-v1/get/voices GET https://api.bland.ai/v1/voices List all voices available to your account. ## Overview Returns every voice your account can use: Bland's curated default voices, voices you have cloned, voices you have added to your library from the public catalog, and voices owned by your org. For just the publicly-shared library, use [List Shared Voices](/api-v1/get/voices-shared) instead. *** ## Headers Your API key for authentication. *** ## Response Array of voices. UUID of the voice. Pass this as `voice_id` to [Speak](/api-v2/post/tts) or any voice management endpoint. Display name. For curated default voices this can also be used in the `voice` field when sending calls. Short human-readable description of the voice. `true` for shared library voices and Bland curated voices, `false` for voices private to your org. Labels describing the voice (language, style, source). Bland's recommended curated voices carry the `"Bland Curated"` tag. Owner UUID. `null` for curated default voices. Underlying model identifier. Format varies by engine; treat as opaque. Engine identifier. One of `BTTS`, `BTTS_V2`, `BTTS_V3`, or `LEGACY`. `true` if the voice has been fine-tuned past the base clone. `true` for voices in the Bland creator program. Creator voices may carry a per-character fee in addition to synthesis cost. Total number of ratings the voice has received. Alias of `ratings` returned for backwards compatibility. Average rating, 0-5. The calling user's rating for this voice, if any. `null` when the caller has not rated it. Submit via [Rate Voice](/api-v1/post/voices-id-rate). Creator name for voices in the creator program. `null` otherwise. ```json Response theme={null} { "voices": [ { "id": "d4610ec1-933d-44c9-a05f-53df2437808d", "name": "maya", "description": "Young American Female", "public": true, "tags": ["english", "soft", "Bland Curated"], "user_id": null, "voice_id": "5134ee24-7d14-49a4-8aff-2215d295b6cc", "service": "BTTS_V2", "finetuned": false, "is_creator_voice": false, "ratings": 1234, "total_ratings": 1234, "average_rating": 4.6, "my_rating": null, "creator_display_name": null }, { "id": "5f29c646-1881-4882-8d8c-8616a2d5ce9c", "name": "MyClone", "description": null, "public": false, "tags": ["Beige Clone V3", "cloned", "female"], "user_id": "ffcf63aa-6298-471f-91ad-5d2653812042", "voice_id": "c18a1cd5-91ef-4b06-841a-e58b8b487e8c", "service": "BTTS_V3", "finetuned": false, "is_creator_voice": false, "ratings": 0, "total_ratings": 0, "average_rating": 0, "my_rating": null, "creator_display_name": null } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Voice Source: https://docs.bland.ai/api-v1/get/voices-id GET https://api.bland.ai/v1/voices/{id} Get details on a single voice. ## Overview Returns the full record for a single voice. Same field shape as [List Voices](/api-v1/get/voices). The `id` path parameter accepts either the voice's UUID or its `name` (for curated default voices like `maya`, `derek`, `willow`). *** ## Headers Your API key for authentication. *** ## Path Parameters Voice UUID or curated voice name. For example: * `GET /v1/voices/d4610ec1-933d-44c9-a05f-53df2437808d` * `GET /v1/voices/maya` *** ## Response The voice record. See [List Voices](/api-v1/get/voices#response) for the full field list. ```json Response theme={null} { "voice": { "id": "d4610ec1-933d-44c9-a05f-53df2437808d", "name": "maya", "description": "Young American Female", "public": true, "tags": ["english", "soft", "Bland Curated"], "user_id": null, "voice_id": "5134ee24-7d14-49a4-8aff-2215d295b6cc", "service": "BTTS_V2", "finetuned": false, "is_creator_voice": false, "ratings": 1234, "total_ratings": 1234, "average_rating": 4.6, "my_rating": null, "creator_display_name": null } } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Voice Samples Source: https://docs.bland.ai/api-v1/get/voices-id-samples GET https://api.bland.ai/v1/voices/{id}/samples List the training samples attached to a voice clone you own. ## Overview Returns the training samples used to create a voice clone. Only voices owned by your org return samples; default voices and shared library voices return `400 VOICE_SAMPLES_ERROR` with the message `"Voice is a default voice and not owned by the user."` Retrievable samples are only present for V1 (`BTTS`) voices. **V2 and V3 voices both return `[]`** even though they were cloned from a sample, because the underlying single source clip is not exposed via this endpoint. Use the source audio of your original clone for those. *** ## Headers Your API key for authentication. *** ## Path Parameters UUID of the voice. *** ## Query Parameters When `true`, includes base64-encoded audio data with each sample. Increases response size significantly. Use [Get Voice Sample](/api-v1/get/voices-id-samples-sample-id) for a single sample with audio instead. *** ## Response Array of training sample records. Empty array for V3 voices. UUID of the sample. UUID of the parent voice. Transcribed text for the sample. `null` if transcription has not been generated yet. Length of the sample audio. Base64-encoded audio. Only present when `include_audio=true`. ISO 8601 timestamp. ```json Response theme={null} { "samples": [] } ``` ```json Not Owned theme={null} { "data": null, "errors": [ { "error": "VOICE_SAMPLES_ERROR", "message": "Voice is a default voice and not owned by the user." } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Voice Sample Source: https://docs.bland.ai/api-v1/get/voices-id-samples-sample-id GET https://api.bland.ai/v1/voices/{id}/samples/{sample_id} Download a single training sample as audio or JSON metadata. ## Overview Returns a single training sample for a voice you own. By default the response is the raw WAV audio. Pass `?format=json` to get the metadata plus base64-encoded audio instead. Only voices owned by your org return samples. Default voices and shared-library voices return `400 VOICE_SAMPLE_ERROR`. *** ## Headers Your API key for authentication. *** ## Path Parameters UUID of the parent voice. UUID of the sample to fetch. *** ## Query Parameters Response format. `audio` returns the raw WAV binary, `json` returns sample metadata with base64-encoded audio under `data`. *** ## Response With `format=audio` (default), returns the WAV binary with: * `Content-Type: audio/wav` * `Content-Disposition: attachment; filename="sample-.wav"` With `format=json`, returns sample metadata. Only present in JSON mode. Base64-encoded WAV audio. ```http Audio Response theme={null} HTTP/1.1 200 OK Content-Type: audio/wav Content-Length: 245318 Content-Disposition: attachment; filename="sample-d15b199a.wav" ``` ```json JSON Response theme={null} { "sample": { "id": "d15b199a-1b79-4664-9a9a-b149ee3b136a", "voice_id": "73d4c04b-1e15-4272-9c7f-8d2955914ba9", "transcription": "Hello and welcome to Bland.", "duration_seconds": 11.4, "audio_data": "", "created_at": "2026-06-22T21:34:31.347Z" } } ``` ```json Audio Not Found theme={null} { "data": null, "errors": [ { "error": "AUDIO_NOT_FOUND", "message": "No audio data found for this sample" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Voice Settings Source: https://docs.bland.ai/api-v1/get/voices-id-settings GET https://api.bland.ai/v1/voices/{id}/settings Get the current consistency/expressiveness defaults on a voice you own. ## Overview Returns the current synthesis defaults stored on a voice you own, plus the valid range for each tunable so callers do not have to discover the bounds by trial and error. Different engines expose different settings: * **BTTS V1**: `consistency` (0-1 float) and `expressiveness` (0-1 float). * **BTTS V2**: `consistency` (0-64 integer, lower is more consistent) and `expressiveness` (0-1 float). * **BTTS V3**: a single boolean `boost_language_consistency`. To update these settings, use [Update Voice Settings](/api-v1/post/voices-id-settings). *** ## Headers Your API key for authentication. *** ## Path Parameters UUID of the voice. *** ## Response For V1 and V2 voices: The engine identifier, e.g. `BTTS_V2`. Valid ranges for the tunables. `1` for V1, `64` for V2. For V3 voices: `BTTS_V3`. ```json V2 Response theme={null} { "consistency": 8, "expressiveness": 1, "service": "BTTS_V2", "limits": { "consistency": { "min": 0, "max": 64 }, "expressiveness": { "min": 0, "max": 1 } } } ``` ```json V3 Response theme={null} { "boost_language_consistency": true, "service": "BTTS_V3" } ``` ```json Not Owned theme={null} { "data": null, "errors": [ { "error": "VOICE_SETTINGS_ERROR", "message": "Voice is a default voice and not owned by the user." } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Shared Voices Source: https://docs.bland.ai/api-v1/get/voices-shared GET https://api.bland.ai/v1/voices/shared Browse the public Bland voice library. ## Overview Returns the catalog of publicly-shared voices in the Bland library. These are voices that other creators have published for everyone to use; they are not in your org's library until you call [Add Library Voice](/api-v1/post/voices-library-add-id). Use this endpoint to power voice-picker UIs and discovery flows. *** ## Headers Your API key for authentication. *** ## Query Parameters Number of voices to return. Pagination offset. Free-text search across voice name, description, and tags. Filter to voices tagged for a specific language (for example `en`, `es`, `ja`). *** ## Response Array of shared voices. UUID of the shared voice. Pass to [Add Library Voice](/api-v1/post/voices-library-add-id) to add it to your org. Display name in the public library. The voice's underlying TTS service. Examples: `BTTS_V2`, `BTTS_V3`. `true` if the voice is part of the creator program. Creator voices may carry a per-character fee in addition to the synthesis cost. Total number of ratings the voice has received. Alias of `ratings` returned for backwards compatibility. Average rating, 0-5. Internal score used to surface trending voices in the dashboard. ISO 8601 timestamp. Always `true` for entries in the shared library. Name of the creator who published the voice, if applicable. Per-character creator fee in cents per 1,000 characters. `null` for non-creator voices. Per-character creator fee in cents per 10,000 characters. `null` for non-creator voices. ```json Response theme={null} { "voices": [ { "id": "e657b253-ca1f-41cc-b25f-7267ae644519", "name": "StephenD", "description": null, "service": "BTTS_V2", "is_creator_voice": false, "ratings": 12, "rating_count": 12, "rating_avg": 4.5, "trending_score": 0, "tags": ["english", "male", "cloned"], "created_at": "2026-04-16T09:14:25.232Z", "public": true, "creator_display_name": null, "creator_fee_cents_per_1k": null, "creator_fee_cents_per_10k": null } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Custom Components Source: https://docs.bland.ai/api-v1/get/widget-custom-components GET https://api.bland.ai/v1/widget/custom_components Retrieves a specific custom component by ID. ### Headers Your API key for authentication. ### Response HTTP status code (200 for success). * `id` (string): Custom component UUID * `org_id` (string): Organization UUID * `widget_id` (string): Widget identifier UUID * `pathway_id` (string): Associated pathway UUID * `pathway_node` (string): Pathway node ID to display the custom component on * `width` (string): Widget width dimension * `height` (string): Widget height dimension * `variables` (string\[]): Array of variable names to pass into the custom component iframe URL as query params * `iframe_url` (string): URL for the iframe source * `created_at` (string): ISO timestamp * `updated_at` (string): ISO timestamp Always null on successful response. ```json Response theme={null} { "data": [ { "created_at": "2025-10-02T21:45:27.633Z", "updated_at": "2025-10-02T21:45:27.633Z", "id": "70b56282-8db5-4e26-aad9-098c099fb1db", "org_id": "99a0d526-6910-4f31-92b8-72834d0827fb", "widget_id": "7d1a8c0d-5346-4f96-9f5c-d888e273eaf0", "pathway_id": "05f4b269-e79a-4825-b4cd-7778f782bfad", "pathway_node": "1", "width": "100%", "height": "300px", "variables": [ "firstName" ], "iframe_url": "https://widget-custom-components.vercel.app" } ], "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Widget by ID Source: https://docs.bland.ai/api-v1/get/widget-id GET https://api.bland.ai/v1/widget/{id} Retrieves a specific widget by ID. ### Headers Your API key for authentication. ### Path Parameters UUID of the widget to retrieve. ### Response HTTP status code (200 for success). The widget object containing: * `id` (string): Widget UUID * `pathway_id` (string | null): Associated pathway UUID * `agent_id` (string | null): Associated agent UUID or null * `agent_prompt` (string | null): Agent prompt used instead of pathway * `allowed_domains` (string\[]): Array of allowed domains * `messages_per_minute` (number): Rate limit for messages * `config` (object): Widget configuration object * `created_at` (string): ISO timestamp * `updated_at` (string): ISO timestamp Always null on successful response. ```json Response theme={null} { "status": 200, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "pathway_id": "a0f0d4ed-f5f5-4f16-b3f9-22166594d7a7", "agent_id": "46f37229-7d12-44be-b343-6e68274cfbea", "allowed_domains": ["example.com", "subdomain.example.com"], "messages_per_minute": 10, "config": { "theme": "light", "position": "bottom-right", "greeting": "Hello! How can I help you today?" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T12:45:00Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Widget Threads Source: https://docs.bland.ai/api-v1/get/widget-id-threads GET https://api.bland.ai/v1/widget/{id}/threads Retrieves all conversation threads for a specific widget. Returns threads ordered by creation date (newest first) with associated messages ordered chronologically. ### Headers Your API key for authentication. ### Path Parameters UUID of the widget to retrieve threads for. ### Query Parameters Page number for pagination (minimum 1). Number of threads per page (minimum 1, maximum 100). Filter results to a specific thread by its UUID. ### Response HTTP status code (200 for success). * `threads` (array): Array of thread objects, each containing: * `id` (string): Thread UUID * `created_at` (string): ISO timestamp * `ended_at` (string | null): ISO timestamp of when the thread ended * `live_agent_handoff_at` (string | null): ISO timestamp of when the thread was handed off to a live agent * `visitor_id` (string | null): UUID of visitor (if available) * `messages` (array): Array of message objects, each containing: * `id` (string): Message UUID * `sender_type` (string): Either "USER" or "ASSISTANT" * `created_at` (string): ISO timestamp * `content` (string): Message content * `original_content` (string | null): Original message content before any modifications * `total` (number): Total number of threads matching the query (useful for calculating total pages) This endpoint does not return 404 if no threads exist; it returns an empty array instead. ```json Response theme={null} { "status": 200, "data": { "threads": [ { "id": "thread_550e8400-e29b-41d4-a716-446655440000", "created_at": "2024-01-15T14:30:00Z", "ended_at": null, "live_agent_handoff_at": null, "visitor_id": "visitor_123456789", "messages": [ { "id": "msg_001", "sender_type": "USER", "created_at": "2024-01-15T14:30:00Z", "content": "Hello, I need help with my order", "original_content": null }, { "id": "msg_002", "sender_type": "ASSISTANT", "created_at": "2024-01-15T14:30:15Z", "content": "I'd be happy to help you with your order! Can you please provide your order number?", "original_content": null }, { "id": "msg_003", "sender_type": "USER", "created_at": "2024-01-15T14:30:45Z", "content": "It's order #12345", "original_content": null } ] }, { "id": "thread_660f9511-f3ac-52e5-b827-557766551111", "created_at": "2024-01-15T13:15:00Z", "ended_at": "2024-01-15T13:20:00Z", "live_agent_handoff_at": null, "visitor_id": null, "messages": [ { "id": "msg_101", "sender_type": "USER", "created_at": "2024-01-15T13:15:00Z", "content": "What are your business hours?", "original_content": null }, { "id": "msg_102", "sender_type": "ASSISTANT", "created_at": "2024-01-15T13:15:05Z", "content": "Our business hours are Monday through Friday, 9 AM to 6 PM EST.", "original_content": null } ] } ], "total": 2 }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Widgets Source: https://docs.bland.ai/api-v1/get/widgets GET https://api.bland.ai/v1/widgets Retrieves all widgets associated with your account. ### Headers Your API key for authentication. ### Response HTTP status code (200 for success). The widget object containing: * `id` (string): Widget UUID * `pathway_id` (string | null): Associated pathway UUID * `agent_id` (string | null): Associated agent UUID or null * `agent_prompt` (string | null): Agent prompt used instead of pathway * `allowed_domains` (string\[]): Array of allowed domains * `messages_per_minute` (number): Rate limit for messages * `config` (object): Widget configuration object * `created_at` (string): ISO timestamp * `updated_at` (string): ISO timestamp Always null on successful response. ```json Response theme={null} { "status": 200, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pathway_id": "a0f0d4ed-f5f5-4f16-b3f9-22166594d7a7", "agent_id": "46f37229-7d12-44be-b343-6e68274cfbea", "allowed_domains": ["example.com", "subdomain.example.com"], "messages_per_minute": 10, "config": { "theme": "light", "position": "bottom-right", "greeting": "Hello! How can I help you today?" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T12:45:00Z" } ], "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Alarm Source: https://docs.bland.ai/api-v1/patch/alarms-id PATCH https://api.bland.ai/v1/alarms/{id} Update an alarm configuration. ### Headers Your API key for authentication. ### Path Parameters Alarm configuration ID. ### Body Parameters Updated positive numeric threshold. Notes: * `threshold` is a sensitivity scalar (higher values are less sensitive; lower values are more sensitive). * The Dashboard may display an approximate "% change" visualization for this value. Treat that UI percentage as a directional aid, not an exact conversion. Dashboard sensitivity presets map to these threshold values: * `Sensitive` → `0.5` * `Normal` → `1.0` * `Relaxed` → `2.0` * `Critical` → `2.5` Controls whether this alarm is actively evaluated. * `true`: Alarm is active. The system will evaluate this metric on scheduled runs and can generate alarm/recovery events and notifications. * `false`: Alarm is paused. The config is retained, but scheduled evaluation and notifications for this alarm are disabled until re-enabled. Updated webhook settings. Set to `null` to clear. `webhook_config` should be a JSON object with: * `url` (string, required when object is provided) * `headers` (object, optional) Example: ```json theme={null} { "webhook_config": { "url": "https://example.com/webhooks/alarms", "headers": { "Content-Type": "application/json" } } } ``` Updated email recipients. Updated SMS recipients. ### Response Updated alarm configuration object. Updated webhook settings object. Header values may be masked in API responses. Updated email recipients. Can be an empty array if none are configured. Updated SMS recipients. Can be an empty array if none are configured. `null` on success, otherwise an array of error objects. ```json Success theme={null} { "data": { "alarm": { "id": "d4cfd8aa-7df4-4fd7-a5cf-8c5d2871a1f8", "metric_type": "latency", "enabled": true, "threshold": 0.5, "webhook_config": { "url": "https://example.com/webhooks/alarms", "headers": { "Content-Type": "appl***" } }, "email_addresses": ["alerts@example.com"], "sms_numbers": [], "created_at": "2026-03-12T16:13:02.694Z", "updated_at": "2026-03-12T16:45:52.721Z" } }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Citation Schema Source: https://docs.bland.ai/api-v1/patch/citation-schemas PATCH https://api.bland.ai/v1/citation_schemas/ Update an existing citation schema's name, description, or schema configuration. ### Headers Your API key for authentication. ### Query Parameters The unique identifier of the citation schema to update. ### Body Parameters The updated name for the citation schema. The updated description for the citation schema. The updated JSON schema configuration for citation extraction. This completely replaces the existing schema configuration. The schema object can contain: * `variables`: Array of variable definitions for data extraction * `groupings`: Array of related variable collections * `conditions`: Array of conditional logic rules Example structure: ```json theme={null} { "variables": [ { "name": "Customer Name", "description": "The full name of the customer", "type": "string" }, { "name": "Lead Score", "description": "Numeric score indicating lead quality (1-10)", "type": "number" } ], "groupings": [ { "name": "Lead Information", "variables": ["Customer Name", "Lead Score"] } ], "conditions": [] } ``` At least one field (name, description, or schema) must be provided in the request body. ### Response HTTP status code (200 for success). The updated citation schema object. The unique identifier for the citation schema (UUID format). The updated name of the citation schema. The updated description of the citation schema. The organization ID that owns this schema. The updated JSON schema configuration for citation extraction. The timestamp when the citation schema was originally created (ISO 8601 format). Will be null for successful requests. ### Error Responses Returned when: * The schema ID parameter is missing * No update fields are provided in the request body Returned when the specified citation schema is not found or doesn't belong to your organization. ```json Response theme={null} { "status": 200, "data": { "id": "3f4a2b1c-8e9d-4c7f-b2a1-5e8d9c7f6a2b", "name": "Enhanced Customer Information Extraction", "description": "Extracts comprehensive customer demographics, contact information, and lead qualification data from call transcripts", "org_id": "7c8b9a2d-3e4f-5c6b-8a9d-2e3f4c5b6a7c", "schema": { "variables": [ { "name": "Customer Name", "description": "The full name of the customer", "type": "string" }, { "name": "Customer Email", "description": "The email address provided by the customer", "type": "string" }, { "name": "Phone Number", "description": "The customer's phone number", "type": "string" }, { "name": "Lead Score", "description": "Numeric score indicating lead quality (1-10)", "type": "number" }, { "name": "Interested in Demo", "description": "Whether the customer wants to schedule a demo", "type": "boolean" } ], "groupings": [ { "name": "Contact Information", "variables": ["Customer Name", "Customer Email", "Phone Number"] }, { "name": "Lead Qualification", "variables": ["Lead Score", "Interested in Demo"] } ], "conditions": [ { "condition": { "value": "5", "operator": ">=", "variable": "Lead Score" }, "variables": [ { "name": "Follow-up Priority", "type": "string", "description": "Priority level for follow-up (high, medium, low)" } ] } ] }, "created_at": "2023-12-15T14:30:00.000Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Contact Source: https://docs.bland.ai/api-v1/patch/contacts-id PATCH https://api.bland.ai/v1/contacts/{contact_id} Update an existing contact's information. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the contact to update. ### Body Parameters Updated name for the contact. Email address to add or update for the contact. External ID to add or update for the contact. Custom metadata to merge with existing metadata. New keys are added, existing keys are updated. ### Response The updated contact object. Unique identifier for the contact. Organization ID the contact belongs to. Contact's name. Custom metadata associated with the contact. ISO timestamp when the contact was created. ISO timestamp when the contact was last updated. Error array (null on success). ```json Response theme={null} { "data": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "org_id": "11111111-2222-3333-4444-555555555555", "name": "John Smith", "metadata": { "source": "web_signup", "preferences": { "language": "en" }, "verified": true }, "created_at": "2025-07-20T10:30:00.000Z", "updated_at": "2025-07-22T16:00:00.000Z" }, "errors": null } ``` ```json Not Found theme={null} { "data": null, "errors": [ { "error": "NOT_FOUND", "message": "Contact not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Eval Agent Source: https://docs.bland.ai/api-v1/patch/evals-agents-id PATCH https://api.bland.ai/v1/evals/agents/{eval_agent_id} Update an eval agent's metadata or repoint its active version. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the eval agent to update. ### Body Parameters New display name for the eval agent. Between 1 and 200 characters. Updated description, or `null` to clear it. Repoint the published version to this version ID. Pass `null` to unpublish the agent. Key-value metadata to associate with the eval agent. Values must be strings. Replaces the existing metadata object. This endpoint updates agent-level fields only. To edit prompts, levels, or targets, update the agent's draft version using the Update Eval Agent Version endpoint. ### Response The updated eval agent. Unique identifier for the eval agent. ID of the organization that owns this eval agent. Unique slug key for the eval agent within the organization. Display name of the eval agent. Description of what the eval agent grades, or `null`. ID of the current editable draft version. ID of the published version, or `null` if unpublished. Updated key-value metadata. Values are strings. ISO 8601 timestamp for when the eval agent was created. ISO 8601 timestamp for when the eval agent was last updated. ISO 8601 timestamp if the eval agent has been soft-deleted, otherwise `null`. The current editable draft version of the eval agent. Unique identifier for this version. ID of the organization that owns this version. ID of the parent eval agent. Sequential version number. Name of this version. Optional description of this version. State of this version. One of `editable` or `archived`. One of `text` or `audio`. The system prompt for the judge LLM, in Markdown. The grading prompt for the judge LLM, in Markdown. Verdict levels for graded mode. Empty array for pass/fail mode. Which level keys count as a target match. Relative weight of this agent in aggregate scoring. Between 0 and 100. ID of the version this was forked from, or `null`. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. ISO 8601 timestamp for when this version was last updated. ```json Response theme={null} { "errors": null, "data": { "agent": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "org_id": "f0e1d2c3-b4a5-9678-fedc-ba9876543210", "key": "empathy-check", "name": "Empathy Check (Updated)", "description": "Grades how empathetic the agent sounds during difficult conversations.", "current_version_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "active_version_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "metadata": { "team": "cx-quality" }, "created_at": "2026-03-01T09:00:00.000Z", "updated_at": "2026-05-27T11:00:00.000Z", "deleted_at": null }, "current_version": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "org_id": "f0e1d2c3-b4a5-9678-fedc-ba9876543210", "eval_agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 3, "name": "Empathy Check v3", "description": "Refined grading criteria based on feedback.", "state": "editable", "modality": "audio", "system_prompt_md": "You are an expert call quality reviewer.", "prompt_md": "Did the agent express empathy when the caller described their problem?", "levels": [ { "level_key": "excellent", "label": "Excellent", "prompt_md": "The agent clearly and warmly acknowledged the caller's feelings.", "color": "emerald" }, { "level_key": "poor", "label": "Poor", "prompt_md": "The agent ignored or dismissed the caller's feelings.", "color": "rose" } ], "target_level_keys": ["excellent"], "weight": 10, "created_from_version_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-15T08:00:00.000Z", "updated_at": "2026-05-27T10:00:00.000Z" } } } ``` # Update Eval Agent Version Source: https://docs.bland.ai/api-v1/patch/evals-agents-id-versions-id PATCH https://api.bland.ai/v1/evals/agents/{eval_agent_id}/versions/{version_id} Edit a draft version's prompt, levels, targets, or weight. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the eval agent. The unique identifier of the version to update. Must be in the `editable` state. ### Body Parameters Updated display name for this version. Between 1 and 200 characters. Updated description, or `null` to clear it. The modality for this version. One of `text` or `audio`. Updated system prompt for the judge LLM, in Markdown. Maximum 8000 characters. Updated grading prompt for the judge LLM, in Markdown. Maximum 8000 characters. Verdict levels for graded mode. Pass an empty array for pass/fail mode. Maximum 5 levels. Each level object requires: * `level_key` (string, 1-64 characters): unique key within this version. * `label` (string, 1-80 characters): display label shown in results. * `prompt_md` (string): description used in the grading prompt. * `color` (string, optional): one of `rose`, `amber`, `gold`, `emerald`, `blue`, `indigo`, `violet`, `fog`. Which level keys count as a target match. Must be empty for pass/fail agents. Every key listed must match a defined level. Relative weight of this agent in aggregate scoring. Between 0 and 100. ### Response Unique identifier for this version. ID of the organization that owns this version. ID of the parent eval agent. Sequential version number. Name of this version. Description of this version, or `null`. State of this version. One of `editable` or `archived`. One of `text` or `audio`. The system prompt for the judge LLM, in Markdown. The grading prompt for the judge LLM, in Markdown. Updated verdict levels. Each level contains `level_key`, `label`, `prompt_md`, and optionally `color`. Updated target level keys. Updated weight. Between 0 and 100. ID of the version this was forked from, or `null`. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. ISO 8601 timestamp for when this version was last updated. ```json Response theme={null} { "errors": null, "data": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "org_id": "f0e1d2c3-b4a5-9678-fedc-ba9876543210", "eval_agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 3, "name": "Empathy Check v3", "description": "Refined grading criteria with clearer level descriptions.", "state": "editable", "modality": "audio", "system_prompt_md": "You are an expert call quality reviewer specializing in empathy.", "prompt_md": "Did the agent acknowledge and validate the caller's feelings? Review the full transcript and select the most appropriate verdict.", "levels": [ { "level_key": "excellent", "label": "Excellent", "prompt_md": "The agent proactively acknowledged the caller's feelings with warmth and specificity.", "color": "emerald" }, { "level_key": "adequate", "label": "Adequate", "prompt_md": "The agent showed some empathy but responses were generic or brief.", "color": "amber" }, { "level_key": "poor", "label": "Poor", "prompt_md": "The agent ignored, dismissed, or failed to acknowledge the caller's feelings.", "color": "rose" } ], "target_level_keys": ["excellent"], "weight": 15, "created_from_version_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-15T08:00:00.000Z", "updated_at": "2026-05-27T12:00:00.000Z" } } ``` # Update User Template Source: https://docs.bland.ai/api-v1/patch/evals-user-templates-id PATCH https://api.bland.ai/v1/evals/user-templates/{id} Update a saved eval agent template. The source pointers cannot be changed. ### Headers Your API key for authentication. ### Path Parameters The UUID of the user template to update. ### Body Parameters Display name for the template. Maximum 120 characters. Description of the template. Maximum 4000 characters. Pass `null` to clear. Category label for the template. Maximum 64 characters. Pass `null` to clear. System prompt for the eval agent, in Markdown. Maximum 50000 characters. Evaluation prompt, in Markdown. Maximum 50000 characters. Ordered scoring levels. Each level object requires `level_key` (string, 1-64 chars), `label` (string, 1-80 chars), and `prompt_md` (string). The `color` field is optional: one of `rose`, `amber`, `gold`, `emerald`, `blue`, `indigo`, `violet`, or `fog`. Array of `level_key` strings that represent the passing threshold. Access scope for the template. One of `private`, `org`, or `public`. ### Response Unique identifier (UUID) for the template. UUID of the organization that owns this template. Short key used to reference the template. Display name of the template. Description of the template, or `null`. Category of the template, or `null`. Evaluation modality. Either `text` or `audio`. System prompt for the eval agent, in Markdown. Evaluation prompt, in Markdown. Ordered scoring levels. Short identifier for the level, 1-64 characters. Display label for the level, 1-80 characters. Prompt describing this level's criteria, in Markdown. Optional display color. One of `rose`, `amber`, `gold`, `emerald`, `blue`, `indigo`, `violet`, or `fog`. Array of `level_key` strings that represent the passing threshold. Access scope. One of `private`, `org`, or `public`. UUID of the eval agent this template was snapshotted from, or `null`. UUID of the specific version snapshotted, or `null`. UUID of the user who created the template, or `null`. ISO 8601 timestamp of when the template was created. ISO 8601 timestamp of when the template was last updated. ```json Response theme={null} { "data": { "id": "a1b2c3d4-5678-9abc-def0-1234567890ab", "org_id": "b2c3d4e5-6789-abcd-ef01-234567890abc", "key": "my_hallucination_check", "name": "My Hallucination Check (Updated)", "description": "Updated description for our product domain.", "category": "quality", "modality": "text", "system_prompt_md": "You are an expert evaluator assessing whether an AI agent fabricated information.", "prompt_md": "Review the conversation and identify any claims that were factually incorrect or unsupported.", "levels": [ { "level_key": "no_hallucination", "label": "No Hallucination", "prompt_md": "The agent made no factually incorrect or unsupported claims.", "color": "emerald" }, { "level_key": "minor_hallucination", "label": "Minor Hallucination", "prompt_md": "The agent made one or more small inaccuracies that did not materially mislead the user.", "color": "amber" }, { "level_key": "major_hallucination", "label": "Major Hallucination", "prompt_md": "The agent stated clearly false or fabricated information.", "color": "rose" } ], "target_level_keys": ["no_hallucination"], "visibility": "org", "source_agent_id": null, "source_version_id": null, "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-27T10:00:00.000Z", "updated_at": "2026-05-27T15:45:00.000Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Workbench Setup Source: https://docs.bland.ai/api-v1/patch/evals-workbench-setups-id PATCH https://api.bland.ai/v1/evals/workbench-setups/{setup_id} Update a workbench setup's metadata or repoint its active version. This endpoint updates setup-level fields only. To edit attached agents, the pass threshold, or run mode, update the setup's draft version using the Update Workbench Setup Version endpoint. ### Headers Your API key for authentication. ### Path Parameters The ID of the workbench setup to update. ### Body Parameters All fields are optional. Only include fields you want to update. Updated display name for the setup. Between 1 and 200 characters. Updated description, or `null` to clear it. Repoint the published version to a different archived version ID. Set to `null` to unpublish the setup. Key-value metadata to associate with the setup. Values must be strings. ### Response An object containing the updated setup and its current draft version. Unique identifier for the workbench setup. ID of the organization that owns this setup. Stable slug key for the setup. Display name of the setup. Description of the setup, or `null` if not set. ID of the current editable draft version. ID of the published version, or `null` if unpublished. Key-value metadata. Values are strings. ISO 8601 timestamp for when the setup was created. ISO 8601 timestamp for when the setup was last updated. ISO 8601 timestamp for when the setup was deleted, or `null` if not deleted. Unique identifier for this version. ID of the organization that owns this version. ID of the parent workbench setup. Monotonically increasing version number. Display name of this version. Description of this version, or `null` if not set. `"editable"` for a draft, `"archived"` for a published snapshot. Eval agents attached to this version. Each item contains `eval_agent_id`, `eval_agent_version_id`, `weight` (0-100), and `target_level_keys` (array of strings). Percentage of calls that must pass for a run to be considered passing (0-100), or `null` if not set. How calls are evaluated. One of `text`, `audio`, or `full`. ID of the default test configuration, or `null` if not set. Default call IDs to evaluate against. Up to 5000 entries. ID of the version this was forked from, or `null` if it is the first version. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. ISO 8601 timestamp for when this version was last updated. `null` on success. ```json Response theme={null} { "errors": null, "data": { "setup": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "org_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "key": "onboarding-quality-check", "name": "Onboarding Quality Check v2", "description": "Updated evaluation suite for Q2 onboarding calls.", "current_version_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "active_version_id": "d4e5f6a7-b8c9-0123-defa-234567890123", "metadata": { "team": "cx" }, "created_at": "2026-03-15T08:00:00.000Z", "updated_at": "2026-05-27T11:30:00.000Z", "deleted_at": null }, "current_version": { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "org_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "workbench_setup_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 4, "name": "Onboarding Quality Check v2", "description": "Updated evaluation suite for Q2 onboarding calls.", "state": "editable", "attached_agents": [ { "eval_agent_id": "e5f6a7b8-c9d0-1234-efab-345678901234", "eval_agent_version_id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "weight": 50, "target_level_keys": ["good", "excellent"] } ], "pass_threshold_pct": 80, "run_mode": "audio", "default_test_config_id": null, "default_call_ids": [], "created_from_version_id": "d4e5f6a7-b8c9-0123-defa-234567890123", "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-20T14:00:00.000Z", "updated_at": "2026-05-27T11:30:00.000Z" } } } ``` # Update Workbench Setup Version Source: https://docs.bland.ai/api-v1/patch/evals-workbench-setups-id-versions-id PATCH https://api.bland.ai/v1/evals/workbench-setups/{setup_id}/versions/{version_id} Edit a draft version's attached agents, threshold, run mode, or default calls. Only versions in the `editable` state can be updated. To make changes to a published (`archived`) version, fork a new draft from it first using the Create Workbench Setup Version endpoint. ### Headers Your API key for authentication. ### Path Parameters The ID of the workbench setup. The ID of the draft version to update. ### Body Parameters All fields are optional. Only include fields you want to update. Updated display name for the version. Between 1 and 200 characters. Updated description, or `null` to clear it. Replaces the full list of attached eval agents. Up to 20 agents. Each item requires: * `eval_agent_id` (string, required) - ID of the eval agent to attach. * `eval_agent_version_id` (string, required) - Version of the eval agent to use. * `weight` (number, required) - Relative weight for this agent in scoring (0-100). * `target_level_keys` (array of strings, required) - One or more target level keys this agent evaluates against. Percentage of calls that must pass for a run to be considered passing. Between 0 and 100, or `null` to clear. How calls are evaluated. One of `text`, `audio`, or `full`. ID of the default test configuration to use for runs, or `null` to clear. Default call IDs to evaluate against when no explicit call list is provided at run time. Replaces the existing list. Up to 5000 entries. ### Response The full updated version object. Unique identifier for this version. ID of the organization that owns this version. ID of the parent workbench setup. Monotonically increasing version number. Display name of this version. Description of this version, or `null` if not set. `"editable"` for a draft, `"archived"` for a published snapshot. Updated list of eval agents. Each item contains `eval_agent_id`, `eval_agent_version_id`, `weight` (0-100), and `target_level_keys` (array of strings). Updated pass threshold percentage (0-100), or `null` if not set. Updated run mode. One of `text`, `audio`, or `full`. Updated default test configuration ID, or `null` if not set. Updated default call IDs. Up to 5000 entries. ID of the version this was forked from, or `null` if it is the first version. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. ISO 8601 timestamp for when this version was last updated. `null` on success. ```json Response theme={null} { "errors": null, "data": { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "org_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "workbench_setup_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 4, "name": "Onboarding Quality Check", "description": "Updated to include empathy grading.", "state": "editable", "attached_agents": [ { "eval_agent_id": "e5f6a7b8-c9d0-1234-efab-345678901234", "eval_agent_version_id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "weight": 40, "target_level_keys": ["good", "excellent"] }, { "eval_agent_id": "a0b1c2d3-e4f5-6789-abcd-ef0123456789", "eval_agent_version_id": "b1c2d3e4-f5a6-7890-bcde-f01234567890", "weight": 60, "target_level_keys": ["acceptable", "good"] } ], "pass_threshold_pct": 80, "run_mode": "full", "default_test_config_id": null, "default_call_ids": [ "call_abc123", "call_def456", "call_ghi789" ], "created_from_version_id": "d4e5f6a7-b8c9-0123-defa-234567890123", "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-20T14:00:00.000Z", "updated_at": "2026-05-27T12:00:00.000Z" } } ``` # Update Guard Rail Source: https://docs.bland.ai/api-v1/patch/guard-rails-id PATCH https://api.bland.ai/v1/guard_rails/{guard_rail_id} Update an existing guard rail configuration. The `type` field cannot be changed after creation. To change the type, delete the guard rail and create a new one. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the guard rail to update. ### Body Parameters All fields are optional. Only include fields you want to update. Updated name for the guard rail (custom guard rails only). Updated description (custom guard rails only). Updated detection prompt (custom guard rails only). Updated configuration object. For TCPA time-based guard rails, set `end_seconds` to change the time window. Updated array of sources to attach this guard rail to. This replaces all existing attachments. Each attachment requires: * `source_type` (string) - Type of source: `PERSONA`, `PATHWAY`, or `INBOUND` * `source_id` (string) - ID of the source to attach to * `actions` (array) - Actions to take when the guard rail triggers ### Response The updated guard rail object containing `id`, `org_id`, `type`, `name`, `description`, `prompt`, `config`, `attachments`, `created_at`, and `updated_at`. Any errors that occurred (null if none). ```json Update config theme={null} { "config": { "end_seconds": 45 } } ``` ```json Update prompt theme={null} { "prompt": "Flag if the agent provides any medical advice, diagnosis, treatment recommendations, or medication suggestions" } ``` ```json Update attachments theme={null} { "attachments": [ { "source_type": "PERSONA", "source_id": "98765432-1234-1234-1234-123456789012", "actions": [ { "type": "end_call" } ] }, { "source_type": "PATHWAY", "source_id": "11111111-2222-3333-4444-555555555555", "actions": [ { "type": "transfer", "config": { "phone_number": "+15551234567" } } ] } ] } ``` ```json Response theme={null} { "data": { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "org_id": "12345678-1234-1234-1234-123456789012", "type": "tcpa:ai_disclosure", "name": null, "description": null, "prompt": null, "config": { "end_seconds": 45 }, "attachments": [ { "source_type": "PERSONA", "source_id": "98765432-1234-1234-1234-123456789012", "actions": [ { "type": "end_call" } ] } ], "created_at": "2025-01-15T10:30:00.000Z", "updated_at": "2025-01-16T14:20:00.000Z" }, "errors": null } ``` ```json Error Response (Cannot Update Type) theme={null} { "data": null, "errors": [ { "error": "INVALID_PARAMETER", "message": "Cannot update type of guard rail" } ] } ``` ```json Error Response (Not Found) theme={null} { "data": null, "errors": [ { "error": "NOT_FOUND", "message": "Guard rail not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Contact Facts Source: https://docs.bland.ai/api-v1/patch/memory-contact-id-facts PATCH https://api.bland.ai/v1/memory/contact/{memory_id}/facts Merge new facts into a contact's memory record. Existing keys are updated and new keys are added, but no keys are deleted. Facts are structured key-value pairs (e.g. name, plan, timezone) that persist across all conversations. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the contact memory record. ### Body Parameters Key-value pairs to merge with existing facts. New keys are added, existing keys are updated. ### Response The updated contact memory object. Unique identifier for the contact memory. The merged facts object. Error array (null on success). ### Facts Examples Facts can store any structured information about the contact: ```json theme={null} { "facts": { "name": "John Doe", "company": "Acme Corp", "role": "CTO", "preferred_contact": "phone", "timezone": "America/New_York", "plan": "premium", "account_number": "ACC-12345" } } ``` ```json Response theme={null} { "data": { "id": "mem-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "org_id": "11111111-2222-3333-4444-555555555555", "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "persona_id": "persona-12345678", "agent_number": null, "summary": "Customer is a premium plan subscriber.", "facts": { "name": "John Doe", "company": "Acme Corp", "role": "CTO", "preferred_contact": "phone", "timezone": "America/New_York" }, "recent_messages": [...], "created_at": "2025-07-20T10:30:00.000Z", "updated_at": "2025-07-22T16:00:00.000Z" }, "errors": null } ``` ```json Error Response theme={null} { "data": null, "errors": [ { "error": "BAD_REQUEST", "message": "facts is required" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Conversation Summary Source: https://docs.bland.ai/api-v1/patch/memory-contact-id-summary PATCH https://api.bland.ai/v1/memory/contact/{memory_id}/summary Overwrite the conversation summary for a contact memory. The summary is a plain-text overview of past interactions that the agent uses for context at the start of each conversation. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the contact memory record. ### Body Parameters The new summary text. This replaces the existing summary. ### Response The updated contact memory object. Unique identifier for the contact memory. The updated summary. ISO timestamp when the summary was last updated. Error array (null on success). ```json Response theme={null} { "data": { "id": "mem-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "org_id": "11111111-2222-3333-4444-555555555555", "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "persona_id": "persona-12345678", "agent_number": null, "summary": "Customer is a premium plan subscriber. Recently inquired about order #12345 which is in transit. Preferred contact method is phone. Located in EST timezone.", "summary_updated_at": "2025-07-22T16:00:00.000Z", "facts": { "name": "John Doe" }, "recent_messages": [...], "created_at": "2025-07-20T10:30:00.000Z", "updated_at": "2025-07-22T16:00:00.000Z" }, "errors": null } ``` ```json Error Response theme={null} { "data": null, "errors": [ { "error": "BAD_REQUEST", "message": "summary is required" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Organization Member Permissions Source: https://docs.bland.ai/api-v1/patch/org_member_permissions PATCH https://api.bland.ai/v1/orgs/{org_id}/members/permissions Modify the permissions of an existing member within an organization. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the organization. ### Body The action to perform on the member's permissions.\
Valid values: `"add"`, `"remove"`, `"reset"`, `"set"`
The user ID of the member whose permissions are being modified. A list of permissions to update.\
Valid values: `"owner"`, `"admin"`, `"operator"`, `"viewer"`
### Response Contains the updated permissions for the user. The updated list of permissions assigned to the user. Always `null` on success. ```json Response theme={null} { "data": { "newPermissions": ["viewer", "operator"] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Organization Members Source: https://docs.bland.ai/api-v1/patch/org_members PATCH https://api.bland.ai/v1/orgs/{org_id}/members Add or remove members from an organization. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the organization. ### Body The action to perform.\
Valid values: `"add"`, `"remove"`
Who to add or remove. Accepts an existing user ID, a phone number (E.164 format, e.g. `+14155550123`), or an email address.\
When you pass a phone number or email that doesn't match an existing user, an invitation is created. Phone number invitees receive an SMS, and email invitees receive a sign-up link. Invitees are automatically added to the organization when they sign up with the same phone number or email.
A list of permissions to assign when adding a member.\
Required only when `action` is `"add"`.\
Valid values: `"owner"`, `"admin"`, `"operator"`, `"viewer"`
Whether the removal applies to an invite instead of a full member.\
Required only when `action` is `"remove"`.
### Response Always `null` upon successful update. Always `null` on success. ```json Response theme={null} { "data": null, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Organization Properties Source: https://docs.bland.ai/api-v1/patch/org_properties PATCH https://api.bland.ai/v1/orgs/{org_id}/properties Modify specific properties of an organization. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the organization. ### Body An object containing the properties to update.\

**Valid keys:** * `"org_display_name"` (string) - The display name of the organization. Must be between **1 and 30 characters**. * `"preferences"` (object) - Preference settings for the organization: * `"use_bland_url"` (boolean) - Whether the organization prefers to use the Bland URL. * `"recording_lifespan_days"` (integer) - The lifespan of recordings in days. Must be between **1 and 1825** (inclusive) or `-1` to disable retention.
### Response The updated organization properties. The unique identifier of the organization. The unique slug identifier of the organization. The updated display name of the organization. URL of the organization's image (if set). The organization's plan. Default: `"starter"`. The timestamp of when the organization was created. The KYC (Know Your Customer) verification level. Default: `0`. The placement group of the organization. Default: `"blandshared"`. Whether the organization is deleted. Default: `false`. Whether the organization has overdue Stripe payments. Default: `false`. Whether the organization is suspended. Default: `false`. The organization's request rate limit. Default: `5`. The type of the organization. Default: `"normal"`. A list of entitlements granted to the organization. Default: `[]`. The updated preferences for the organization. Whether the organization prefers to use the Bland URL. Always `null` on success. ```json Response theme={null} { "data": { "id": "d122b4cf-1614-4124-aa28-15f81a09988f", "org_slug": "133906ea-d750-4a15-80fa-d6aef584dc58", "org_display_name": "Org Name", "org_image_url": null, "org_plan": "starter", "org_creation_date": "2025-02-14T06:46:09.818Z", "kyc_level": 0, "placement_group": "blandshared", "is_deleted": false, "is_stripe_overdue": false, "is_suspended": false, "org_rate_limit": 5, "org_type": "normal", "entitlements": [], "preferences": { "use_bland_url": false } }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Organization's Service Version Source: https://docs.bland.ai/api-v1/patch/org_version PATCH https://api.bland.ai/v1/orgs/{org_id}/versions/{service} Update the current version of a specified service for an organization. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the organization. The name of the service whose version you want to update.\
Valid values: `"api_server"`, `"ws_server"`
### Body The new version identifier to set for the specified service. ### Response Always `null` upon successful update. Always `null` on success. ```json Response theme={null} { "data": null, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Persona Source: https://docs.bland.ai/api-v1/patch/personas-id PATCH https://api.bland.ai/v1/personas/{persona_id} Update an existing persona configuration. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the persona to update. ### Body Parameters Updated display name for the persona. Updated role assigned to the persona. Updated description of the persona's purpose and use case. Updated array of tags to associate with the persona. Updated URL of the persona's profile image. Updated call configuration settings for the persona. Voice identifier to use for calls. Whether to record calls. Language code for the persona. Background audio setting. Maximum call duration in minutes. Whether to wait for greeting before starting. Interruption sensitivity threshold. Updated orchestration prompt for the persona. Updated personality and behavior prompt for the persona. Updated array of default tools enabled for the persona. Updated array of pathway routing conditions for the persona. Name of the pathway condition. Prompt that triggers this pathway condition. ID of the pathway to route to. Version of the pathway to use. Starting node ID within the pathway. Updated array of knowledge base IDs to connect to the persona. ### Response The updated persona object. Unique identifier for the persona. Display name of the persona. Role assigned to the persona. Description of the persona's purpose. Array of tags associated with the persona. URL of the persona's profile image (null if none). ISO 8601 timestamp of when the persona was created. ISO 8601 timestamp of when the persona was last modified. ISO 8601 timestamp of when the persona was deleted (null if active). ID of the user who owns this persona. ID of the current production version. ID of the current draft version. Array of inbound phone numbers using this persona. Complete production version object. Complete draft version object with updated configuration. Any errors that occurred (null if none). ```json Response theme={null} { "data": { "id": "12345678-1234-1234-1234-123456789012", "name": "Blandy", "role": null, "description": "Helpful Agent for Bland Documentation", "tags": [], "image_url": null, "created_at": "2025-09-23T15:13:36.348Z", "updated_at": "2025-09-23T15:43:49.257Z", "deleted_at": null, "user_id": "12345678-1234-1234-1234-123456789012", "current_production_version_id": "12345678-1234-1234-1234-123456789012", "current_draft_version_id": "12345678-1234-1234-1234-123456789012", "current_production_version": { "id": "12345678-1234-1234-1234-123456789012", "persona_id": "12345678-1234-1234-1234-123456789012", "version_type": "production", "version_number": 1, "orchestration_prompt": null, "personality_prompt": "You are a helpful assistant", "pathway_conditions": null, "kb_ids": [], "call_config": null, "default_tools": [], "promoted_from_version_id": null, "promoted_at": "2025-09-23T15:13:36.368Z", "promoted_by": null, "created_at": "2025-09-23T15:13:36.369Z", "updated_at": "2025-09-23T15:13:36.369Z" }, "current_draft_version": { "id": "12345678-1234-1234-1234-123456789012", "persona_id": "12345678-1234-1234-1234-123456789012", "version_type": "draft", "version_number": 2, "orchestration_prompt": null, "personality_prompt": "You are a helpful assistant", "pathway_conditions": null, "kb_ids": [], "call_config": null, "default_tools": [], "promoted_from_version_id": "12345678-1234-1234-1234-123456789012", "promoted_at": null, "promoted_by": null, "created_at": "2025-09-23T15:13:36.390Z", "updated_at": "2025-09-23T15:13:36.390Z" }, "inbound_numbers": [] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Persona Number Settings Source: https://docs.bland.ai/api-v1/patch/personas-id-inbound-phone-settings PATCH https://api.bland.ai/v1/personas/{persona_id}/inbound/{phone_number}/settings Update persona-specific settings for a phone number attached to a persona. Use this to configure per-number pathway overrides while still using the persona's base configuration. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the persona the phone number is attached to. The E.164 formatted phone number to update settings for. This number must currently be attached to the specified persona. ### Body Parameters Persona-specific settings for this phone number. Pass `null` to clear all per-number settings and fall back to the persona's defaults. Override the persona's default pathway with a specific pathway for calls/messages on this number. Specific version of the pathway to use. Specific node within the pathway to start from. ### Response The updated inbound number record. Internal ID of the inbound number record. The E.164 formatted phone number. The persona this number is attached to. The updated persona settings for this number, or `null` if cleared. ISO 8601 timestamp of when the record was last modified. `null` on success, or a list of error objects if the request failed. ```json Request (Set pathway override) theme={null} { "persona_settings": { "pathway_id": "pathway_abc123", "pathway_version": 2, "start_node_id": "node_xyz" } } ``` ```json Response (Success) theme={null} { "data": { "id": 42, "phone_number": "+14155551234", "persona_id": "12345678-1234-1234-1234-123456789012", "persona_settings": { "pathway_id": "pathway_abc123", "pathway_version": 2, "start_node_id": "node_xyz" }, "updated_at": "2025-09-23T16:00:00.000Z" }, "errors": null } ``` ```json Request (Clear settings) theme={null} { "persona_settings": null } ``` ```json Error Response (Number not attached to persona) theme={null} { "data": null, "errors": [ { "error": "INBOUND_NOT_FOUND", "message": "Inbound number not found or not attached to this persona" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Advanced Config Source: https://docs.bland.ai/api-v1/patch/sip-config PATCH https://api.bland.ai/v1/sip/config Update advanced SIP configuration including failover, codecs, and alerts. ### Headers Your API key for authentication. ### Body The phone number to update configuration for. Must be in E.164 format. The direction to update: `"inbound"` or `"outbound"`. Failover configuration: * `enabled` (boolean) — Enable/disable failover * `endpoints` (array) — Failover SIP servers, each with `host`, `port`, `transport`, and `priority` * `triggers` (array) — Conditions that trigger failover: `"unreachable"`, `"auth_failure"`, `"timeout"` * `failback` (string) — `"auto"` or `"manual"` Codec configuration: * `codecs` (array) — Ordered list of codec names: `"PCMU"`, `"PCMA"`, `"G.729"`, `"Opus"`, `"G.722"` * `transcode` (boolean) — Enable transcoding between codecs Alert configuration: * `enabled` (boolean) — Enable/disable alerts * `thresholds` — `unreachable_minutes` (number), `failure_rate_percent` (number), `failure_rate_window_minutes` (number), `response_time_ms` (number) * `channels` — `email` (boolean), `sms` (boolean), `webhook` (string, URL) ```json Example Request theme={null} curl -X PATCH https://api.bland.ai/v1/sip/config \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "phone_number": "+14150000000", "direction": "outbound", "failover_config": { "enabled": true, "endpoints": [ { "host": "backup1.sip.provider.com", "port": 5061, "transport": "tls", "priority": 1 }, { "host": "backup2.sip.provider.com", "port": 5061, "transport": "tls", "priority": 2 } ], "triggers": ["unreachable", "timeout"], "failback": "auto" }, "codec_config": { "codecs": ["PCMU", "PCMA", "Opus"], "transcode": true }, "alert_config": { "enabled": true, "thresholds": { "unreachable_minutes": 5, "failure_rate_percent": 20, "failure_rate_window_minutes": 30, "response_time_ms": 500 }, "channels": { "email": true, "sms": false, "webhook": "https://hooks.example.com/sip-alerts" } } }' ``` *** Docs for agents: [llms.txt](/llms.txt) # Update SMS Conversation Source: https://docs.bland.ai/api-v1/patch/sms-conversations-id PATCH https://api.bland.ai/v1/sms/conversations/{conversation_id} Updates properties of an existing SMS conversation. **Enterprise Feature** - This endpoint is available for enterprise customers only. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the SMS conversation to update. ### Body Parameters Sets the active status of the conversation. When set to `false`, the conversation will be marked as inactive. ### Response Confirmation message indicating the conversation was updated successfully. The updated conversation object containing the new values. The unique identifier of the conversation. The current active status of the conversation. ISO 8601 timestamp of when the conversation was last updated. ```json Success Response theme={null} { "message": "Conversation updated successfully", "conversation": { "id": "conv_1234567890", "is_active": false, "updated_at": "2024-01-15T10:30:00.000Z" } } ``` ```json 400 Error Response theme={null} { "data": null, "errors": [ { "message": "Conversation ID is required", "error": "CONVERSATION_ID_REQUIRED" } ] } ``` ```json 404 Error Response theme={null} { "data": null, "errors": [ { "message": "Conversation not found", "error": "CONVERSATION_NOT_FOUND" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Issue Source: https://docs.bland.ai/api-v1/patch/triage-issues-id PATCH https://api.bland.ai/v1/triage/issues/{id} Update a triage issue. All fields optional. ## Overview Partial update. Send only the fields you want to change. Pass `null` for `owner_id` or `assignee_id` to clear them. Returns the full updated issue. *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. *** ## Body Parameters Send any combination of the fields below. Sending an empty body is allowed but a no-op. New title. 1-200 characters. New description. Maximum 10,000 characters. New status. One of `backlog`, `todo`, `in_progress`, `in_review`, `done`, `closed`. New severity. One of `critical`, `high`, `medium`, `low`. New category. 1-64 characters. The category does not need to exist in the [Categories](/api-v1/get/triage-categories) catalog beforehand, freely-typed values are accepted. New owner. Pass a user ID to assign, or `null` to clear. New assignee. Pass a user ID to assign, or `null` to clear. *** ## Response The updated issue. See [Create Issue](/api-v1/post/triage-issues#response) for the full field list. `null` on success. Returns 404 if the issue does not exist or is not in your org. Returns 400 with `{ error: "bad_request" }` if any field fails validation, the message lists each invalid path. ```json Response theme={null} { "data": { "id": "b4f022b0-e47e-4c8e-b67c-b763db7b4ba4", "triage_id": "T-1042", "org_id": "f038cd1d-aa49-4127-ab2d-90c3fce669f3", "number": 1042, "title": "Agent skipped the verification step (confirmed)", "description": "On the Aug 12 demo flow the agent jumped to the closing node without asking for the email confirmation.", "status": "in_progress", "severity": "high", "source": "manual", "category": "Routing", "owner_id": null, "assignee_id": "d8dddfff-cc75-4e31-8056-cf3521e8055b", "author_id": "df480553-8bf8-4327-917d-402c33282a2e", "external_link": null, "created_at": "2026-05-04T18:24:11.482Z", "updated_at": "2026-05-07T02:29:25.744Z", "last_activity_at": "2026-05-07T02:29:25.744Z", "resource_count": 3, "flag_count": 1, "relation_count": 0, "latest_agent_session": null, "is_processing": false, "has_unread_activity": true }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Knowledge Base Source: https://docs.bland.ai/api-v1/patch/vectors-id PATCH https://api.bland.ai/v1/knowledgebases/{vector_id} Update a knowledge base. Usage: Pass the `vector_id` into your agent's `tools` to enable the agent to use the knowledge base. ```json theme={null} "tools": [ "KB-55e64dae-1585-4632-ae97-c909c288c6bc" ] ``` ### Headers Your API key for authentication. ### Path Parameters The `vector_id` of the knowledge base to update. ### Body The name of the knowledge base. Make this a clear name that describes the contents of the store. A description of the knowledge base. This can be a longer description of the contents of the knowledge base, or what terms to use to search for vectors in the knowledge base. This is visible to the AI, so making it descriptive can help the AI understand when to use it or not. The full text document to be stored and vectorized. ### Response The unique identifier for the knowledge base. Will start with "KB-". ```json theme={null} { "vector_id": "KB-55e64dae-1585-4632-ae97-c909c288c6bc" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Voice Config Source: https://docs.bland.ai/api-v1/patch/voices-id-config PATCH https://api.bland.ai/v1/voices/{id}/config Update default synthesis settings on a voice you own. ## Overview Updates the default consistency and expressiveness settings on a voice clone. These defaults are applied when [Speak](/api-v2/post/tts) is called without per-request overrides. Equivalent to [Update Voice Settings](/api-v1/post/voices-id-settings) (`POST /v1/voices/{id}/settings`). Both share the same write path; `POST /settings` is the canonical form and returns a lighter response envelope. This `PATCH /config` route is kept for backwards compatibility. The accepted parameters depend on the voice's engine: * **BTTS V1** voices accept `consistency` (0.0-1.0 float) and `expressiveness` (0.0-1.0 float). * **BTTS V2 / V3** voices accept `consistency` (1-32 integer, lower is more consistent) and `boost` (0 or 1). Only voices owned by your org can be configured. *** ## Headers Your API key for authentication. *** ## Path Parameters UUID of the voice to configure. *** ## Body Parameters Default consistency for this voice. Float 0.0-1.0 for V1 voices; integer 1-32 for V2/V3 voices (lower is more consistent). Default expressiveness for V1 voices only. Float 0.0-1.0. Expressiveness boost for V2 and V3 voices only. `0` or `1`. *** ## Response Returns the full updated voice. `success` on success. Human-readable confirmation, for example `"Voice configuration updated successfully"`. The updated voice. See [Get Voice](/api-v1/get/voices-id#response) for the full field list. ```json Response theme={null} { "status": "success", "message": "Voice configuration updated successfully", "voice": { "id": "73d4c04b-1e15-4272-9c7f-8d2955914ba9", "name": "DocTestRename", "description": null, "public": false, "ratings": 0, "tags": ["Beige Clone V2", "male"], "user_id": "fea2a74f-9bd7-4b5d-a52e-c3c1a3f58bb0", "voice_id": "ff595c98-da38-4617-ada3-df42561a2379", "service": "BTTS_V2", "finetuned": false, "consistency": 8, "expressiveness": null, "voice_meta": { "per_decode": 8 }, "is_creator_voice": false } } ``` *** Docs for agents: [llms.txt](/llms.txt) # Rename Voice Source: https://docs.bland.ai/api-v1/patch/voices-id-rename PATCH https://api.bland.ai/v1/voices/{id}/rename Change the display name of a cloned voice you own. ## Overview Renames a voice clone in your library. Only voices owned by your org can be renamed; default and shared-library voices return `403`. *** ## Headers Your API key for authentication. *** ## Path Parameters UUID of the voice to rename. *** ## Body Parameters New display name. 1-30 characters. Must be unique within your library. *** ## Response The updated display name. UUID of the renamed voice. `null` on success. ```json Response theme={null} { "data": { "name": "DocTestRename", "voice_id": "73d4c04b-1e15-4272-9c7f-8d2955914ba9" }, "errors": null } ``` ```json Name Taken theme={null} { "data": null, "errors": [ { "error": "Validation Error", "message": "Voice name is already taken" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Voice Sample Transcriptions Source: https://docs.bland.ai/api-v1/patch/voices-id-samples PATCH https://api.bland.ai/v1/voices/{id}/samples Update the transcription text on one or more training samples. ## Overview Updates the transcribed text for one or more samples on a voice clone you own. Useful when auto-transcription has errors that you want to correct before the voice is used. The samples themselves and their audio are not modified. *** ## Headers Your API key for authentication. *** ## Path Parameters UUID of the parent voice. *** ## Body Parameters Array of sample updates. Each entry must include `id` and `transcription`. ```json theme={null} { "samples": [ { "id": "d15b199a-1b79-4664-9a9a-b149ee3b136a", "transcription": "Hello and welcome to Bland." } ] } ``` *** ## Response `success` on success. The updated samples. See [List Voice Samples](/api-v1/get/voices-id-samples#response) for field shape. ```json Response theme={null} { "status": "success", "samples": [ { "id": "d15b199a-1b79-4664-9a9a-b149ee3b136a", "voice_id": "73d4c04b-1e15-4272-9c7f-8d2955914ba9", "transcription": "Hello and welcome to Bland.", "duration_seconds": 11.4, "created_at": "2026-06-22T21:34:31.347Z" } ] } ``` ```json Invalid Request theme={null} { "data": null, "errors": [ { "error": "INVALID_REQUEST", "message": "Missing or invalid samples array" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Custom Component Source: https://docs.bland.ai/api-v1/patch/widget-custom-components-id PATCH https://api.bland.ai/v1/widget/custom_components/{id} Retrieves a specific custom component by ID. ### Headers Your API key for authentication. ### Path Parameters UUID of the custom component to update. ### Body Widget identifier UUID to associate with the custom component. Pathway UUID to associate with the custom component. Pathway node ID to display the custom component on. Widget width dimension (e.g., "100%", "500px"). Widget height dimension (e.g., "300px", "100%"). Array of available agent variable names to pass into the custom component iframe URL as query params. URL for the iframe source. ### Response HTTP status code (200 for success). * `id` (string): Custom component UUID * `org_id` (string): Organization UUID * `widget_id` (string): Widget identifier UUID * `pathway_id` (string): Associated pathway UUID * `pathway_node` (string): Pathway node ID to display the custom component on * `width` (string): Widget width dimension * `height` (string): Widget height dimension * `variables` (string\[]): Array of variable names to pass into the custom component iframe URL as query params * `iframe_url` (string): URL for the iframe source * `created_at` (string): ISO timestamp * `updated_at` (string): ISO timestamp Always null on successful response. ```json Response theme={null} { "data": [ { "created_at": "2025-10-02T21:45:27.633Z", "updated_at": "2025-10-02T21:45:27.633Z", "id": "70b56282-8db5-4e26-aad9-098c099fb1db", "org_id": "99a0d526-6910-4f31-92b8-72834d0827fb", "widget_id": "7d1a8c0d-5346-4f96-9f5c-d888e273eaf0", "pathway_id": "05f4b269-e79a-4825-b4cd-7778f782bfad", "pathway_node": "1", "width": "100%", "height": "300px", "variables": [ "firstName" ], "iframe_url": "https://widget-custom-components.vercel.app" } ], "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Widget Source: https://docs.bland.ai/api-v1/patch/widget-id PATCH https://api.bland.ai/v1/widget/{id} Updates an existing widget. All fields in the request body are optional. ### Headers Your API key for authentication. ### Path Parameters UUID of the widget to update. ### Body New pathway UUID to associate with the widget. Must be defined if `agent_prompt` is null. New pathway UUID to associate with the widget. Must be defined if `pathway_id` is null. New array of allowed domains where the widget can be embedded. New rate limit for messages (minimum: 0). New widget configuration object (flexible JSON). Supports `timeoutSeconds` to configure conversation timeout (default: 86400 seconds / 24 hours). New agent UUID to associate with the widget. New URL to receive post-conversation webhook payloads when conversations end. See [Post-Conversation Webhooks](/tutorials/chat-widget#post-conversation-webhooks) for payload details. ### Response HTTP status code (200 for success). The updated widget object containing: * `id` (string): Widget UUID * `pathway_id` (string): Associated pathway UUID * `agent_id` (string | null): Associated agent UUID or null * `allowed_domains` (string\[]): Array of allowed domains * `messages_per_minute` (number): Rate limit for messages * `config` (object): Widget configuration object * `webhook_url` (string | null): Post-conversation webhook URL or null * `created_at` (string): ISO timestamp * `updated_at` (string): Updated ISO timestamp Always null on successful response. ```json Response theme={null} { "status": 200, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "pathway_id": "a0f0d4ed-f5f5-4f16-b3f9-22166594d7a7", "agent_id": "46f37229-7d12-44be-b343-6e68274cfbea", "allowed_domains": ["newdomain.com", "anotherdomain.com"], "messages_per_minute": 15, "config": { "theme": "dark", "position": "bottom-left", "greeting": "Hi there! What can I do for you?", "timeoutSeconds": 7200 }, "webhook_url": "https://example.com/conversation-webhook", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T14:22:30Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Encrypted Key Source: https://docs.bland.ai/api-v1/post/accounts POST https://api.bland.ai/v1/accounts Integrate your own Twilio account with Bland. See [Custom Twilio Integration](/tutorials/custom-twilio) for more information. ### Headers Your API key for authentication. ### Body Your Twilio account SID. Your Twilio auth token. ### Response Your `encrypted_key` to store and use in future requests. ```json theme={null} { "status": "success", "encrypted_key": "YOUR_ENCRYPTED_KEY" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Encrypted Key Source: https://docs.bland.ai/api-v1/post/accounts-delete POST https://api.bland.ai/v1/accounts/delete Disable an encrypted key for a Twilio account integration. See [Custom Twilio Integration](/tutorials/custom-twilio) for more information. ### Headers Your API key for authentication. The `encrypted_key` to delete. Learn more about BYOT [here](/tutorials/custom-twilio). ### Response The status of the request. * `success` - The encrypted key was successfully deleted. * `error` - There was an error deleting the encrypted key. Special messages: * `Error deleting Twilio credentials` - The encrypted key could not be deleted or already has been deleted. * `Missing encrypted key` - The `encrypted_key` parameter is missing. * none - The encrypted key was successfully deleted. ```json theme={null} { "status": "success" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Batch Run Scenarios Source: https://docs.bland.ai/api-v1/post/agent-testing-batch-run POST https://api.bland.ai/v1/agent-testing/batch-run Execute multiple test scenarios as a batch. Returns immediately with a batch ID while tests execute asynchronously. ### Headers Your API key for authentication. ### Body Array of scenario IDs to run. All scenario IDs must belong to your organization. Pathway version to test. Defaults to the current production version. URL to receive a webhook when the entire batch completes. The webhook payload will include the batch result summary. ### Response The unique identifier for the test batch. An array of run entries, one per scenario. Each entry contains: * `run_id` - The unique identifier for the individual test run. * `scenario_id` - The scenario ID associated with this run. ```json Response theme={null} { "batch_id": "e7a2c3d4-8f9b-4a1e-b5c6-d7e8f9a0b1c2", "runs": [ { "run_id": "a3f1b2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c", "scenario_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" }, { "run_id": "b4c2d3e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e", "scenario_id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e" } ] } ``` This endpoint is rate limited per organization. All `scenario_ids` must belong to your organization or the request will be rejected. *** Docs for agents: [llms.txt](/llms.txt) # Analyze Failed Run Source: https://docs.bland.ai/api-v1/post/agent-testing-runs-analyze POST https://api.bland.ai/v1/agent-testing/runs/{id}/analyze Run AI-powered analysis on a failed test run to get root cause and fix suggestions. ### Headers Your API key for authentication. ### Path Parameters The run ID to analyze. ### Response The AI-generated analysis of the failed test run. Description of why the test failed. An array of suggested fixes for the failure. The type of suggested change. One of: `prompt_change`, `node_config`, `flow_change`, `tone_improvement`. The ID of the node the suggestion applies to. The display name of the node the suggestion applies to. A human-readable description of the issue and what should change. The specific change to make (e.g., updated prompt text or configuration value). Confidence score for this suggestion, from 0 to 1. A map of node IDs to their display names, covering all nodes referenced in the analysis. ```json Response theme={null} { "analysis": { "root_cause": "The agent failed to transfer the caller to a live representative when the caller explicitly requested to speak with a manager. The 'Escalation Handler' node's prompt does not include instructions for handling direct manager requests, causing the agent to loop back to the main menu instead.", "suggestions": [ { "type": "prompt_change", "target_node_id": "node_8f3a2b1c", "target_node_name": "Escalation Handler", "description": "The escalation node's prompt does not account for explicit manager requests. Adding a condition to detect phrases like 'speak to a manager' or 'talk to someone' would allow the agent to route correctly.", "suggested_change": "Add the following to the node prompt: 'If the caller asks to speak with a manager, supervisor, or live person, immediately transfer them to the manager queue without further qualification.'", "confidence": 0.92 }, { "type": "flow_change", "target_node_id": "node_4d7e9f0a", "target_node_name": "Main Menu", "description": "The Main Menu node has a fallback edge that loops back to itself when no intent is matched. This creates an infinite loop when the escalation path fails to trigger.", "suggested_change": "Add a new edge from 'Main Menu' to 'Escalation Handler' that triggers when the caller's intent is classified as 'escalation' or 'transfer_request'.", "confidence": 0.78 } ], "node_id_to_name": { "node_8f3a2b1c": "Escalation Handler", "node_4d7e9f0a": "Main Menu", "node_1a2b3c4d": "Greeting", "node_5e6f7a8b": "Transfer to Manager" } } } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Test Scenario Source: https://docs.bland.ai/api-v1/post/agent-testing-scenarios POST https://api.bland.ai/v1/agent-testing/scenarios Create a new test scenario with assertions for a pathway or persona. ### Headers Your API key for authentication. ### Body Parameters The pathway to test. Either `pathway_id` or `persona_id` is required. The persona to test. Either `pathway_id` or `persona_id` is required. Name of the scenario. Must be unique within the pathway/persona. Description of what the scenario tests. One of: `CUSTOM`, `VOICEMAIL`, `VOICEMAIL_SCREENER`, `ANGRY_CALLER`, `BELLIGERENT_CALLER`, `CONFUSED_CALLER`, `CALL_SCREENER`, `HAPPY_PATH`, `EDGE_CASE`. One of: `AGENT`, `REPLAY`, `HISTORICAL`. Prompt instructing the simulated caller how to behave. Display name for the tester persona. Max conversation turns before the test ends. Maximum value is 50. Custom request data to pass to the pathway (e.g., variables). ID of the pathway node where the simulated conversation should begin. Use this to test a specific branch of a pathway without rewiring the flow. When omitted (or `null`), the test runs from the pathway's default start node. If the ID does not match a node in the current pathway version, the run fails with an `Invalid start_node_id` error. Enable Bland Tone naturalness scoring. If true, this scenario must pass before the pathway can be promoted to production. Pre-seeded messages for `REPLAY` scenarios. Additional instructions for test execution. Arbitrary metadata to attach to the scenario. Array of assertion definitions. The assertion type. One of: `LLM_JUDGE`, `BLAND_TONE`, `VARIABLE_EXTRACTED`, `NODE_REACHED`, `NODES_VISITED`, `WEBHOOK_TRIGGERED`, `REGEX_MATCH`, `STRING_CHECK`, `CUSTOM_LLM`, `TRAVERSAL_MATCH`. Type-specific configuration for the assertion. Display name for the assertion. Whether this assertion must pass for the scenario to pass. Weight of this assertion in the overall score. Order in which the assertion is evaluated. ### Response Unique identifier for the created scenario. Organization ID that owns this scenario. The pathway ID being tested (null if testing a persona). The persona ID being tested (null if testing a pathway). Name of the scenario. Description of the scenario. Scenario category. Type of scenario. Prompt for the simulated caller. Display name for the tester persona. Maximum conversation turns. Custom request data. Starting node ID. Whether Bland Tone scoring is enabled. Whether this scenario is required for promotion. Whether the scenario is enabled. Pre-seeded messages for replay scenarios. Additional instructions for test execution. Arbitrary metadata. Array of assertion objects. Unique identifier for the assertion. The assertion type. Display name for the assertion. Type-specific configuration. Whether this assertion must pass. Weight of this assertion in the overall score. Evaluation order. ISO 8601 timestamp of when the scenario was created. ```json Response theme={null} { "id": "a1b2c3d4-5678-9abc-def0-1234567890ab", "org_id": "b2c3d4e5-6789-abcd-ef01-234567890abc", "pathway_id": "c3d4e5f6-789a-bcde-f012-34567890abcd", "persona_id": null, "name": "Angry Caller Test", "description": "Tests the agent's ability to de-escalate an angry caller", "category": "ANGRY_CALLER", "scenario_type": "AGENT", "tester_persona_prompt": "You are a frustrated customer who has been waiting on hold for 30 minutes. You are upset about a billing error on your account.", "tester_persona_name": "Frustrated Customer", "max_turns": 15, "request_data": null, "start_node_id": null, "bland_tone_enabled": true, "is_required_for_promotion": false, "enabled": true, "input_messages": null, "advanced_instructions": null, "metadata": null, "assertions": [ { "id": "d4e5f6a7-89ab-cdef-0123-4567890abcde", "type": "LLM_JUDGE", "name": "De-escalation", "config": { "prompt": "Did the agent successfully de-escalate the situation and address the customer's concerns?", "output_type": "score", "threshold": 0.7 }, "is_required": true, "weight": 1.5, "order": 0 } ], "created_at": "2026-04-14T00:00:00.000Z" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Generate Scenario from Call Source: https://docs.bland.ai/api-v1/post/agent-testing-scenarios-generate POST https://api.bland.ai/v1/agent-testing/scenarios/generate-from-call Generate a test scenario from a historical call transcript using AI analysis. ### Headers Your API key for authentication. ### Body The ID of the historical call to generate a scenario from. The call transcript will be analyzed by AI to extract a realistic test scenario. The pathway to bind the generated scenario to. Either `pathway_id` or `persona_id` is required. The persona to bind the generated scenario to. Either `pathway_id` or `persona_id` is required. ### Response The response contains the generated scenario data. This data is **not yet saved** -- it is returned so you can review and use it to create a scenario. Sensitive data such as phone numbers, webhook URLs, and API keys is automatically stripped from the generated `request_data`. An AI-generated name summarizing the scenario. An AI-generated description of what the scenario tests based on the call transcript. The inferred category for the scenario (e.g., `HAPPY_PATH`, `EDGE_CASE`, `ANGRY_CALLER`). An AI-generated prompt that instructs the simulated caller to replicate the behavior observed in the original call. A name for the simulated caller persona derived from the call. The pathway the scenario is bound to (if provided). The persona the scenario is bound to (if provided). Request data extracted from the call with sensitive fields automatically removed. ```json Response theme={null} { "name": "Inbound Appointment Booking - Returning Customer", "description": "Simulates a returning customer calling to book a follow-up appointment. The caller provides their name and preferred time slot, and expects confirmation.", "category": "HAPPY_PATH", "tester_persona_prompt": "You are Sarah Chen, a returning customer. You previously visited for a consultation and want to book a follow-up appointment. You prefer afternoons, ideally next Thursday at 2 PM. Be polite but firm about your preferred time. If that slot is unavailable, accept an alternative within the same week.", "tester_persona_name": "Sarah Chen", "pathway_id": "pw_abc123", "persona_id": null, "request_data": { "customer_name": "Sarah Chen", "account_id": "cust_92841", "appointment_type": "follow_up" } } ``` *** Docs for agents: [llms.txt](/llms.txt) # Run Test Scenario Source: https://docs.bland.ai/api-v1/post/agent-testing-scenarios-run POST https://api.bland.ai/v1/agent-testing/scenarios/{id}/run Execute a single test scenario. Returns immediately with a run ID while the test executes asynchronously. ### Headers Your API key for authentication. ### Path Parameters The scenario ID to run. ### Body Pathway version to test. Defaults to the current production version. Override the scenario's `request_data` for this run. Any keys provided here will replace the corresponding keys in the scenario's default request data. URL to receive a webhook when the run completes. The webhook payload will include the full run result. ### Response The unique identifier for the test run. The current status of the run. Will be `RUNNING` immediately after creation. ```json Response theme={null} { "run_id": "a3f1b2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c", "status": "RUNNING" } ``` This endpoint is rate limited per organization. If you need to run multiple scenarios at once, consider using the [Batch Run](/api-v1/post/agent-testing-batch-run) endpoint instead. *** Docs for agents: [llms.txt](/llms.txt) # Create Simulation Set Source: https://docs.bland.ai/api-v1/post/agent-testing-simulation-sets POST https://api.bland.ai/v1/agent-testing/simulation-sets Create a simulation set that runs each scenario multiple times to detect flaky behavior. Returns immediately while simulations execute asynchronously. ### Headers Your API key for authentication. ### Body Scenario IDs to include. All scenario IDs must belong to your organization. Number of times to run each scenario. Must be >= 1. The pathway ID. The persona ID. Pathway version to test. This endpoint is rate limited. All `scenario_ids` must belong to your organization. ### Response The unique identifier for the newly created simulation set. The initial status of the simulation set. Will be `PENDING` upon creation. The number of simulations that will be run per scenario. The total number of scenarios included in this set. ISO 8601 timestamp of when the simulation set was created. ```json Response theme={null} { "simulation_set_id": "d4e5f6a7-89ab-cdef-0123-4567890abcde", "status": "PENDING", "simulations_per_scenario": 5, "total_scenarios": 3, "created_at": "2026-04-14T10:00:00.000Z" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Clone Test Template Source: https://docs.bland.ai/api-v1/post/agent-testing-templates-clone POST https://api.bland.ai/v1/agent-testing/templates/{id}/clone Clone a template to create a new scenario bound to your pathway or persona. ### Headers Your API key for authentication. ### Path Parameters The template ID to clone. ### Body The pathway to bind the cloned scenario to. Either `pathway_id` or `persona_id` is required. The persona to bind the cloned scenario to. Either `pathway_id` or `persona_id` is required. Override the template name. Defaults to the template's original name. Override the template description. Override the tester persona prompt that drives the simulated caller's behavior. Override the maximum number of conversational turns before the test ends. Override the request data passed to the agent during the test call. Override the starting node for pathway-based scenarios. Override the Bland Tone setting for the test call. Whether to require this scenario to pass before a pathway can be promoted. Default `false`. ### Response The newly created scenario object cloned from the template. * `id` (string): The unique identifier for the new scenario. * `name` (string): The scenario name. * `description` (string): The scenario description. * `category` (string): The category inherited from the template. * `tester_persona_prompt` (string): The prompt driving the simulated caller. * `tester_persona_name` (string): The name of the simulated caller persona. * `pathway_id` (string): The pathway this scenario is bound to (if applicable). * `persona_id` (string): The persona this scenario is bound to (if applicable). * `max_turns` (integer): The maximum number of conversational turns. * `request_data` (object): The request data for the test call. * `start_node_id` (string): The starting node ID (if set). * `bland_tone_enabled` (boolean): Whether Bland Tone is enabled. * `is_required_for_promotion` (boolean): Whether this scenario is required for pathway promotion. * `assertions` (array): The assertion objects inherited from the template. * `type` (string): The assertion type. * `config` (object): Configuration specific to the assertion type. * `description` (string): A human-readable description of the assertion. * `created_at` (string): ISO 8601 timestamp of when the scenario was created. ```json Response theme={null} { "scenario": { "id": "scn_8f2a1b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "name": "Voicemail Detection", "description": "Simulates a voicemail greeting to verify the agent correctly detects and handles voicemail.", "category": "VOICEMAIL", "tester_persona_prompt": "You are a voicemail system. Greet the caller with a standard voicemail message: 'Hi, you've reached John. I'm not available right now. Please leave a message after the beep.' Then remain silent.", "tester_persona_name": "Voicemail System", "pathway_id": "pw_abc123", "persona_id": null, "max_turns": 4, "request_data": {}, "start_node_id": null, "bland_tone_enabled": true, "is_required_for_promotion": false, "assertions": [ { "type": "call_ended_by_agent", "config": {}, "description": "Agent should hang up after detecting voicemail" }, { "type": "latency_below", "config": { "max_ms": 3000 }, "description": "Agent response latency stays below 3 seconds" } ], "created_at": "2026-04-14T18:30:00.000Z" } } ``` *** Docs for agents: [llms.txt](/llms.txt) # Cancel Tornado Session Source: https://docs.bland.ai/api-v1/post/agent-testing-tornado-cancel POST https://api.bland.ai/v1/agent-testing/tornado/{id}/cancel Cancel a running tornado session. ### Headers Your API key for authentication. ### Path Parameters The tornado session ID. ### Response Whether the session was successfully cancelled. ```json Response theme={null} { "cancelled": true } ``` *** Docs for agents: [llms.txt](/llms.txt) # Start Tornado Session Source: https://docs.bland.ai/api-v1/post/agent-testing-tornado-start POST https://api.bland.ai/v1/agent-testing/tornado/start Start an iterative fix loop that runs tests, analyzes failures, applies fixes, and retests until all scenarios pass. Returns immediately while the loop executes asynchronously. ### Headers Your API key for authentication. ### Body The pathway to fix. The persona ID. Specific scenarios to test. If omitted, runs all enabled scenarios for the pathway. Maximum 50 scenarios. Pathway version to start from. Maximum fix iterations. Default `5`. Timeout in milliseconds. Default `900000` (15 minutes). Only one tornado session can be active per pathway. Returns `409 Conflict` if a session is already running. ### Response The unique identifier for the tornado session. The initial status of the session. Will be `RUNNING` upon creation. The pathway being tested and fixed. The maximum number of fix iterations configured. The timeout configured for this session in milliseconds. ISO 8601 timestamp of when the session was created. ```json Response theme={null} { "session_id": "e1f2a3b4-5678-9cde-f012-3456789abcde", "status": "RUNNING", "pathway_id": "c3d4e5f6-789a-bcde-f012-34567890abcd", "max_iterations": 5, "timeout_ms": 900000, "created_at": "2026-04-14T10:15:00.000Z" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create a Web Agent Source: https://docs.bland.ai/api-v1/post/agents POST https://api.bland.ai/v1/agents Configure all of the settings for a new web agent. ### Headers Your API key for authentication. Example web call usage (client side): ```javascript theme={null} import { BlandWebClient } from 'bland-client-js-sdk'; const agentId = 'YOUR-AGENT-ID'; const sessionToken = 'YOUR-SESSION-TOKEN'; document.addEventListener('DOMContentLoaded', async () => { document.getElementById('btn').addEventListener('click', async () => { const blandClient = new BlandWebClient( agentId, sessionToken ); await blandClient.initConversation({ sampleRate: 44100, }); }); }); ``` ### Body Provide instructions, relevant information, and examples of the ideal conversation flow. #### Out-of-the-Box Behaviors (Summarized): * Speech pattern: Direct, concise, casual * Spells out symbols, acronyms, abbreviations, percentages, etc. (\$4,000,000 -> "four million dollars") * Asks clarifying questions * Ends call when objective is complete or voicemail is detected #### Prompting Tips: * Want to easily test out exactly how your agent will behave? * [Try out Agent Testing!](https://app.bland.ai/home?page=testing) * Aim for less than >2,000 characters where possible. * Simple, direct prompts are the most predictable and reliable. * Frame instructions positively: * `"Do this"` rather than `"Don't do this"`. * Ex. "Keep the conversation casual" rather than "Don't be too formal". * This gives concrete examples of what to do, instead of leaving expected behavior open to interpretation. Set your agent's voice - all available voices can be found with the [List Voices](/api-v1/get/voices) endpoint. Set a webhook URL to receive call data after the web call completes. Add any additional information you want to associate with the call. This can be useful for tracking or categorizing calls. Set the pathway that your agent will follow. This will override the `prompt` field, so there is no need to pass the 'prompt' field if you are setting a pathway. Warning: Setting a pathway will set the following fields to `null` / their default value - `prompt`, `first_sentence`, `model`, `dynamic_data`, `tools`, `transfer_list` Set to `null` or an empty string to clear the pathway. Select a supported language of your choice. Optimizes every part of our API for that language - transcription, speech, and other inner workings. Supported Languages and their codes can be found [here](/api-v1/post/calls#param-language). Select a model to use for your call. Options: `base` or `turbo`. In nearly all cases, `base` is the best choice for now. There are two different ways to use Bland: * `model: base` * The original, follows scripts/procedures most effectively. * Supports all features and capabilities. * Best for Custom Tools * `model: turbo` * The absolute fastest latency possible, can be verbose at times * Limited capabilities currently (excludes Transferring, IVR navigation, Custom Tools) * Extremely realistic conversation capabilities A phrase that your call will start with instead of a generating one on the fly. This works both with and without `wait_for_greeting`. Can be more than one sentence, but must be less than 200 characters. To remove, set to `null` or an empty string. Interact with the real world through API calls. Detailed tutorial here: [Custom Tools](/tutorials/custom-tools) Integrate data from external APIs into your agent's knowledge. Set to `null` or an empty string to clear dynamic data settings. Detailed usage in the [Send Call](/api-v1/post/calls) endpoint. Adjusts how patient the AI is when waiting for the user to finish speaking. Lower values mean the AI will respond more quickly, while higher values mean the AI will wait longer before responding. Recommended range: 50-200 * 50: Extremely quick, back and forth conversation * 100: Balanced to respond at a natural pace * 200: Very patient, allows for long pauses and interruptions. Ideal for collecting detailed information. Try to start with 100 and make small adjustments in increments of \~10 as needed for your use case. These words will be boosted in the transcription engine - recommended for proper nouns or words that are frequently mis-transcribed. For example, if the word "Reece" is frequently transcribed as a homonym like "Reese" you could do this: ```json theme={null} { "keywords": ["Reece"] } ``` For stronger keyword boosts, you can place a colon then a boost factor after the word. The default boost factor is 2. ```json theme={null} { "keywords": ["Reece:3"] } ``` The maximum duration that calls to your agent can last before being automatically terminated. Set to `null` to reset to default. ### Response Can be `success` or `error`. A unique identifier for the call (present only if status is `success`). ```json Response theme={null} { "agent": { "agent_id": "2c565dc7-f41f-43db-a99f-e4c8ba9d7d18", "dynamic_data": null, "interruption_threshold": null, "first_sentence": null, "model": "base", "voice_settings": null, "voice": "maya", "prompt": "...", "temperature": null, "max_duration": 30, "language": "ENG", "tools": null } } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Web Agent Settings Source: https://docs.bland.ai/api-v1/post/agents-id POST https://api.bland.ai/v1/agents/{agent_id} Update your web agent's settings, prompt and other details. ### Headers Your API key for authentication. ### Path Parameters The web agent you'll be updating. ### Body Provide instructions, relevant information, and examples of the ideal conversation flow. #### Out-of-the-Box Behaviors (Summarized): * Speech pattern: Direct, concise, casual * Spells out symbols, acronyms, abbreviations, percentages, etc. (\$4,000,000 -> "four million dollars") * Asks clarifying questions #### Prompting Tips: * Want to easily test out exactly how your agent will behave? * [Try out Agent Testing!](https://app.bland.ai/home?page=testing) * Aim for less than >2,000 characters where possible. * Simple, direct prompts are the most predictable and reliable. * Frame instructions positively: * `"Do this"` rather than `"Don't do this"`. * Ex. "Keep the conversation casual" rather than "Don't be too formal". * This gives concrete examples of what to do, instead of leaving expected behavior open to interpretation. Set your agent's voice - all available voices can be found with the [List Voices](/api-v1/get/voices) endpoint. Set a webhook URL to receive call data after the web call completes. Add any additional information you want to associate with the call. This can be useful for tracking or categorizing calls. Set the pathway that your agent will follow. This will override the `prompt` field, so there is no need to pass the 'prompt' field if you are setting a pathway. Warning: Setting a pathway will set the following fields to `null` / their default value - `prompt`, `first_sentence`, `model`, `dynamic_data`, `tools`, `transfer_list` Set to `null` or an empty string to clear the pathway. Select a supported language of your choice. Optimizes every part of our API for that language - transcription, speech, and other inner workings. Supported Languages and their codes can be found [here](/api-v1/post/calls#param-language). The webhook should be a http / https callback url. We will send the call\_id and transcript to this URL after the call completes. This can be useful if you want to have real time notifications when calls finish. Set to `null` or an empty string to clear the webhook. Select a model to use for your call. Options: `base` or `turbo`. In nearly all cases, `base` is the best choice for now. There are two different ways to use Bland: * `model: base` * The original, follows scripts/procedures most effectively. * Supports all features and capabilities. * Best for Custom Tools * `model: turbo` * The absolute fastest latency possible, can be verbose at times * Limited capabilities currently (excludes Transferring, IVR navigation, Custom Tools) * Extremely realistic conversation capabilities A phrase that your call will start with instead of a generating one on the fly. This works both with and without `wait_for_greeting`. Can be more than one sentence, but must be less than 200 characters. To remove, set to `null` or an empty string. Interact with the real world through API calls. Detailed tutorial here: [Custom Tools](/tutorials/custom-tools) Integrate data from external APIs into your agent's knowledge. Set to `null` or an empty string to clear dynamic data settings. Detailed usage in the [Send Call](/api-v1/post/calls) endpoint. Adjusts how patient the AI is when waiting for the user to finish speaking. Lower values mean the AI will respond more quickly, while higher values mean the AI will wait longer before responding. Recommended range: 50-200 * 50: Extremely quick, back and forth conversation * 100: Balanced to respond at a natural pace * 200: Very patient, allows for long pauses and interruptions. Ideal for collecting detailed information. Try to start with 100 and make small adjustments in increments of \~10 as needed for your use case. The maximum duration that calls to your agent can last before being automatically terminated. Set to `null` to reset to default. ### Response Whether the update was successful or not - will be `success` or `error`. A message describing the status of the update. An object containing the updated settings for the agent. If the update was unsuccessful, this will contain the settings that failed to update. Useful to determine how your request is being interpreted on our end. ```json Response theme={null} { "status": "success", "message": "Successfully updated agent 46f37229-7d12-44be-b343-6e68274cfbea.", "updates": { "model": "base" } } ``` *** Docs for agents: [llms.txt](/llms.txt) # Authorize a Web Agent Call Source: https://docs.bland.ai/api-v1/post/agents-id-authorize POST https://api.bland.ai/v1/agents/{agent_id}/authorize Create a single-use session token for a client to talk with your web agent. ### Headers Your API key for authentication. Example web call usage (client side): ```javascript theme={null} import { BlandWebClient } from 'bland-client-js-sdk'; const agentId = 'YOUR-AGENT-ID'; const sessionToken = 'YOUR-SESSION-TOKEN'; document.addEventListener('DOMContentLoaded', async () => { document.getElementById('btn').addEventListener('click', async () => { const blandClient = new BlandWebClient( agentId, sessionToken ); await blandClient.initConversation({ sampleRate: 44100, }); }); }); ``` ### Path The web agent to authorize a call for. Special note: While in Beta, this request must be made to the `api.bland.ai` domain. ### Body Variables to be passed to this session. Example: ```json theme={null} { "name": "John Doe" } ``` ### Response The single-use session token that can be sent to the client. Can be `success` or `error`. A message saying whether the token creation succeeded, or a helpful message describing why it failed. ```json theme={null} { "token": "22480c52-0ff1-4214-bcb7-50649b508432" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Web Agent Source: https://docs.bland.ai/api-v1/post/agents-id-delete POST https://api.bland.ai/v1/agents/{agent_id}/delete Delete a web agent. ### Headers Your API key for authentication. ### Path The web agent to delete. ### Response Can be `success` or `error`. A message saying whether the deletion succeeded, or a helpful message describing why it failed. ```json theme={null} { "status": "success", "message": "Successfully deleted agent 2c565dc7-f41f-43db-a99f-e4c8ba9d7d18" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Alarm Source: https://docs.bland.ai/api-v1/post/alarms POST https://api.bland.ai/v1/alarms Create an alarm configuration for your organization. ### Headers Your API key for authentication. ### Body Parameters Metric to monitor. Allowed values: `latency`, `api_errors`, `call_length`. Positive numeric threshold used for alarm trigger evaluation. Notes: * `threshold` is a sensitivity scalar (higher values are less sensitive; lower values are more sensitive). * The Dashboard may display an approximate "% change" visualization for this value. Treat that UI percentage as a directional aid, not an exact conversion. Dashboard sensitivity presets map to these threshold values: * `Sensitive` → `0.5` * `Normal` → `1.0` * `Relaxed` → `2.0` * `Critical` → `2.5` Optional webhook destination for alarm notifications. `webhook_config` should be a JSON object with: * `url` (string, required) * `headers` (object, optional) Example: ```json theme={null} { "webhook_config": { "url": "https://example.com/webhooks/alarms", "headers": { "Content-Type": "application/json", "Authorization": "Bearer test-token" } } } ``` Optional email recipients for notifications. Optional SMS recipients for notifications. ### Response Created alarm configuration object. Alarm configuration ID. Metric tracked by this alarm. Configured trigger threshold. Whether this alarm is enabled. `null` on success, otherwise an array of error objects. ```json Success theme={null} { "data": { "alarm": { "id": "c92e5e2d-0d41-4c6f-a194-7d9f99e34ab1", "metric_type": "api_errors", "enabled": true, "threshold": 33, "webhook_config": { "url": "https://example.com/webhooks/alarms", "headers": { "Content-Type": "appl***" } }, "email_addresses": ["alerts@example.com"], "sms_numbers": ["+15555550123"], "created_at": "2026-03-12T15:56:21.836Z", "updated_at": "2026-03-12T15:56:21.836Z" } }, "errors": null } ``` ```json Error theme={null} { "data": null, "errors": [ { "error": "INVALID_THRESHOLD", "message": "Threshold must be a positive number" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Test Alarm Notifications Source: https://docs.bland.ai/api-v1/post/alarms-id-notify POST https://api.bland.ai/v1/alarms/{id}/notify Send a test alarm or recovery notification. ### Headers Your API key for authentication. ### Path Parameters Alarm configuration ID. ### Body Parameters Notification type to test. Allowed values: `alarm`, `recovery`. ### Response Whether at least one configured delivery method succeeded. Summary of the test result. Delivery results by channel (`webhook`, `email`, `sms`). Whether webhook delivery succeeded. HTTP status returned by the webhook endpoint, when available. Whether email delivery succeeded. Recipient list used for the test email. `null` on success response, or an array with `NOTIFICATION_TEST_FAILED`. ```json Success theme={null} { "data": { "success": true, "message": "Alarm notification test completed: 2/2 methods successful", "results": { "webhook": { "success": true, "statusCode": 200 }, "email": { "success": true, "sentTo": ["alerts@example.com"] } } }, "errors": null } ``` ```json Error theme={null} { "data": null, "errors": [ { "error": "INVALID_NOTIFICATION_TYPE", "message": "type must be either 'alarm' or 'recovery'" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Toggle Alarm Source: https://docs.bland.ai/api-v1/post/alarms-id-toggle POST https://api.bland.ai/v1/alarms/{id}/toggle Enable or disable an alarm. ### Headers Your API key for authentication. ### Path Parameters Alarm configuration ID. ### Body Parameters * `true`: Alarm is active. The system will evaluate this metric on scheduled runs and can generate alarm/recovery events and notifications. * `false`: Alarm is paused. The config is retained, but scheduled evaluation and notifications for this alarm are disabled until re-enabled. ### Response Updated alarm configuration object. Updated enabled state. Alarm configuration ID. Metric this alarm tracks. Configured threshold for this alarm. Webhook settings object. Header values may be masked in responses. Email recipients for notifications. Can be an empty array. SMS recipients for notifications. Can be an empty array. ISO timestamp when the alarm was created. ISO timestamp when the alarm was last updated. `null` on success, otherwise an array of error objects. ```json Success theme={null} { "data": { "alarm": { "id": "72e424a6-496f-4f89-a349-c6c8cb3eff29", "metric_type": "latency", "enabled": false, "threshold": 0.5, "webhook_config": { "url": "https://example.com/webhooks/alarms", "headers": { "Content-Type": "appl***" } }, "email_addresses": ["alerts@example.com"], "sms_numbers": [], "created_at": "2026-03-12T16:13:02.694Z", "updated_at": "2026-03-12T17:08:56.928Z" } }, "errors": null } ``` ```json Error theme={null} { "data": null, "errors": [ { "error": "INVALID_ENABLED_VALUE", "message": "enabled must be a boolean value (true or false)" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Trigger Alarm Evaluation Source: https://docs.bland.ai/api-v1/post/alarms-id-trigger POST https://api.bland.ai/v1/alarms/{id}/trigger Manually trigger alarm evaluation with current data. ### Headers Your API key for authentication. ### Path Parameters Alarm configuration ID. ### Response Whether the evaluation completed with enough data. Human-readable result message. Current metric snapshot, when available. Current metric value. Number of samples used in evaluation. Deviation from baseline. Configured threshold for comparison. ```json Success theme={null} { "data": { "success": true, "message": "Test completed successfully. Current alarm state: NORMAL", "currentMetrics": { "value": 0.2, "sampleCount": 22, "deviation": null, "threshold": 2.5 } }, "errors": null } ``` ```json Not Enough Data theme={null} { "data": { "success": false, "message": "Not enough recent data available. Please wait until there is more data to trigger an alarm." }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Block Rules Source: https://docs.bland.ai/api-v1/post/blocked-numbers POST https://api.bland.ai/v1/blocked_numbers Create one or more block rules to prevent specific phone numbers from reaching your inbound numbers. **Call Blocking** – Blocked numbers will be rejected before reaching any agent. Blocking can apply globally or to specific inbound lines. ### Headers Your API key for authentication. ### Body Parameters A list of phone numbers to block, formatted in E.164 (e.g., `+14155551234`). Maximum 10 numbers per request. Set to `true` to block the numbers globally across all inbound numbers. Set to `false` to scope the block to a specific `inbound_number`. You cannot enable both `is_global` and `inbound_number` in the same request. The E.164 formatted inbound number to associate the block with. Required when `is_global` is `false`. Optional text to describe the reason for blocking. ### Response Contains the number of rules created and the list of created blocks. Number of block rules successfully created. List of block rule objects that were created. `null` on success, or an array of error objects if validation fails. ```json Response theme={null} { "data": { "created_count": 1, "blocks": [ { "id": 123, "blocked_number": "+10000000000", "is_global": true, "inbound_number": null, "org_id": "b7d3e9fc-5c4a-4c2a-9b8f-d1e1d1a2e333", "reason": null, "is_active": true, "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z" } ] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Edit Block Rule Source: https://docs.bland.ai/api-v1/post/blocked-numbers-id-edit POST https://api.bland.ai/v1/blocked_numbers/{block_id}/edit Update attributes of an existing block rule. You can only update fields like `reason` or `is_active`. Phone numbers and scope (global/inbound) are immutable after creation. ### Headers Your API key for authentication. ### Path Parameters The unique ID of the block rule to update. ### Body Parameters Optional reason for blocking. Set to `null` to remove an existing reason. Controls whether the block rule is currently enforced. Set to `false` to disable or `true` to re-enable. Use `null` to leave unchanged. ### Response The updated block rule object. Unique ID of the block rule. The phone number being blocked. Indicates if the block applies globally. The specific inbound number the block applies to (if not global). UUID of the owning organization. Reason for the block, if present. Whether the block rule is currently active. ISO timestamp when the rule was created. ISO timestamp of the last update. `null` on success, or a list of validation or lookup errors. ```json Response theme={null} { "data": { "id": 123, "blocked_number": "+10000000000", "is_global": false, "inbound_number": "+18888888888", "org_id": "b7d3e9fc-5c4a-4c2a-9b8f-d1e1d1a2e333", "reason": "User requested block", "is_active": false, "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-10T12:00:00.000Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Send Call Source: https://docs.bland.ai/api-v1/post/calls POST https://api.bland.ai/v1/calls Send an AI phone call with a custom objective and actions. ## Overview Send an AI phone call with a custom objective and actions. This endpoint can be used to create dynamic phone calls where the AI agent can follow instructions, use tools, and follow a conversation pathway. *** ## Headers Your API key for authentication. A special key for using a BYOT (Bring Your Own Twilio) account. Only required for sending calls from your own Twilio account. Learn more about BYOT [here](/tutorials/custom-twilio). *** ## Body Parameters ### Basic Parameters The phone number to call. Must be a valid phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. The voice of the AI agent to use. Accepts any form of voice ID, including custom voice clones and voice presets. Default voices can be referenced directly by their name instead of an id. Usage example: voice: "maya" Bland Curated voices: * Josh * Florian * Derek * June * Nat * Paige This is the pathway ID for the pathway you have created on our dev portal. You can access the ID of your pathways by clicking the 'Copy ID' button of your pathway [here](https://app.bland.ai/home?page=convo-pathways) Note: Certain parameters do not apply when using pathways. Example Simple Request body: ```json theme={null} { "phone_number": "+1975934749", "pathway_id": "a0f0d4ed-f5f5-4f16-b3f9-22166594d7a7" } ``` The version number of the pathway to use for the call. Defaults to the production version. Note: Do not specify if using a pathway. Provide instructions, relevant information, and examples of the ideal conversation flow. This is your prompt where you are telling the agent what to do. Recommendations: * Include context and a background/persona for the agent like `"You are {name}, a customer service agent at {company} calling {name} about {reason}`. * Phrase instructions like you are speaking to the agent before the call. * Any time you tell the agent not to do something, provide an example of what they should do instead. * Keep the prompt under 2,000 characters where possible. Makes your agent say a specific phrase or sentence for it's first response. The ID of the persona to use for the call. Personas act as pre-configured templates that automatically apply a configuration when you pass a persona\_id to an outbound call. Think of them as "call presets" that you can reuse across multiple calls. When using a persona\_id, any parameters specified in your request body will override the corresponding parameters from the persona's configuration. You can access your persona IDs by clicking the "Personas" button at the bottom of the Send Call page, and then "Use and Manage". ### Model Parameters Select a model to use for your call. Options: `base` or `turbo`. In nearly all cases, `base` is the best choice. There are two different ways to use Bland: * `model: base` * The original, follows scripts/procedures most effectively. * Supports all features and capabilities. * Best for Custom Tools * `model: turbo` * The absolute fastest latency possible, can be verbose at times * Limited capabilities currently (excludes Transferring, IVR navigation, Custom Tools) * Extremely realistic conversation capabilities Select a supported language of your choice. Optimizes every part of our API for that language - transcription, speech, and other inner workings. The available language options are as follows: * `babel` - Babel (All Languages) - Experimental1 * `fluent` - Fluent (Multilingual)2 * `en` - English * `babel-en` - English (Babel) * `en-US` - English (US) * `en-GB` - English (UK) * `en-AU` - English (Australia) * `en-NZ` - English (New Zealand) * `en-IN` - English (India) * `es` - Spanish * `babel-es` - Spanish (Babel) * `es-419` - Spanish (Latin America) * `fr` - French * `babel-fr` - French (Babel) * `fr-CA` - French (Canada) * `de` - German * `babel-de` - German (Babel) * `el` - Greek * `hi` - Hindi * `hi-Latn` - Hindi (Latin script) * `hu` - Hungarian * `ja` - Japanese * `ko` - Korean * `ko-KR` - Korean (Korea) * `vi` - Vietnamese * `pt` - Portuguese * `pt-BR` - Portuguese (Brazil) * `pt-PT` - Portuguese (Portugal) * `zh` - Chinese (Mandarin, Simplified) * `zh-CN` - Chinese (Mandarin, Simplified, China) * `zh-Hans` - Chinese (Mandarin, Simplified, Hans) * `zh-TW` - Chinese (Mandarin, Traditional) * `zh-Hant` - Chinese (Mandarin, Traditional, Hant) * `it` - Italian * `nl` - Dutch * `pl` - Polish * `ru` - Russian * `sv` - Swedish * `sv-SE` - Swedish (Sweden) * `da` - Danish * `da-DK` - Danish (Denmark) * `fi` - Finnish * `no` - Norwegian * `id` - Indonesian * `ms` - Malay * `tr` - Turkish * `uk` - Ukrainian * `bg` - Bulgarian * `cs` - Czech * `ro` - Romanian * `sk` - Slovak * `auto` - Auto Detect (English & Spanish) 1 The Bland Babel Transcription Engine (BETA) is our new proprietary transcription engine! Babel can handle multilingual conversations by identifying and switching languages on the fly. It's now in beta and available under the "babel" language mode. **Note: For pathway calls and prompts, make sure to prompt your agent to respond in the language they are spoken to.** 2 The `fluent` mode is a multilingual option that auto-detects the spoken language and switches between languages on the fly, powered by a multilingual transcription model. **Note: For pathway calls and prompts, make sure to prompt your agent to respond in the language they are spoken to.** By default, the agent starts talking as soon as the call connects. When wait\_for\_greeting is set to true, the agent will wait for the call recipient to speak first before responding. The pronunciation guide is an `array` of `objects` that guides the agent on how to say specific words. Use this to improve clarity for acronyms, names, brand terms, or jargon. ```json theme={null} [ { "word": "example", "pronunciation": "ex-am-ple", "case_sensitive": "false", "spaced": "false" }, { "word": "API", "pronunciation": "A P I", "case_sensitive": "true", "spaced": "true" } ] ``` * `word` — the word you want to guide the LLM on how to pronounce * `pronunciation` — how the AI should pronounce the word, using syllables or space-separated characters. For example, `"A P I"` ensures each letter is spoken clearly rather than read as a word. * `case_sensitive` — whether or not to consider case. Particularly useful with names. EG: 'Max' the name versus 'max' the word. Defaults to false. `Not required`. * `spaced` — whether to match whole words only. When true, "high" will match "high" but not "hightop". When false, it will match any word that contains "high". Defaults to true. `Not required`. A value between 0 and 1 that controls the randomness of the LLM. 0 will cause more deterministic outputs while 1 will cause more random. Example Values: "0.9", "0.3", "0.5" Adjusts how patient the AI is when waiting for the user to finish speaking. Lower values mean the AI will respond more quickly, while higher values mean the AI will wait longer before responding. Controls how readily the AI stops speaking when the caller talks over it. A higher value yields more easily; a lower value holds the turn through more of the caller's speech. * `0`: Block. The AI ignores interruptions and finishes speaking (same as `block_interruptions: true`). * `1`: Difficult. Harder to interrupt. * `2`: Balanced (default). * `3`: Easy. The AI stops quickly when the caller begins speaking. ### Dispatch Parameters Specify a phone number to call from that you own or have uploaded from your Twilio account. Country code is required, spaces or parentheses must be excluded. By default, calls are initiated from a separate pool of numbers owned by Bland. If you are using your own twilio numbers, you must specify a matching encrypted\_key in the create call request headers. Controls how the caller number (`from`) is selected when placing an outbound call. Use this field to influence how the system chooses a number that appears local or relevant to the callee, improving pickup rates. There are two supported strategies: #### 1. `local` Automatically selects a `from` number that matches the callee's area code for **US-based calls**. You must have purchased a local dialing add-on in the [add-ons section](https://app.bland.ai/dashboard/add-ons). Example: ```json theme={null} { "dialing_strategy": { "type": "local" } } ``` #### 2. `custom_pooling` Selects a number from your own pre-configured pool of phone numbers. Designed for organizations that want full control over the caller IDs being used. This is an enterprise only feature, to use this feature contact your Bland representative or reach out to sales. Example: ```json theme={null} { "dialing_strategy": { "type": "custom_pooling", "pool_id": "bd039087-decb-435a-a6e3-ca1ffbf89974" } } ``` By default, Bland will choose a US-based number from our own pool of numbers. Set the timezone for the call. Handled automatically for calls in the US. This helps significantly with use cases that rely on appointment setting, scheduling, or behaving differently based on the time of day. Timezone options are here in the TZ identifier column. The time you want the call to start. If you don't specify a time (or the time is in the past), the call will send immediately. Set your time in the format YYYY-MM-DD HH:MM:SS -HH:MM (ex. 2021-01-01 12:00:00 -05:00). The timezone is optional, and defaults to UTC if not specified. Note: Scheduled calls can be cancelled with the POST /v1/calls/:call\_id/stop endpoint. A phone number that the agent can transfer to under specific conditions - such as being asked to speak to a human or supervisor. This option will be ignored for pathways. For best results: * Specify conditions that the agent should transfer to a human under (examples are great!) * In the `task`, refer to the action solely as "transfer" or "transferring". * Alternate phrasing such as "swap" or "switch" can mislead the agent, causing the action to be ignored. Give your agent the ability to transfer calls to a set of phone numbers. This option will be ignored for pathways. Overrides transfer\_phone\_number if a transfer\_list.default is specified. Will default to transfer\_list.default, or the chosen phone number. Example usage to route calls to different departments: ```json theme={null} { "transfer_list": { "default": "+12223334444", "sales": "+12223334444", "support": "+12223334444", "billing": "+12223334444" } } ``` When the call starts, a timer is set for the `max_duration` minutes. At the end of that timer, if the call is still active it will be automatically ended. Example Values: 20, 2 ### Knowledge Parameters Add custom tools and knowledge bases to your call for your agent to call upon. Example: ```json theme={null} { "tools": [ "TL-ba6c4237-67c2-40e8-868b-60d429a84eda", "KB-30d465c0-22d0-41e0-a63d-61bcacc277e7" ] } ``` Read more about custom tools [here](https://docs.bland.ai/tutorials/custom-tools#custom-tools) ### Audio Parameters Select an audio track that you'd like to play in the background during the call. The audio will play continuously when the agent isn't speaking, and is incorporated into it's speech as well. Use this to provide a more natural, seamless, engaging experience for the conversation. We've found this creates a significantly smoother call experience by minimizing the stark differences between total silence and the agent's speech. Options: * null - Default, will play audible but quiet phone static. * office - Office-style soundscape. Includes faint typing, chatter, clicks, and other office sounds. * cafe - Cafe-like soundscape. Includes faint talking, clinking, and other cafe sounds. * restaurant - Similar to cafe, but more subtle. * none - Minimizes background noise Toggles noise filtering or suppression in the audio stream to filter out background noise. When set to `true`, the AI will not respond or process interruptions from the user. To record your phone call, set `record` to true. When your call completes, you can access through the `recording_url` field in the call details or your webhook. ### Voicemail Parameters Configuration for handling voicemails during outbound calls. This object controls how the AI behaves when it encounters a voicemail, including whether to leave a message, send an SMS notification, or detect voicemails more intelligently using AI. It has the following parameters: * `message` (string): The message the AI will leave if a voicemail is detected. This message will be played after the beep, then the call will end. This field is required if `action` is set to `leave_message`.
* `action` (enum): What the AI should do when it detects a voicemail. The default is `"hangup"`. Available options: * `"hangup"`: Immediately end the call without leaving a message. * `"leave_message"`: Play the `message` and then end the call. * `"ignore"`: Continue the call as if no voicemail was detected (used for IVRs or special routing).
* `sms` (object): Optional. Configuration for sending an SMS notification when a voicemail is left. Contains: * `to` (string): The phone number to send the SMS to (usually the same as the original callee). * `from` (string): The phone number to send the SMS from (must be a number you own and have SMS permissions for). * `message` (string): The body of the SMS message. Keep concise and clear.
* `sensitive` (boolean): When `true`, uses LLM-based analysis to detect frequent voicemails. The default is `false`. Example: ```json theme={null} { "voicemail": { "message": "Hi, just calling to follow up. Please call us back when you can.", "action": "leave_message", "sms": { "to": "+18005550123", "from": "+18005550678", "message": "We just left you a voicemail. Call us back anytime!" }, "sensitive": true } } ```
### Analysis Parameters The citation schema is an incredibly powerful tool for running ***post call analysis***, including specific variable extractions, conditional logic, and more. You can build a citation schema [here](https://app.bland.ai/dashboard/analytics?tab=citations). After building the citation schema (or schemas), you can copy their UUIDs and reference them in your API request for outgoing calls (and you can also attach them to your inbound phone numbers). Here's an example: ```json theme={null} { "citation_schema_ids": ["b7c2e1d4-8f3a-4c9e-9a2b-1e5f6d7c8a9b", "f2d3c4b5-6a7e-8d9c-0b1a-2c3d4e5f6a7b"] } ``` > Note: Citation schemas are very powerful and accurate, but also are more resource intensive to run. As such, for the time being, they are an enterprise-only feature. When `true` and the call is transferred to a human, Bland transcribes the conversation after the transfer live and streams it over the [Post-Transfer Transcript Stream](/api-v1/post/calls-id-transcript-stream) WebSocket while the transferred conversation is happening. Works for both cold and warm transfers. This option controls the live stream only. To receive the post-transfer transcript in the post-call webhook, subscribe with `"post_transfer_transcript"` in `webhook_events`. The two are independent: you can use either one or both. This feature is in limited rollout. If it is not enabled for your organization, the option has no effect. Attach an [evals workbench](/tutorials/evals) to this call. When the call completes, Bland automatically runs the workbench's eval configuration against the call — no separate eval-run submission needed. Provide at least one of: * `workbench_setup_id` (string): The workbench setup to attach. Bland pins the setup's current published version at call creation, so editing the workbench mid-call does not change what gets evaluated. * `workbench_setup_version_id` (string): An exact published workbench setup version to pin. Attaching evals requires the call to be recorded. If you set `record: false` alongside `post_call_evals`, the request is rejected; otherwise recording is enabled automatically. The post-call webhook acknowledges the attachment with `post_call_evals: { workbench_setup_id, workbench_setup_version_id, status: "pending" }`. Eval scores arrive later on a separate `evals` webhook event once the run completes. Example: ```json theme={null} { "post_call_evals": { "workbench_setup_id": "b7c2e1d4-8f3a-4c9e-9a2b-1e5f6d7c8a9b" } } ``` ### Post Call Parameters (Optional) Custom instructions for how the call summary should be generated after the call completes. Use this to provide specific guidance or context for the AI when writing the post-call summary. Maximum length: 2000 characters. Example: ```json theme={null} { "summary_prompt": "Summarize the call in 2-3 sentences, focusing on the customer's main concern and any next steps discussed." } ``` If the call goes to voicemail, you can set up the call to retry, after a configurable delay. You can also update the voicemail\_action, and voicemail\_message in the retry object, for the re-tried call. Takes in the following parameters: * `wait` (integer): The delay in seconds before the call is retried. * `voicemail_action` (enum): The action to take when the call goes to voicemail. Options: `hangup`, `leave_message`, `ignore`. * `voicemail_message` (string): The message to leave when the call goes to voicemail. Example: ```json theme={null} { "retry": { "wait": 10, "voicemail_action": "leave_message", "voicemail_message": "Hello, this is a test message." } } ``` A list of possible outcome tags (dispositions) you define. After the call ends, the AI reviews the transcript and picks **one** of these tags to describe how the call went. Tag selection is based **only** on the transcript, no metadata or external inputs are used. The chosen tag will appear in the `disposition_tag` field of the call data. If no custom `dispositions` are provided, the AI will automatically select from these built-in tags: * `INTERESTED` - Customer shows clear interest in the offering * `NOT_INTERESTED` - Customer expresses lack of interest * `FOLLOW_UP_REQUIRED` - Customer needs additional follow-up * `CALL_BACK_SCHEDULED` - A callback appointment was scheduled * `TRANSFERRED` - Call was transferred to another agent/department * `OBJECTION_RAISED` - Customer raised concerns or objections * `NEEDS_MORE_INFO` - Customer requires additional information * `NOT_QUALIFIED` - Customer does not meet qualification criteria * `NO_CONTACT_MADE` - Unable to establish meaningful contact * `COMPLETED_ACTION` - Customer completed the desired action * `DO_NOT_CONTACT` - Customer requested no future contact * `AGENT_ENDED_CALL` - Call ended by AI (auto-assigned for calls >2 minutes without transcript) * `NO_ANSWER` - Call was not answered (auto-assigned by system) * `BUSY` - Number was busy (auto-assigned by system) * `CANCELED` - Call was canceled (auto-assigned by system) * `FAILED` - Call failed to connect (auto-assigned by system) Example: ```json theme={null} { "dispositions": ["got_full_name_and_number", "no_information_provided", "transferred_to_agent"] } ``` ### Advanced Parameters Custom key-value data you send with the call. This information is available as variables inside your prompt, pathway, or tools — but only if the call is answered. ```json theme={null} { "task": "Say hello to the user, who's name is {{name}}", "request_data": { "name": "John Doe" } } ``` In this case, the AI would say: "Hello, John". Add any additional information you want to associate with the call. This data is accessible for all calls, regardless of if they are picked up or not. This can be used to track calls or add custom data to the call. Anything that you put here will be returned in the post call webhook under metadata. Example: ```json theme={null} { "metadata": { "campaign_id": "1234", "source": "web" } } ``` When the call ends, call information is sent to this webhook URL. Specify which events you want to stream to the webhook, during the call. **Citation Webhook Requirements:** * Include `citations` for any citation webhooks (sent separately after call completion) * For delayed post-call webhooks with citations, you need `citations` + dashboard delay toggle enabled See the [Citations documentation](/enterprise-features/citations#webhook-integration-options) for complete setup instructions. Options: * `queue` * `call` * `latency` * `webhook` * `tool` * `dynamic_data` * `citations` (Required for any citation webhooks) * `evals` (Eval scores from an attached [evals workbench](/tutorials/evals), sent as a separate webhook when the run completes) * `post_transfer_transcript` (Adds the post-transfer conversation to the post-call webhook when the call is transferred to a human; see [Post-transfer transcript](/tutorials/post-call-webhooks#post-transfer-transcript). Requires call recording: `record` is enabled automatically when unset, and passing `record: false` alongside this subscription returns a 400. In limited rollout: if not enabled for your organization, the subscription has no effect.) Example payloads: ```json queue theme={null} // ex 1 { "message": "Call enqueued", "call_id": "12345678-1234-1234-1234-123456789abc", "category": "queue", "log_level": "info" } ``` ```json call theme={null} // ex 1 { "message": "Call connected", "call_id": "12345678-1234-1234-1234-123456789abc", "category": "call", "log_level": "info" } // ex 2 { "message": "Sending first sentence: Hello, thank you for reaching out. I'd like to get to know you a bit better. How are you feeling today?", "call_id": "12345678-1234-1234-1234-123456789abc", "category": "call", "log_level": "info" } // ex 3 { "message": "Agent speech: Hello, thank you for reaching out.", "call_id": "12345678-1234-1234-1234-123456789abc", "category": "call", "log_level": "info" } // ex 4 { "message": "Handling user speech: Yeah. I'm thirty six. And I'm five foot nine.", "call_id": "12345678-1234-1234-1234-123456789abc", "category": "call", "log_level": "info" } // ex 5 { "message": "Webhook Response: 200 | Webhook Response Data: [object Object] | Response Time: 689ms", "call_id": "87654321-4321-4321-4321-cba987654321", "category": "call", "log_level": "info" } ``` ```json latency theme={null} // ex 1 { "message": "TTS: 218ms", "call_id": "12345678-1234-1234-1234-123456789abc", "category": "latency", "log_level": "performance" } // ex 2 { "message": "LLM: 266ms", "call_id": "12345678-1234-1234-1234-123456789abc", "category": "latency", "log_level": "performance" } ``` ```json webhook theme={null} { "message": "Storing dynamic data messages: \n\n answer : \"true\"", "call_id": "87654321-4321-4321-4321-cba987654321", "category": "call", "log_level": "info" } ``` ```json tool theme={null} { "message": "Executing custom tool: Test Tool 4 with input: [object Object]", "call_id": "abcdef12-3456-7890-abcd-ef1234567890", "category": "call", "log_level": "info" } ``` ```json dynamic_data theme={null} { "message": "Storing dynamic data: \n\n vector_data : {\"data\":{\"results\":[{\"id\":\"fedcba98-7654-3210-fedc-ba9876543210\",\"input_text\":\"Here are details on the restaurant...\",\"similarity\":0.103339002763233,\"chunk_index\":0}]},\"errors\":null}", "call_id": "abcdef12-3456-7890-abcd-ef1234567890", "category": "call", "log_level": "info" } ``` ```json citations theme={null} { "call_id": "12345678-1234-1234-1234-123456789abc", "user_id": "11111111-2222-3333-4444-555555555555", "event_type": "citations", "timestamp": "2025-07-03T16:41:15.231Z", "citations": [ { "call_id": "12345678-1234-1234-1234-123456789abc", "variable_name": "User height", "variable_type": "boolean", "value": true, "cited_utterances": [ { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "idx": 3, "start_time": 24.096, "end_time": 27.424, "confidence": 0.17166666666666666, "channel": 1, "transcript": "I am 36 and I am 5'9\".", "speaker_id": "SPEAKER_1_0", "speaker_name": null, "speaker_description": null, "topics": [ "customer_information_provided" ], "topics_meta": "{\"customer_information_provided\":\"customer providing personal details\"}", "utterance_type": "answer" } ], "schema_id": "99999999-8888-7777-6666-555555555555" }, { "call_id": "12345678-1234-1234-1234-123456789abc", "variable_name": "Caller Age", "variable_type": "number", "value": 36, "cited_utterances": [ { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "idx": 3, "start_time": 24.096, "end_time": 27.424, "confidence": 0.17166666666666666, "channel": 1, "transcript": "I am 36 and I am 5'9\".", "speaker_id": "SPEAKER_1_0", "speaker_name": null, "speaker_description": null, "topics": [ "customer_information_provided" ], "topics_meta": "{\"customer_information_provided\":\"customer providing personal details\"}", "utterance_type": "answer" }, { "id": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "idx": 4, "start_time": 30.56, "end_time": 35.455, "confidence": 0.5672727272727273, "channel": 0, "transcript": "All right. So you're 36 years old and five foot nine. That's great. How's your day been so far? Anything exciting happened?", "speaker_id": "SPEAKER_0_0", "speaker_name": null, "speaker_description": null, "topics": [ "day_review_inquiry" ], "topics_meta": "{\"day_review_inquiry\":\"agent inquiring about the customer's day and any exciting events\"}", "utterance_type": "question" } ], "schema_id": "99999999-8888-7777-6666-555555555555" }, { "call_id": "12345678-1234-1234-1234-123456789abc", "variable_name": "Caller feeling", "variable_type": "string", "value": null, "cited_utterances": [], "schema_id": "99999999-8888-7777-6666-555555555555" } ] } ``` Integrate data from external APIs into your agent's knowledge. Set to `null` or an empty string to clear dynamic data settings. ```json theme={null} "dynamic_data": [ { "url": "endpoint", "method": "GET", "body": [], "headers": [ { "key": "Content-Type", "value": "application/json" } ], "query": [], "cache": true, "response_data": [ { "context": "", "data": "$", "name": "" } ] } ], ``` These words will be boosted in the transcription engine - recommended for proper nouns or words that are frequently mis-transcribed. For example, if the word Blandy is frequently transcribed as a homonym like "Reese" you could do this: ```json theme={null} { "keywords": ["Blandy"] } ``` For stronger keyword boosts, you can place a colon then a boost factor after the word. The default boost factor is 2. ```json theme={null} { "keywords": ["Blandy:3"] } ``` When `true`, the system will ignore DTMF input (Dual-Tone Multi-Frequency) — the tones generated when a user presses keys on their phone keypad (e.g., 0-9, \*, #).\ This disables any in-call actions triggered by keypad input, such as menu navigation or transfers.\ Useful when your agent should handle the entire call conversationally, without responding to button presses. A sequence of DTMF digits that will be played before the call starts. Acceptable characters are 0-9, \*, #, and w, where w is a pause of 0.5 seconds. Example: ```json theme={null} { "precall_dtmf_sequence": "1234567890*#w" } ``` Configure guard rails to monitor the call for compliance violations and trigger actions automatically. Guard rails continuously analyze AI and user responses during the call. Learn more about guard rails in the [Guard Rails documentation](/tutorials/guard-rails). Each item in the array can be one of three types: * `tcpa:ai_disclosure` - AI must disclose it's an AI * `tcpa:self_introduction` - Must identify who is calling * `tcpa:recording_disclosure` - Must disclose the call is being recorded * `tcpa:opt_out` - This out-of-the-box guard rail is different as it's not time-based and instead monitors the entire conversation to see if the agent continues to engage in the conversation after the user opts out. `config.end_seconds` is not needed for this type. ```json theme={null} { "type": "tcpa:ai_disclosure", "actions": [ { "type": "end_call" } ], "config": { "end_seconds": 30 } } ``` | Field | Type | Description | | -------------------- | ------ | ----------------------------------------------------------------------------------- | | `type` | string | One of: `tcpa:ai_disclosure`, `tcpa:self_introduction`, `tcpa:recording_disclosure` | | `actions` | array | Actions to take if disclosure is NOT made within the time window | | `config.end_seconds` | number | Time window in seconds (default: 30) | Custom guard rails with your own prompt. Enterprise customers can create up to 5 custom guard rails. ```json theme={null} { "type": "custom", "prompt": "Flag if the agent provides any medical advice or diagnosis...", "actions": [ { "type": "transfer", "config": { "phone_number": "+15551234567" } } ] } ``` | Field | Type | Description | | --------- | ------ | -------------------------------------------- | | `type` | string | `custom` | | `prompt` | string | Your custom detection prompt | | `actions` | array | Actions to take when the guard rail triggers | Each guard rail requires an `actions` array. Available action types: | Action Type | Description | Config | | -------------- | ------------------------------- | ------------------------------------ | | `end_call` | Immediately terminate the call | None | | `transfer` | Transfer to a human agent | `{ "phone_number": "+15551234567" }` | | `move_to_node` | Jump to a specific pathway node | `{ "node_id": "node-uuid" }` | **Full example with multiple guard rails:** ```json theme={null} { "guard_rails": [ { "type": "tcpa:ai_disclosure", "actions": [{ "type": "end_call" }], "config": { "end_seconds": 30 } }, { "type": "tcpa:opt_out", "actions": [{ "type": "end_call" }] }, { "type": "custom", "prompt": "Flag if the agent makes any investment recommendations", "actions": [ { "type": "transfer", "config": { "phone_number": "+15551234567" } } ] } ] } ``` ## Response Can be `success` or `error`. A message explaining the status of the call. A unique identifier for the call (present only if status is `success`). The batch ID of the call (present only if status is `success`). For validation errors, a detailed list of each field with an error and it's error message. Example: ```json theme={null} { "status": "error", "message": "Invalid parameters", "errors": [ "Missing required parameter: phone_number.", "Missing required parameter: task.", "Phone number must be a string or number.", "Task must be a string." ] } ``` ```json theme={null} { "status": "success", "message": "Call successfully queued.", "call_id": "9d404c1b-6a23-4426-953a-a52c392ff8f1", "batch_id": null } ``` ## Error Codes Reference This section documents all possible error codes and HTTP status codes you can receive when making a POST request to `/v1/calls`. ### Authentication & Authorization Errors Authentication failed due to missing or invalid API key. ```json theme={null} { "data": null, "errors": [ { "error": "AUTH_FAILURE", "message": "Unauthorized" } ] } ``` **Common causes:** * Missing Authorization header * Invalid API key * Expired API key Account has been flagged or banned for security purposes. ```json theme={null} { "status": "error", "message": "The Bland Team has flagged your account for security purposes. As a precautionary measure against recent heightened malicious use cases, we have flagged your account for review and temporarily blocked from dispatching calls. If you need to be unblocked urgently, please email us at hello@bland.ai with your account phone number." } ``` ### Rate Limiting Errors (HTTP 429) Calls sent too frequently to the same number. ```json theme={null} { "status": "error", "message": "Calls can only be sent every 10 seconds to the same number. Please try again in a few seconds." } ``` Rate limit exceeded for your account. ```json theme={null} { "status": "error", "message": "Rate limit exceeded" } ``` Attempting to call a blacklisted number. ```json theme={null} { "status": "error", "message": "This number is blacklisted." } ``` Rate limits for newly created accounts. ```json theme={null} { "status": "error", "message": "Rate limit exceeded for newly created accounts. Please try again soon." } ``` International calling rate limit exceeded. ```json theme={null} { "status": "error", "message": "International rate limit exceeded for your account type." } ``` ### Parameter Validation Errors (HTTP 400) Required parameters are missing from the request. ```json theme={null} { "status": "error", "message": "Invalid parameters. Error: [\"Missing required parameter: phone_number.\"]", "errors": ["Missing required parameter: phone_number."] } ``` **Required parameters:** * `phone_number` (always required) * `task` (required if `pathway_id` is not provided) Field values are the wrong data type according to TypeBox validation. ```json theme={null} { "status": "error", "message": "Record must be a boolean" } ``` **Common type validation errors:** * `"Task must be a string"` * `"Record must be a boolean"` * `"Max duration must be a number"` * `"Temperature must be a number"` * `"Tools must be an array"` * `"Dynamic data must be an array"` * `"Metadata must be a record of string keys and any values"` Voicemail action must be one of the allowed values. ```json theme={null} { "status": "error", "message": "Invalid voicemail action. Must be one of: hangup, leave_message, ignore" } ``` Numeric values are outside their allowed ranges. ```json theme={null} { "status": "error", "message": "Max duration must be at least 1" } ``` Precall DTMF sequence contains invalid characters. ```json theme={null} { "status": "error", "message": "Precall DTMF sequence must be a valid DTMF sequence" } ``` **Valid DTMF characters:** 0-9, \*, #, w (wait) Start time must be a valid ISO date-time string. ```json theme={null} { "status": "error", "message": "Start time must be a valid date-time format" } ``` Webhook URL format is invalid. ```json theme={null} { "status": "error", "message": "Webhook must be a valid URI" } ``` From number doesn't match phone number pattern. ```json theme={null} { "status": "error", "message": "Invalid from number format" } ``` Transfer phone number format validation error. ```json theme={null} { "status": "error", "message": "Invalid transfer phone number format" } ``` Transfer list contains phone numbers with invalid format. ```json theme={null} { "status": "error", "message": "Invalid phone number format in transfer list" } ``` Request contains fields that are not allowed in the schema. ```json theme={null} { "status": "error", "message": "Additional properties are not allowed" } ``` Phone number format is invalid, missing country code, or invalid length. ```json theme={null} { "status": "error", "message": "Invalid phone number. Please include a country code if outside the US." } ``` **Other variations:** ```json theme={null} { "status": "error", "message": "Invalid phone number. `+1234567890123456789` has these validation errors: [specific errors]" } ``` ```json theme={null} { "error": "Invalid phone number format" } ``` **Common causes:** * Phone number too long (>15 digits) or too short (\<7 digits) * Invalid characters in phone number * Missing country code for international numbers * Phone number fails Twilio validation Transfer phone number is invalid. ```json theme={null} { "status": "error", "message": "Invalid transfer_phone_number." } ``` Language code is not supported. ```json theme={null} { "status": "error", "message": "Invalid language code" } ``` Pronunciation guide format is incorrect. ```json theme={null} { "status": "error", "message": "Invalid pronunciation guide type." } ``` Feature not supported on the specified platform. ```json theme={null} { "status": "error", "message": "Precall DTMF sequence is not supported for this platform." } ``` The 'from' number is invalid or not owned by your account. ```json theme={null} { "status": "error", "message": "Invalid 'from' - must be a phone number string with 10 or 12 digits." } ``` Attempting to call a number on the Do Not Call list. ```json theme={null} { "status": "DNC Error", "message": "Number found in DNC list. You cannot dial sensitive numbers. More attempts will result in being blocked." } ``` Transfer list configuration errors. ```json theme={null} { "status": "error", "message": "Transfer list must be an object." } ``` ```json theme={null} { "status": "error", "message": "Invalid transfer phone number." } ``` ```json theme={null} { "status": "error", "message": "Transfer phone number cannot be the same as the phone number." } ``` Retry configuration must be an object. ```json theme={null} { "status": "error", "message": "Retry must be an object." } ``` Version number must be a valid number. ```json theme={null} { "status": "error", "message": "version_number must be a number." } ``` Pathway version must be a number or specific string value. ```json theme={null} { "status": "error", "message": "pathway_version needs to either be a number, or a string of 'production' or 'staging'." } ``` ```json theme={null} { "status": "error", "message": "version_number must be a number or string." } ``` The 'from' number format is invalid. ```json theme={null} { "status": "error", "message": "Invalid from phone number." } ``` Boolean parameters must be true/false or string equivalents. ```json theme={null} { "status": "error", "message": "wait_for_greeting must be a boolean." } ``` **Valid for parameters**: `wait_for_greeting`, `record`, `answered_by_enabled`, `block_interruptions`, `sensitive_voicemail_detection`, `ignore_button_press` First sentence must be a string. ```json theme={null} { "status": "error", "message": "First sentence must be a string. type: [actual_type]" } ``` Voicemail message must be a string. ```json theme={null} { "status": "error", "message": "Voicemail message must be a string. type: [actual_type]" } ``` Voicemail SMS configuration errors. ```json theme={null} { "status": "error", "message": "voicemail_sms must be an object. type: [actual_type]" } ``` ```json theme={null} { "status": "error", "message": "voicemail_sms.message must be a string. type: [actual_type]" } ``` ```json theme={null} { "status": "error", "message": "voicemail_sms.from must be a string. type: [actual_type]" } ``` Interruption threshold must be a number. ```json theme={null} { "status": "error", "message": "interruption_threshold must be a number." } ``` Webhook URL must be a valid HTTPS URL. ```json theme={null} { "status": "error", "message": "webhook must be a string that starts with https://." } ``` Request data must be an object. ```json theme={null} { "status": "error", "message": "request_data must be an object." } ``` Metadata must be an object. ```json theme={null} { "status": "error", "message": "metadata must be an object." } ``` Voice parameter must be a string. ```json theme={null} { "status": "error", "message": "Voice must be a string." } ``` Voicemail action must be one of the allowed values. ```json theme={null} { "status": "error", "message": "Invalid voicemail_action. Options are: [list_of_options]." } ``` Keywords configuration errors. ```json theme={null} { "status": "error", "message": "Keywords must be an array of strings." } ``` ```json theme={null} { "status": "error", "message": "Keywords must be strings." } ``` ```json theme={null} { "status": "error", "message": "Keywords each must be less than 100 characters: [keyword]" } ``` ```json theme={null} { "status": "error", "message": "Keywords must be in the format 'string' or 'string:number'." } ``` ```json theme={null} { "status": "error", "message": "Keyword boosts with a colon must have a valid integer for the boost rate." } ``` ```json theme={null} { "status": "error", "message": "At most 20 keywords can be added." } ``` Timezone validation errors. ```json theme={null} { "status": "error", "message": "Timezone must be a string." } ``` ```json theme={null} { "status": "error", "message": "Invalid timezone: [error_message]" } ``` Summary prompt validation errors. ```json theme={null} { "status": "error", "message": "Summary prompt must be a string." } ``` ```json theme={null} { "status": "error", "message": "Summary prompt must be less than 2000 characters." } ``` Start time scheduling validation errors. ```json theme={null} { "status": "error", "message": "start_time must be a string." } ``` ```json theme={null} { "status": "error", "message": "Invalid start_time." } ``` ```json theme={null} { "status": "error", "message": "Calls must be scheduled at least 5 minutes in advance, or more" } ``` Background track validation errors. ```json theme={null} { "status": "error", "message": "background_track must be a string." } ``` ```json theme={null} { "status": "error", "message": "Invalid background_track option. Options are: [list_of_options]." } ``` Max duration validation errors. ```json theme={null} { "status": "error", "message": "max_duration must be a number." } ``` ```json theme={null} { "status": "error", "message": "max_duration must be a positive number." } ``` ```json theme={null} { "status": "error", "message": "max_duration must be at most 12 hours." } ``` Dynamic data or tools configuration is invalid. ```json theme={null} { "status": "error", "message": "Unable to parse dynamic data/tools." } ``` ```json theme={null} { "status": "error", "message": "Invalid tools: [error_message]" } ``` ```json theme={null} { "status": "error", "message": "Invalid dynamic data: [error_message]" } ``` Pathway configuration is invalid or missing required components. ```json theme={null} { "status": "error", "message": "Invalid pathway data - no blocks or links found for pathway {pathway_id}" } ``` **Other variations:** ```json theme={null} { "status": "error", "message": "Invalid pathway data" } ``` The specified start node ID does not exist in the pathway. ```json theme={null} { "status": "error", "message": "Invalid start node ID: {start_node_id}" } ``` Content failed moderation and was flagged as inappropriate. ```json theme={null} { "status": "error", "message": "Flagged Node: [flagged content]" } ``` Attempting to call emergency or sensitive numbers. ```json theme={null} { "status": "error", "message": "Cannot dial sensitive numbers. More attempts will result in being blocked." } ``` Server unable to save the request body or call data. ```json theme={null} { "status": "error", "message": "Unable to save request body." } ``` Call could not be queued for processing. ```json theme={null} { "status": "error", "message": "Unable to queue call." } ``` Parent call for warm transfer has already completed or doesn't exist. ```json theme={null} { "status": "error", "message": "Parent call has completed or does not exist. Warm Transfer Request Cancelled" } ``` General server errors and catch-all error handlers. ```json theme={null} { "status": "error", "message": "Internal server error during flagging process" } ``` **Typical scenarios**: * Uncaught exceptions in call processing * Third-party service failures * Memory allocation or resource exhaustion errors * Network connectivity issues Basic call parameters validation from the main validation function. ```json theme={null} { "status": "error", "message": "Call parameters must be an object." } ``` ### Business Logic Errors No billing record found for your account. ```json theme={null} { "status": "error", "message": "No billing record found." } ``` Account balance is insufficient for the call. ```json theme={null} { "status": "error", "message": "Insufficient balance." } ``` The specified pathway ID does not exist or is not accessible. ```json theme={null} { "status": "error", "message": "Pathway with ID \"{pathway_id}\" not found" } ``` The specified pathway version does not exist. ```json theme={null} { "status": "error", "message": "Pathway version with ID \"{version_number}\" not found" } ``` The objective parameter failed validation (returns validation details). ```json theme={null} { "error": "OBJECTIVE_VALIDATION_ERROR", "details": "Custom validation response" } ``` ### Service Errors (HTTP 500) Failed to establish connection with Twilio services. ```json theme={null} { "status": "error", "message": "Error in creating Twilio connection." } ``` The encrypted key provided is invalid or corrupted. ```json theme={null} { "status": "error", "message": "Invalid `encrypted_key`. Please use the correct key for your account." } ``` General internal server error during call processing. ```json theme={null} { "status": "error", "message": "Error triggering call. Please check your twilio account for errors" } ``` Error occurred during the content flagging process. ```json theme={null} { "status": "error", "message": "Internal server error during flagging process" } ``` Error retrieving Bring Your Own Twilio (BYOT) phone number. ```json theme={null} { "status": "error", "message": "Error in getting BYOT Number" } ``` Error retrieving dialer data from encrypted key. ```json theme={null} { "status": "error", "message": "Error in getting dialer data from encrypted key" } ``` Error fetching user data for account verification. ```json theme={null} { "status": "error", "message": "Error in fetching user data" } ``` **Other variations:** ```json theme={null} { "status": "error", "message": "Error in fetching parent user data" } ``` Missing retry attempt information for retry calls. ```json theme={null} { "status": "error", "message": "Retry attempt not provided for retry call: {call_id}" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Stop All Active Calls Source: https://docs.bland.ai/api-v1/post/calls-active-stop POST https://us.api.bland.ai/v1/calls/active/stop End all active phone calls on your account. ### Headers Your API key for authentication. ### Response Can be `success` or `error`. If the status is `success`, the message will say "Call ended successfully." Otherwise, if the status is `error`, the message will say "SID not found for the given c\_id." or "Internal server error." The number of active calls that will be cancelled. ```json theme={null} { "status": "success", "message": "Stopping active calls. This may take some time...", "num_calls": 12 } ``` *** Docs for agents: [llms.txt](/llms.txt) # Transfer Active Call Source: https://docs.bland.ai/api-v1/post/calls-active-transfer POST https://api.bland.ai/v1/calls/active/transfer Transfer an in-progress call to a different phone number. ## Overview Transfers an active call to a different phone number while the call is in progress. The current call leg is replaced with a `` to the new number, no announcement is played to either party. Only calls in `queue_status: "started"` are eligible. Once transferred, the call record's `transferred_to` field is updated so the new number appears in call details. *** ## Headers Your API key for authentication. *** ## Body Parameters ID of the active call to transfer. Must currently be in progress. Destination phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format (for example `+12223334444`). Parsed against the US region by default, so 10-digit US numbers also work. *** ## Response Confirmation message including the `call_id` and the destination number. `null` on success. ```json Response theme={null} { "data": { "message": "Call 29f01d00-5197-4b83-bc0f-161e14533a78 transferred to +12223334444 successfully" }, "errors": null } ``` ```json Validation Error theme={null} { "data": null, "errors": [ { "error": "VALIDATION_ERROR", "message": "Call ID is required" } ] } ``` ```json Not Found theme={null} { "data": null, "errors": [ { "error": "NOT_FOUND", "message": "Call with id 29f01d00-5197-4b83-bc0f-161e14533a78 not found or has already been completed." } ] } ``` ```json Forbidden theme={null} { "data": null, "errors": [ { "error": "FORBIDDEN", "message": "Transfer blocked by international restrictions for your account type." } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Analyze Call with AI Source: https://docs.bland.ai/api-v1/post/calls-id-analyze POST https://api.bland.ai/v1/calls/{call_id}/analyze Analyzes a call of calls based using questions and goals. ### Headers Your API key for authentication. ### Path Parameters The unique identifier for the call to be analyzed. ### Request Body This is the overall purpose of the call. Provides context for the analysis to guide how the questions/transcripts are interpreted. An array of questions to be analyzed for the call. Each question should be an array with two elements: the question text and the expected answer type (e.g., "string", "boolean"). Fairly flexible in terms of the expected answer type, and unanswerable questions will default to `null`. Examples: ```json theme={null} "questions": [ ["Who answered the call?", "human or voicemail"], ["Positive feedback about the product: ", "string"], ["Negative feedback about the product: ", "string"], ["Customer confirmed they were satisfied", "boolean"] ] ``` ### Response Will be `success` if the request was successful. Confirms the request was successful, or provides an error message if the request failed. Contains the analyzed answers for the call in an array. Token-based price for the analysis request. As a rough estimate, the base cost is `0.003` credits with an additional `0.0015` credits per call in the call. Longer call transcripts and higher numbers of questions can increase the cost, however the cost scales very effectively with calls vs. individual calls. ```json theme={null} { "status": "success", "message": "Successfully analyzed call", "answers": [ "human", "Customer found the product sturdy and reliable", "A bit heavy", true ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Listen to Active Call Source: https://docs.bland.ai/api-v1/post/calls-id-listen POST https://api.bland.ai/v1/calls/{call_id}/listen Initiate a live listen session for an active call Starts a live listen session for an active call, returning a WebSocket URL for real-time audio streaming. ## Authentication Your API key for authentication ## Path Parameters The unique identifier of the call to listen to ## Prerequisites * Live listen must be enabled in organization preferences (`live_listen_enabled: true`) * Call must be in active status (not completed) * Call must belong to the authenticated organization ## Response Response status indicator WebSocket URL for connecting to the live audio stream Array of error objects if request failed ```bash cURL theme={null} curl -X POST "https://api.bland.ai/v1/calls/call_123456/listen" \ -H "Authorization: YOUR_API_KEY" ``` ```javascript JavaScript theme={null} const response = await fetch('https://api.bland.ai/v1/calls/call_123456/listen', { method: 'POST', headers: { 'Authorization': 'YOUR_API_KEY' } }); const data = await response.json(); console.log(data.data.url); // WebSocket URL ``` ```python Python theme={null} import requests url = "https://api.bland.ai/v1/calls/call_123456/listen" headers = {"Authorization": "YOUR_API_KEY"} response = requests.post(url, headers=headers) data = response.json() print(data["data"]["url"]) # WebSocket URL ``` ```json Success Response theme={null} { "status": "success", "data": { "url": "wss://api.bland.ai/ws/listen/call_123456" }, "errors": null } ``` ```json Organization Not Configured theme={null} { "status": "error", "data": null, "errors": [ { "error": "INVALID_ORG_PREFERENCES", "message": "Org preferences do not allow live listening" } ] } ``` ```json Call Not Found theme={null} { "status": "error", "data": null, "errors": [ { "error": "CALL_NOT_FOUND", "message": "Call not found" } ] } ``` ```json Call Not Active theme={null} { "status": "error", "data": null, "errors": [ { "error": "INVALID_CALL_STATUS", "message": "Call is not in progress" } ] } ``` ```json Call Not Available for Streaming theme={null} { "status": "error", "data": null, "errors": [ { "error": "CALL_NOT_FOUND", "message": "Call was either not found or not started" } ] } ``` ## WebSocket Connection After receiving the WebSocket URL, connect to it to receive real-time audio data: ### Connection Details * **URL**: Use the `url` returned in the response * **Protocol**: WebSocket (WSS) * **Binary Type**: `arraybuffer` * **Authentication**: Handled via the URL token ### Audio Data Format The WebSocket streams binary audio data with these specifications: * **Format**: PCM Int16 (16-bit signed integers) * **Sample Rate**: 16,000 Hz * **Channels**: Mono (1 channel) * **Byte Order**: Little-endian * **Data**: Combined audio from all call participants ### WebSocket Implementation Example ```javascript theme={null} // Connect to WebSocket const socket = new WebSocket(websocketUrl); socket.binaryType = 'arraybuffer'; socket.onmessage = (event) => { // Convert ArrayBuffer to Int16Array const dataView = new DataView(event.data); const int16Array = new Int16Array(dataView.byteLength / 2); for (let i = 0; i < int16Array.length; i++) { int16Array[i] = dataView.getInt16(i * 2, true); // Little-endian } // Process audio data (convert to Float32 for Web Audio API) const float32Array = new Float32Array(int16Array.length); for (let i = 0; i < int16Array.length; i++) { float32Array[i] = int16Array[i] / 32768; // Normalize to [-1, 1] } // Use audio data for playback }; socket.onclose = () => { console.log('Live listen session ended'); }; ``` ## Error Codes | Error Code | Description | | ------------------------- | ------------------------------------------------------ | | `MISSING_CALL_ID` | Call ID parameter is required | | `INVALID_ORG_PREFERENCES` | Live listen is not enabled for organization | | `CALL_NOT_FOUND` | Call does not exist or does not belong to organization | | `INVALID_CALL_STATUS` | Call is not currently active | | `INTERNAL_SERVER_ERROR` | Server error occurred | ## Notes * WebSocket connection automatically closes when the call ends * Multiple concurrent listeners can subscribe to the same call * Audio stream includes all participants in the call (combined) * The WebSocket URL can be used by multiple connections simultaneously *** Docs for agents: [llms.txt](/llms.txt) # Stop Active Call Source: https://docs.bland.ai/api-v1/post/calls-id-stop POST https://api.bland.ai/v1/calls/{call_id}/stop End an active phone call by call_id. This endpoint can also be used to cancel scheduled calls. ### Headers Your API key for authentication. ### Path Parameters The unique identifier for the call you want to end. ### Response Can be `success` or `error`. If the status is `success`, the message will say "Call ended successfully." Otherwise, if the status is `error`, the message will say "SID not found for the given c\_id." or "Internal server error." ```json theme={null} { "status": "success", "message": "Call ended successfully." } ``` *** Docs for agents: [llms.txt](/llms.txt) # Post-Transfer Transcript Stream (WebSocket) Source: https://docs.bland.ai/api-v1/post/calls-id-transcript-stream Live transcript of the conversation after a call is transferred to a human. ## Overview When a call created with `stream_post_transfer_transcript: true` is transferred to a human (cold or warm), Bland transcribes the bridged conversation live. Connect to this WebSocket to receive finalized transcript segments as the caller and the transferred-to representative speak. The stream is a real-time preview. For a durable record, subscribe with `"post_transfer_transcript"` in `webhook_events`: the [post-call webhook](/tutorials/post-call-webhooks#post-transfer-transcript) then carries the same segment format, built from the call recording after the call ends. The stream and the webhook are independent opt-ins. The post-transfer transcript stream is in limited rollout. If the [Get Transcript Stream URL endpoint](/api-v1/post/calls-id-transcript-stream-token) returns 403, it is not yet enabled for your organization. *** ## Connecting Request a connection URL from [Get Transcript Stream URL](/api-v1/post/calls-id-transcript-stream-token) and connect to it exactly as returned, within 5 minutes. The URL is opaque: it routes the connection to the server handling the call and carries the stream credential. Do not parse or reconstruct it. Connections without a valid credential for the call are closed with code `1008`. *** ## Connection Lifecycle * **Connect any time after the call is answered.** The connection URL becomes available once the call is answered; a listener that connects before the transfer starts is held and attached automatically when the transferred conversation begins. * **Join-live semantics.** A listener that connects mid-transfer receives segments from that moment forward. There is no history replay; use the post-call webhook for the complete transcript. * **Multiple listeners are allowed.** Each requests its own connection URL; all receive the same events. * **End of stream.** When the transferred conversation ends, the server sends a `stream_end` event and closes the socket with code `1000`. *** ## Events All messages are JSON text frames. ### `transcript_segment` One finalized utterance. Segments are settled text (interim results are never sent), so they arrive at natural pause boundaries, not word by word. ```json theme={null} { "event": "transcript_segment", "call_id": "9d404c1b-6a23-4b21-a7f9-64f8456ba0ec", "segment": { "start": 12.4, "end": 15.1, "speaker": 1, "speaker_label": "user", "text": "I was calling about my appointment on Thursday.", "confidence": 0.97 } } ``` Seconds from the start of the transferred conversation. End of the utterance, in the same clock as `start`. `1` for the caller, `2` for the transferred-to human. `user` for the caller, `representative` for the transferred-to human. Matches the labels in the webhook's `post_transfer_transcript`. The finalized utterance text. Transcription confidence between 0 and 1. Segments from the two speakers can arrive out of chronological order, since each speaker's speech finalizes independently. Order by `start` when rendering. ### `stream_end` The transferred conversation has ended. No further segments will arrive, and the socket closes with code `1000`. ```json theme={null} { "event": "stream_end", "call_id": "9d404c1b-6a23-4b21-a7f9-64f8456ba0ec" } ``` *** ## Implementation Example ```javascript theme={null} // 1. Get a connection URL (server-side) const res = await fetch( `https://api.bland.ai/v1/calls/${callId}/transcript-stream/token`, { method: "POST", headers: { authorization: BLAND_API_KEY } }, ); const { data } = await res.json(); // 2. Connect (safe in a browser: the URL carries only a short-lived credential) const ws = new WebSocket(data.url); ws.onmessage = (event) => { const msg = JSON.parse(event.data); if (msg.event === "transcript_segment") { const s = msg.segment; console.log(`[${s.start}s] ${s.speaker_label}: ${s.text}`); } else if (msg.event === "stream_end") { console.log("Transfer ended"); } }; ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Transcript Stream URL Source: https://docs.bland.ai/api-v1/post/calls-id-transcript-stream-token POST https://api.bland.ai/v1/calls/{call_id}/transcript-stream/token Get a short-lived, ready-to-connect WebSocket URL for a call's live post-transfer transcript stream. ## Overview Returns a short-lived, ready-to-connect WebSocket URL for the call's [post-transfer transcript stream](/api-v1/post/calls-id-transcript-stream). Use this from your backend so browser clients never see your long-lived API key; the returned URL carries only a 5-minute credential scoped to this one call. The URL is opaque — connect to it exactly as returned. Do not parse it or construct your own. The URL becomes available when the call is answered (that is when the server handling the call is assigned). Until then this endpoint returns 404 with `CALL_NOT_FOUND` ("Call was either not found or not started" — the same response as [Listen to Active Call](/api-v1/post/calls-id-listen)); poll every second or two after placing the call. Once connected, you can hold the socket through the rest of the call — it parks until the transfer starts. The post-transfer transcript stream is in limited rollout. If this endpoint returns 403 with `FEATURE_NOT_ENABLED`, it is not yet enabled for your organization. *** ## Headers Your API key for authentication. *** ## Path Parameters The call whose post-transfer transcript you want to stream. The call must have been created with `stream_post_transfer_transcript: true`. *** ## Body Parameters This endpoint takes no body. POST an empty body or `{}`. *** ## Response Opaque WebSocket URL. Connect to it as returned, within 5 minutes. Lifetime of the URL's embedded credential. Currently `300` (5 minutes). The TTL gates the connection handshake only; an established stream is not closed when it expires. `null` on success. `401` when the call belongs to a different organization, `403` when the feature is not enabled for your organization, `404` with `CALL_NOT_FOUND` when the call does not exist or has no active transcript stream (not created with `stream_post_transfer_transcript`, not yet answered, or already ended). ```bash cURL theme={null} curl -X POST "https://api.bland.ai/v1/calls/{call_id}/transcript-stream/token" \ -H "authorization: YOUR_API_KEY" ``` ```json Response theme={null} { "data": { "url": "wss://stream.aws.dc8.bland.ai/ws/transcript-stream/eyJhbGciOiJBMjU2R0NNS1ci...?token=eyJhbGciOiJIUzI1NiIs...", "expires_in_seconds": 300 }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Send Call With Task (Simple) Source: https://docs.bland.ai/api-v1/post/calls-simple POST https://us.api.bland.ai/v1/calls Send an AI phone call using a task. ### Headers A valid Bland API key, located in the [organization portal](https://app.bland.ai/dashboard/settings). ### Body The phone number to call. Must be a valid phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. The task to use for the call. This is a prompt that tells the AI background information, expected behavior, and relevant information. ### Response Can be `success` or `error`. A unique identifier for the call (present only if status is `success`). ```json Response theme={null} { "status": "success", "call_id": "9d404c1b-6a23-4426-953a-a52c392ff8f1" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Send Call using Pathways (Simple) Source: https://docs.bland.ai/api-v1/post/calls-simple-pathway POST https://api.bland.ai/v1/calls Send an AI phone call with your own conversational pathway agent! Links - [Video Tutorial](https://www.loom.com/share/5ce5a84ec97149efad7cf5eff66a93c5?sid=697dc436-53cf-494c-a3e9-a25031df6496) | [Step-by-step web tutorial](https://docs.bland.ai/tutorials/pathways) ### Headers Your API key for authentication. ### Body The phone number to call. Country code defaults to `+1` (US) if not specified. Formatting is flexible, however for the most predictable results use the [E.164](https://www.twilio.com/docs/glossary/what-e164#examples-of-e164-numbers) format. Expected/Ideal Format: * "+12223334444" * "+91223334444" * "+61223334444" Valid, but not recommended: * "2223334444" * "+1 (222) 333-4444" * "+1 222 333 4444" * "222-333-4444" Invalid: * "12223334444" * "552223334444" * "non-numeric characters" * "2223334444 ext. 123" Follows the conversational pathway you created to guide the conversation. You can access your pathway\_id by clicking on the 'Copy ID' button on your pathways [here](https://app.bland.ai/home?page=convo-pathways). If you don't have any pathways, click the 'Create Pathway' button to create one! [Video tutorial](https://www.loom.com/share/5ce5a84ec97149efad7cf5eff66a93c5?sid=697dc436-53cf-494c-a3e9-a25031df6496) [Step by step Web Tutorial](https://docs.bland.ai/tutorials/pathways) ### Response Can be `success` or `error`. A unique identifier for the call (present only if status is `success`). ```json Response theme={null} { "status": "success", "call_id": "9d404c1b-6a23-4426-953a-a52c392ff8f1" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Citation Schema Source: https://docs.bland.ai/api-v1/post/citation-schemas POST https://api.bland.ai/v1/citation_schemas/ Create a new citation schema for extracting structured data from call transcripts. ## Overview Create a citation schema to define what data should be extracted from call transcripts. Citation schemas allow you to automatically capture structured information like customer details, call outcomes, or any custom variables relevant to your use case. *** ### Headers Your API key for authentication. ### Body Parameters The name of the citation schema. This should be descriptive and help you identify the schema's purpose. An optional description explaining what this schema extracts and its intended use case. The JSON schema configuration that defines variables, groupings, and conditions for citation extraction. If not provided, an empty schema will be created that can be configured later. The schema object can contain: * `variables`: Array of variable definitions for data extraction * `groupings`: Array of related variable collections * `conditions`: Array of conditional logic rules that trigger additional variable extraction Example structure: ```json theme={null} { "variables": [ { "name": "Customer Name", "description": "The full name of the customer", "type": "string" }, { "name": "Customer Email", "description": "The customer's email address", "type": "string" }, { "name": "Customer Age", "description": "The customer's age in years", "type": "number" }, { "name": "Interested in Demo", "description": "Whether the customer wants to schedule a demo", "type": "boolean" } ], "groupings": [ { "name": "Contact Information", "variables": [ "Customer Name", "Customer Email" ], "description": "The customer's contact details" }, { "name": "Demographics", "variables": [ "Customer Age" ], "description": "The customer's demographic information" } ], "conditions": [ { "condition": { "value": "true", "operator": "===", "variable": "Interested in Demo" }, "variables": [ { "name": "Demo Preference", "type": "string", "description": "Type of demo preferred (in-person, virtual, etc.)" } ] } ] } ``` ### Response HTTP status code (200 for success). The created citation schema object. The unique identifier for the created citation schema (UUID format). The name of the citation schema. The description of the citation schema. The organization ID that owns this schema. The JSON schema configuration for citation extraction. The timestamp when the citation schema was created (ISO 8601 format). Will be null for successful requests. ### Error Responses Returned when the required `name` parameter is missing. ```json Response theme={null} { "status": 200, "data": { "id": "6ba7b812-9dad-11d1-80b4-00c04fd430c8", "name": "Customer Information Extraction", "description": "Extracts customer demographics and contact information from call transcripts", "org_id": "9b59f853-c2c7-4e3a-b5d6-8f7e9a1b2c3d", "schema": { "variables": [ { "name": "Customer Name", "description": "The full name of the customer", "type": "string" }, { "name": "Customer Email", "description": "The email address provided by the customer", "type": "string" }, { "name": "Interested in Demo", "description": "Whether the customer wants to schedule a demo", "type": "boolean" } ], "groupings": [ { "name": "Contact Information", "variables": ["Customer Name", "Customer Email"] } ], "conditions": [ { "condition": { "value": "true", "operator": "===", "variable": "Interested in Demo" }, "variables": [ { "name": "Demo Preference", "type": "string", "description": "Type of demo the customer prefers (in-person, virtual, etc.)" } ] } ] }, "created_at": "2023-12-15T14:30:00.000Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Backfill Citation Schema Source: https://docs.bland.ai/api-v1/post/citation-schemas-backfill POST https://api.bland.ai/v1/citation_schemas/backfill Retroactively apply one or more citation schemas to extract data from existing call transcripts. ## Overview The backfill endpoint allows you to apply citation schemas to calls and SMS conversations that have already been completed. This is useful when you: * Create a new schema and want to extract data from historical calls or conversations * Need to re-analyze calls or conversations with updated schemas * Want to extract data from multiple calls or conversations at scale Call backfill operations are **asynchronous** — you'll receive a `workflow_id` immediately and can poll the status endpoint to check progress. SMS conversation backfill is **synchronous** — results are returned directly in the response. This is an **Enterprise-only feature**. Contact your Bland representative or reach out to sales to enable this functionality. Backfilling will update citation variables for the specified call(s) and schema(s). Variables are merged with existing data - only the variables defined in the schema being backfilled will be updated. *** ## Request ### Headers Your API key for authentication. ### Body Parameters #### Schema Parameters (Choose One) A single citation schema ID from your organization to apply to the call(s). An array of citation schema IDs to apply to the call(s). All schemas will be processed for each call. **Note**: Cannot be combined with `schema` (inline schema). An inline citation schema definition. Useful for one-time analysis without creating a schema in your account. Can be combined with `call_id`/`call_ids` or `conversation_id`/`conversation_ids` for multi-call or multi-conversation analysis. **Note**: Cannot be combined with `schema_ids`. #### Call Parameters A single call ID to analyze with the specified schema(s). An array of call IDs to analyze with the specified schema(s). All schemas will be applied to each call. #### SMS Conversation Parameters A single SMS conversation ID to analyze with the specified schema(s). Processed synchronously. An array of SMS conversation IDs to analyze. Maximum 50 conversations per request. All schemas will be applied to each conversation. Processed synchronously. *** ## Response Returns `202 Accepted` when calls are included (async processing), or `200 OK` when only SMS conversations are included (sync processing). `"processing"` when calls are being processed asynchronously, or `"complete"` when only SMS conversations were processed. Unique identifier for the call backfill workflow. Only present when calls are included. Use this to check status and retrieve results. Number of calls being processed. Number of SMS conversations processed. Number of schemas being applied. Total number of call+schema extractions that will be performed (`call_count × schema_count`). Only present when calls are included. Results for SMS conversation backfill. Only present when conversations are included. Each entry contains: * `conversation_id` — the conversation that was analyzed * `status` — `"success"`, `"skipped"`, or `"error"` * `variables_extracted` — count of unique variable names extracted across all schemas (same definition as `result.calls[].variables_extracted_count`) * `previous_variables` — the conversation's citation variables **before** this backfill operation * `newly_extracted_variables` — variables that were extracted or updated by **this backfill** operation * `final_variables` — the conversation's citation variables **after** this backfill operation (complete merged state) * `error` — error message if the extraction failed Instructions on how to check the status of the call workflow. *** ## Checking Status Use the workflow ID to poll the status endpoint: ```bash theme={null} GET https://api.bland.ai/v1/citation_schemas/backfill/status/{workflow_id} ``` ### Status Response The workflow ID you're querying. Current workflow status: * `RUNNING`: Still processing * `COMPLETED`: Finished successfully (may have partial failures) * `FAILED`: Workflow encountered an error * `TERMINATED`: Manually stopped * `TIMED_OUT`: Exceeded maximum execution time Only present when `status` is `COMPLETED`. Contains the full backfill results. ### Result Object (When Completed) Overall result status: * `success`: All extractions succeeded * `partial`: Some extractions succeeded, some failed * `failed`: All extractions failed Array of results, one entry per call processed. The call that was analyzed. Status for this call: `success`, `partial`, or `failed`. Details about each schema extraction for this call. Total number of unique variables extracted across all schemas for this call. The call's citation variables **before** this backfill operation. Variables that were extracted or updated by **this backfill** operation. The call's citation variables **after** this backfill operation (complete state). Aggregate statistics across all calls and schemas: * `total_calls`: Number of calls processed * `successful_calls`: Calls where all schemas succeeded * `partial_calls`: Calls where some schemas failed * `failed_calls`: Calls where all schemas failed * `total_schemas_processed`: Total schema extractions attempted * `successful_schema_extractions`: Schema extractions that succeeded * `failed_schema_extractions`: Schema extractions that failed *** ## Usage Flow 1. **Send backfill request** and receive `workflow_id` 2. **Poll the status endpoint** periodically (every 5-10 seconds) 3. **When status is `COMPLETED`**, retrieve results from `result` field 4. **Review the results** to see what was extracted for each call *** ## Examples ### Single Call, Single Schema ```bash Request theme={null} curl -X POST https://api.bland.ai/v1/citation_schemas/backfill \ -H "authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "call_id": "call-123", "schema_id": "schema-abc" }' ``` ```json Response (202 Accepted) theme={null} { "status": "processing", "workflow_id": "backfill:call-123:1760635265843", "call_count": 1, "schema_count": 1, "total_combinations": 1, "message": "Citation backfill workflow started for 1 call(s) with 1 schema(s)..." } ``` ### Multiple Calls, Multiple Schemas ```bash Request theme={null} curl -X POST https://api.bland.ai/v1/citation_schemas/backfill \ -H "authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "call_ids": ["call-123", "call-456", "call-789"], "schema_ids": ["schema-abc", "schema-def"] }' ``` ```json Response (202 Accepted) theme={null} { "status": "processing", "workflow_id": "backfill:batch:671b7623-f9ac-46db-95f1-9b504fe59a06:1760635265843", "call_count": 3, "schema_count": 2, "total_combinations": 6, "message": "Citation backfill workflow started for 3 call(s) with 2 schema(s)..." } ``` ### SMS Conversations ```bash Request theme={null} curl -X POST https://api.bland.ai/v1/citation_schemas/backfill \ -H "authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "conversation_ids": ["conv-123", "conv-456"], "schema_id": "schema-abc" }' ``` ```json Response (200 OK) theme={null} { "status": "complete", "call_count": 0, "conversation_count": 2, "schema_count": 1, "conversations": [ { "conversation_id": "conv-123", "status": "success", "variables_extracted": 2, "previous_variables": { "customer_name": "Jane" }, "newly_extracted_variables": { "intent": "support", "resolved": true }, "final_variables": { "customer_name": "Jane", "intent": "support", "resolved": true } }, { "conversation_id": "conv-456", "status": "success", "variables_extracted": 2, "previous_variables": {}, "newly_extracted_variables": { "intent": "billing", "resolved": false }, "final_variables": { "intent": "billing", "resolved": false } } ] } ``` ### Single Call with Inline Schema ```bash Request theme={null} curl -X POST https://api.bland.ai/v1/citation_schemas/backfill \ -H "authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "call_id": "call-123", "schema": { "name": "Customer Sentiment Analysis", "variables": [ { "name": "customer_satisfied", "type": "boolean", "description": "Whether the customer expressed satisfaction" }, { "name": "sentiment_score", "type": "number", "description": "Overall sentiment from -1 (negative) to 1 (positive)" } ] } }' ``` ### Checking Status ```bash Request theme={null} curl https://api.bland.ai/v1/citation_schemas/backfill/status/backfill:call-123:1760635265843 \ -H "authorization: YOUR_API_KEY" ``` ```json Response (Status: RUNNING) theme={null} { "workflow_id": "backfill:call-123:1760635265843", "status": "RUNNING", "run_id": "0199ee0a-2343-7d98-8fbb-8d5c2d46ed4c", "start_time": "2025-10-16T17:21:05.859Z" } ``` ```json Response (Status: COMPLETED) theme={null} { "workflow_id": "backfill:call-123:1760635265843", "status": "COMPLETED", "run_id": "0199ee0a-2343-7d98-8fbb-8d5c2d46ed4c", "start_time": "2025-10-16T17:21:05.859Z", "close_time": "2025-10-16T17:21:39.019Z", "result": { "status": "success", "calls": [ { "call_id": "call-123", "status": "success", "schemas_processed": [ { "schema_id": "schema-abc", "status": "success", "variables_extracted": 5 } ], "variables_extracted_count": 5, "previous_variables": { "customer_name": "John Doe" }, "newly_extracted_variables": { "order_id": "ORD-789456", "issue_type": "shipping", "products": [ { "name": "Wireless Headphones", "issue": "damaged packaging", "quantity": 1 } ], "customer_satisfied": true, "resolution": "refund_issued" }, "final_variables": { "customer_name": "John Doe", "order_id": "ORD-789456", "issue_type": "shipping", "products": [ { "name": "Wireless Headphones", "issue": "damaged packaging", "quantity": 1 } ], "customer_satisfied": true, "resolution": "refund_issued" } } ], "summary": { "total_calls": 1, "successful_calls": 1, "partial_calls": 0, "failed_calls": 0, "total_schemas_processed": 1, "successful_schema_extractions": 1, "failed_schema_extractions": 0 } } } ``` *** ## Error Responses ### 400 Bad Request Returned when: * No schema parameter provided (`schema_id`, `schema_ids`, or `schema` required) * No identifier parameter provided (`call_id`, `call_ids`, `conversation_id`, `conversation_ids`, or `recording_url` required) * Invalid parameter combinations (e.g., `schema_ids` with inline `schema`) * Empty arrays provided * More than 50 SMS conversations in a single request ### 403 Forbidden Returned when: * Account does not have enterprise features enabled * Attempting to access another organization's calls, conversations, or schemas ### 404 Not Found Returned when: * Specified call ID(s) not found * Specified schema ID(s) not found * Resources don't belong to your organization * None of the provided `schema_id`/`schema_ids` can be resolved (error code: `NO_RESOLVABLE_SCHEMAS`) ### 500 Internal Server Error Returned when an unexpected error occurs starting the workflow. *** ## Best Practices ### Polling Strategy * Poll every **5-10 seconds** for single-call operations * Poll every **10-30 seconds** for batch operations * Implement exponential backoff if polling for extended periods * Stop polling once status is `COMPLETED`, `FAILED`, `TERMINATED`, or `TIMED_OUT` ### Batch Processing * Process up to **100 calls** at once for optimal performance * For larger batches, split into multiple backfill requests * Use multiple schemas in a single request rather than separate requests per schema ### Error Handling * Check the `result.calls[].status` field for per-call results * Review `schemas_processed` array to see which schemas succeeded/failed * Use `error_summary` field for quick diagnosis of partial failures * Failed extractions don't prevent successful ones from being stored ### Variable Management * **Newly extracted variables** overwrite previous values with the same name * Variables from different schemas are merged together * Only variables defined in the backfilled schema are updated * Other existing variables remain unchanged *** Docs for agents: [llms.txt](/llms.txt) # Clone Voice Source: https://docs.bland.ai/api-v1/post/clone POST https://api.bland.ai/v1/voices/clone Create a custom voice clone from audio samples. ## Overview Creates a Bland TTS voice clone from one or more audio samples. Sent as `multipart/form-data`. The new voice is private to your org and immediately usable with [Speak](/api-v2/post/tts). Two cloning engines are available, selectable per request: * **BTTS V3** (default), single 10-second sample, 17+ languages, highest fidelity. Returned `service: "BTTS_V3"`. * **BTTS V2**, exactly 1 WAV file, 17+ languages. Returned `service: "BTTS_V2"`. *** ## Headers Your API key for authentication. *** ## Form Fields Display name for the voice clone. 1-30 characters. Must be unique in your library. Audio file or files. Constraints depend on the engine flag (see below). WAV format recommended. `male` or `female`. Optional but recommended; helps the underlying model. Free-text description. Surfaced as additional context to the model for tone and style. Use the V3 engine. Default if no engine flag is set. Pass `"true"` as a multipart string. Use the V2 engine instead of V3. Pass `"true"` as a multipart string. *** ## Engine constraints Each engine validates `audio_samples` differently. Mismatched files will return a `Validation Error` before the clone is created. * Exactly 1 audio file. * Roughly 10 seconds is ideal. * Max 10 MB. * 17+ languages supported. * Exactly 1 audio file. * Roughly 10 seconds is ideal. * Max 10 MB. * 17+ languages supported. *** ## Response Returns `200 OK` with the new voice on success. UUID of the new voice clone. Use it as `voice_id` in [Speak](/api-v2/post/tts). The display name you provided. `null` on success. ```json Response theme={null} { "status": 200, "data": { "voice_id": "4cc89edf-c4b7-4df8-98c5-f8548fcd7c62", "name": "DocTestClone" }, "errors": null } ``` ```json Validation Error theme={null} { "status": 400, "data": null, "errors": [ { "error": "Validation Error", "message": "No files provided for voice cloning." } ] } ``` ```json Voice Limit Exceeded theme={null} { "status": 400, "data": null, "errors": [ { "error": "Limit Exceeded", "message": "You have reached the maximum number of voices for your plan." } ] } ``` *** V2 and V3 voices are single-sample by design. Use [List Voice Samples](/api-v1/get/voices-id-samples) to inspect the source sample attached to a voice. *** Docs for agents: [llms.txt](/llms.txt) # Merge Contacts Source: https://docs.bland.ai/api-v1/post/contacts-merge POST https://api.bland.ai/v1/contacts/merge Merge two contacts into one. All data from the duplicate contact is moved to the primary contact, and the duplicate is deleted. ### Headers Your API key for authentication. ### Body Parameters The ID of the contact that will remain after the merge. Data from the duplicate will be merged into this contact. The ID of the contact to merge and delete. All associated data (calls, conversations, memory) will be transferred to the primary contact. ### Response The merged contact object. Unique identifier for the merged contact (same as primary\_contact\_id). Organization ID the contact belongs to. Contact's name (prefers primary, falls back to duplicate if primary is empty). Merged metadata from both contacts (primary takes precedence for conflicting keys). ISO timestamp when the contact was created. ISO timestamp when the contact was last updated. Error array (null on success). ### Merge Behavior When merging contacts: * **Identifiers**: All phone numbers, emails, and external IDs from the duplicate are added to the primary contact * **Metadata**: Metadata objects are merged, with primary contact values taking precedence for conflicting keys * **Name**: The primary contact's name is kept, unless it's empty (then the duplicate's name is used) * **Calls**: All calls associated with the duplicate are reassigned to the primary contact * **SMS Conversations**: All SMS conversations are reassigned to the primary contact * **Contact Memory**: Memory data is merged (facts, recent messages, summaries) for each persona/agent. If both contacts have memory for the same persona, the data is intelligently combined ```json Response theme={null} { "data": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "org_id": "11111111-2222-3333-4444-555555555555", "name": "John Doe", "metadata": { "source": "web_signup", "phone_verified": true, "email_verified": true }, "created_at": "2025-07-20T10:30:00.000Z", "updated_at": "2025-07-22T16:30:00.000Z" }, "errors": null } ``` ```json Error - Same Contact theme={null} { "data": null, "errors": [ { "error": "BAD_REQUEST", "message": "Cannot merge a contact with itself" } ] } ``` ```json Error - Different Orgs theme={null} { "data": null, "errors": [ { "error": "BAD_REQUEST", "message": "Cannot merge contacts from different orgs" } ] } ``` ```json Not Found theme={null} { "data": null, "errors": [ { "error": "NOT_FOUND", "message": "Contact not found" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Resolve Contact Source: https://docs.bland.ai/api-v1/post/contacts-resolve POST https://api.bland.ai/v1/contacts/resolve Find an existing contact or create a new one. ### Headers Your API key for authentication. ### Body Parameters Phone number for the contact. At least one identifier is required. Email address for the contact. At least one identifier is required. External ID for the contact. At least one identifier is required. Name of the contact. Persona ID for memory scoping. Either `persona_id` or `agent_number` should be provided for memory creation. Agent phone number for memory scoping. Either `persona_id` or `agent_number` should be provided for memory creation. Custom metadata to associate with the contact. ### Response Response containing the contact and creation status. The resolved contact object. Unique identifier for the contact. Organization ID the contact belongs to. Contact's name (if set). Custom metadata associated with the contact. ISO timestamp when the contact was created. ISO timestamp when the contact was last updated. Whether a new contact was created (true) or an existing one was found (false). Error array (null on success). ```json New Contact Created theme={null} { "data": { "contact": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "org_id": "11111111-2222-3333-4444-555555555555", "name": "John Doe", "metadata": { "source": "api" }, "created_at": "2025-07-22T10:30:00.000Z", "updated_at": "2025-07-22T10:30:00.000Z" }, "created": true }, "errors": null } ``` ```json Existing Contact Found theme={null} { "data": { "contact": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "org_id": "11111111-2222-3333-4444-555555555555", "name": "John Doe", "metadata": { "source": "web_signup" }, "created_at": "2025-07-20T10:30:00.000Z", "updated_at": "2025-07-22T15:45:00.000Z" }, "created": false }, "errors": null } ``` ```json Error Response theme={null} { "data": null, "errors": [ { "error": "BAD_REQUEST", "message": "At least one identifier (phone_number, email, or external_id) is required" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Folder Source: https://docs.bland.ai/api-v1/post/create_pathway_folder POST https://us.api.bland.ai/v1/pathway/folders Creates a new folder for the authenticated user. ### Headers Your API key for authentication. ### Body Parameters The name of the new folder. The ID of the parent folder, if creating a subfolder. ### Response The unique identifier of the newly created folder. The name of the newly created folder. The ID of the parent folder, if applicable. ```json Response theme={null} { "folder_id": "new_folder_123", "name": "New Folder", "parent_folder_id": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Pathway Version Source: https://docs.bland.ai/api-v1/post/create_pathway_version POST https://api.bland.ai/v1/pathway/{pathway_id}/version Creates a new version of a specific pathway, including its name, nodes, and edges. ### Headers Your API key for authentication. ### Path Parameters The ID of the pathway for which to create a new version. ### Request Body The name of the new pathway version. An array of node objects defining the structure of the pathway. * `id` — Unique identifier of the node * `type` — Type of the node (e.g., "Default", "End Call", "Webhook") * `data` — Object containing node-specific data * `name` — Name of the node * `text` or `prompt` — Text or prompt associated with the node * Other properties specific to the node type An array of edge objects defining the connections between nodes. * `id` — Unique identifier of the edge * `source` — ID of the source node * `target` — ID of the target node * `label` — Label for this edge ### Response The status of the operation (e.g., "success"). A message describing the result of the operation. The timestamp when the new version was created. The unique identifier of the newly created version. The name of the newly created version. The version number of the newly created version. ```json Response theme={null} { "status": "success", "message": "Version created successfully", "data": { "created_at": "2024-03-07T10:15:30Z", "id": "v3_ghi789", "name": "Improved Customer Flow", "version_number": 3 } } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Custom Dialing Pool Source: https://docs.bland.ai/api-v1/post/custom-dialing-pool-update POST https://us.api.bland.ai/v1/custom-dialing-pools/{pool_id}/update Update an existing custom dialing pool with new phone numbers or credentials. **Enterprise Feature** - Custom dialing is only available on Enterprise plans. Contact your Bland representative for access. Update an existing custom dialing pool by replacing its phone numbers and/or Twilio credentials. This operation will completely replace the existing phone numbers with the new ones provided. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the custom dialing pool to update. **Format**: UUID format (e.g., `550e8400-e29b-41d4-a716-446655440000`) ### Body Array of phone numbers to replace the existing numbers in the pool. All numbers must be valid US phone numbers with +1 prefix. **Format**: Each phone number must be exactly 12 characters: `+1` followed by 10 digits. **Example**: `["+12345678901", "+19876543210"]` This will completely replace all existing phone numbers in the pool. Any numbers not included in this array will be removed. Optional UUID of Twilio credentials to associate with this pool. If provided, must be valid credentials that belong to your account. To remove credentials, pass `null`. **Format**: UUID format (e.g., `550e8400-e29b-41d4-a716-446655440000`) or `null` Learn more about BYOT [here](/tutorials/custom-twilio). ### Response Can be `success` or `error`. The updated custom dialing pool object (present only if status is `success`). Unique identifier for the pool. Organization ID that owns this pool. Array of phone numbers in the pool (updated). UUID of associated Twilio credentials (or null if none). Timestamp when the pool was created. Array of error objects (present only if status is `error`). Error code indicating the type of error. Human-readable error message. ```bash cURL theme={null} curl -X POST "https://us.api.bland.ai/v1/custom-dialing-pools/550e8400-e29b-41d4-a716-446655440001/update" \ -H "Authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone_numbers": ["+12345678901", "+19876543210", "+15551234567", "+17775551234"], "encrypted_key": "550e8400-e29b-41d4-a716-446655440000" }' ``` ```javascript JavaScript theme={null} const poolId = '550e8400-e29b-41d4-a716-446655440001'; const response = await fetch(`https://us.api.bland.ai/v1/custom-dialing-pools/${poolId}/update`, { method: 'POST', headers: { 'Authorization': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ phone_numbers: ['+12345678901', '+19876543210', '+15551234567', '+17775551234'], encrypted_key: '550e8400-e29b-41d4-a716-446655440000' }) }); const data = await response.json(); console.log(data); ``` ```python Python theme={null} import requests pool_id = "550e8400-e29b-41d4-a716-446655440001" url = f"https://us.api.bland.ai/v1/custom-dialing-pools/{pool_id}/update" headers = { "Authorization": "YOUR_API_KEY", "Content-Type": "application/json" } data = { "phone_numbers": ["+12345678901", "+19876543210", "+15551234567", "+17775551234"], "encrypted_key": "550e8400-e29b-41d4-a716-446655440000" } response = requests.post(url, headers=headers, json=data) print(response.json()) ``` ```json Success Response theme={null} { "status": "success", "data": { "id": "550e8400-e29b-41d4-a716-446655440001", "owner_id": "550e8400-e29b-41d4-a716-446655440002", "phone_numbers": ["+12345678901", "+19876543210", "+15551234567", "+17775551234"], "encrypted_key": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2024-01-15T10:30:00Z" }, "errors": null } ``` ```json Error Response - Pool Not Found theme={null} { "status": "error", "data": null, "errors": [ { "error": "POOL_NOT_FOUND", "message": "Geospatial dialing pool not found" } ] } ``` ```json Error Response - Invalid Phone Numbers theme={null} { "status": "error", "data": null, "errors": [ { "error": "INVALID_PHONE_NUMBERS", "message": "All phone numbers must be valid US numbers with +1 prefix" } ] } ``` ```json Error Response - Invalid Credentials theme={null} { "status": "error", "data": null, "errors": [ { "error": "INVALID_CREDENTIALS", "message": "Twilio credentials not found or do not belong to your account" } ] } ``` ## Removing Credentials To remove Twilio credentials from a pool, set `encrypted_key` to `null`: ```json theme={null} { "phone_numbers": ["+12345678901", "+19876543210"], "encrypted_key": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Custom Dialing Pool Source: https://docs.bland.ai/api-v1/post/custom-dialing-pools POST https://us.api.bland.ai/v1/custom-dialing-pools Create a new custom dialing pool with phone numbers for optimized call routing. **Enterprise Feature** - Custom dialing is only available on Enterprise plans. Contact your Bland representative for access. Custom dialing pools allow you to create collections of phone numbers that will be automatically selected based on geographic proximity to optimize call pickup rates. ### Headers Your API key for authentication. ### Body Array of phone numbers to include in the pool. All numbers must be valid US phone numbers with +1 prefix. **Format**: Each phone number must be exactly 12 characters: `+1` followed by 10 digits. **Example**: `["+12345678901", "+19876543210"]` Optional UUID of Twilio credentials to associate with this pool. If provided, must be valid credentials that belong to your account. **Format**: UUID format (e.g., `550e8400-e29b-41d4-a716-446655440000`) Learn more about BYOT [here](/tutorials/custom-twilio). ### Response Can be `success` or `error`. The created custom dialing pool object (present only if status is `success`). Unique identifier for the pool. Organization ID that owns this pool. Array of phone numbers in the pool. UUID of associated Twilio credentials (or null if none). Timestamp when the pool was created. Array of error objects (present only if status is `error`). Error code indicating the type of error. Human-readable error message. ```bash cURL theme={null} curl -X POST "https://us.api.bland.ai/v1/custom-dialing-pools" \ -H "Authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone_numbers": ["+12345678901", "+19876543210", "+15551234567"], "encrypted_key": "550e8400-e29b-41d4-a716-446655440000" }' ``` ```javascript JavaScript theme={null} const response = await fetch('https://us.api.bland.ai/v1/custom-dialing-pools', { method: 'POST', headers: { 'Authorization': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ phone_numbers: ['+12345678901', '+19876543210', '+15551234567'], encrypted_key: '550e8400-e29b-41d4-a716-446655440000' }) }); const data = await response.json(); console.log(data); ``` ```python Python theme={null} import requests url = "https://us.api.bland.ai/v1/custom-dialing-pools" headers = { "Authorization": "YOUR_API_KEY", "Content-Type": "application/json" } data = { "phone_numbers": ["+12345678901", "+19876543210", "+15551234567"], "encrypted_key": "550e8400-e29b-41d4-a716-446655440000" } response = requests.post(url, headers=headers, json=data) print(response.json()) ``` ```json Success Response theme={null} { "status": "success", "data": { "id": "550e8400-e29b-41d4-a716-446655440001", "owner_id": "550e8400-e29b-41d4-a716-446655440002", "phone_numbers": ["+12345678901", "+19876543210", "+15551234567"], "encrypted_key": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2024-01-15T10:30:00Z" }, "errors": null } ``` ```json Error Response - Invalid Phone Numbers theme={null} { "status": "error", "data": null, "errors": [ { "error": "INVALID_PHONE_NUMBERS", "message": "All phone numbers must be valid US numbers with +1 prefix" } ] } ``` ```json Error Response - Invalid Credentials theme={null} { "status": "error", "data": null, "errors": [ { "error": "INVALID_CREDENTIALS", "message": "Twilio credentials not found or do not belong to your account" } ] } ``` ## Usage with Calls Once you've created a custom dialing pool, you can use it in your call requests by specifying the `custom_dialing` parameter: ```json theme={null} { "phone_number": "+12345678901", "task": "Your call task here", "custom_dialing": "550e8400-e29b-41d4-a716-446655440001" } ``` ## The system will automatically select the most geographically appropriate phone number from your pool to maximize pickup rates. Docs for agents: [llms.txt](/llms.txt) # Delete Pathway Source: https://docs.bland.ai/api-v1/post/delete_pathway DELETE https://api.bland.ai/v1/pathway/{pathway_id} Delete your conversational pathway. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the conversational pathway you want to delete. ### Response Can be `success` or `error`. A unique identifier for the pathway (present only if status is `success`). ```json Response theme={null} { "status": "success", "message": "Pathway deleted successfully" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Eval Agent Source: https://docs.bland.ai/api-v1/post/evals-agents POST https://api.bland.ai/v1/evals/agents Create a new eval agent, optionally seeded from a template. ### Headers Your API key for authentication. ### Body Parameters Display name for the eval agent. Between 1 and 200 characters. Optional description of what the eval agent grades. Key of a shipped template to seed the agent from. ID of a saved user template to seed the agent from. The modality for the eval agent. One of `text` or `audio`. `template_key` and `user_template_id` are mutually exclusive. If both are provided, `user_template_id` wins. ### Response The newly created eval agent. Unique identifier for the eval agent. ID of the organization that owns this eval agent. Unique slug key for the eval agent within the organization. Display name of the eval agent. Optional description of what the eval agent grades. ID of the current editable draft version. ID of the published version, or `null` if never published. Key-value metadata associated with the eval agent. Values are strings. ISO 8601 timestamp for when the eval agent was created. ISO 8601 timestamp for when the eval agent was last updated. ISO 8601 timestamp if the eval agent has been soft-deleted, otherwise `null`. The editable draft version created alongside the agent. Unique identifier for this version. ID of the organization that owns this version. ID of the parent eval agent. Sequential version number. Name of this version. Optional description of this version. Always `"editable"` for a newly created draft. One of `text` or `audio`. The system prompt for the judge LLM, in Markdown. The grading prompt for the judge LLM, in Markdown. Verdict levels for graded mode. Empty array for pass/fail mode. Each level contains `level_key`, `label`, `prompt_md`, and optionally `color`. Which level keys count as a target match. Empty array for pass/fail agents. Relative weight of this agent in aggregate scoring. Between 0 and 100. ID of the version this was forked from, or `null` if this is the first version. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. ISO 8601 timestamp for when this version was last updated. ```json Response theme={null} { "errors": null, "data": { "agent": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "org_id": "f0e1d2c3-b4a5-9678-fedc-ba9876543210", "key": "empathy-check", "name": "Empathy Check", "description": "Grades how empathetic the agent sounds during difficult conversations.", "current_version_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "active_version_id": null, "metadata": {}, "created_at": "2026-05-27T10:00:00.000Z", "updated_at": "2026-05-27T10:00:00.000Z", "deleted_at": null }, "current_version": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "org_id": "f0e1d2c3-b4a5-9678-fedc-ba9876543210", "eval_agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 1, "name": "Empathy Check v1", "description": null, "state": "editable", "modality": "audio", "system_prompt_md": "You are an expert call quality reviewer.", "prompt_md": "Did the agent express empathy when the caller described their problem?", "levels": [ { "level_key": "excellent", "label": "Excellent", "prompt_md": "The agent clearly and warmly acknowledged the caller's feelings.", "color": "emerald" }, { "level_key": "poor", "label": "Poor", "prompt_md": "The agent ignored or dismissed the caller's feelings.", "color": "rose" } ], "target_level_keys": ["excellent"], "weight": 10, "created_from_version_id": null, "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-27T10:00:00.000Z", "updated_at": "2026-05-27T10:00:00.000Z" } } } ``` # Publish Eval Agent Source: https://docs.bland.ai/api-v1/post/evals-agents-id-publish POST https://api.bland.ai/v1/evals/agents/{eval_agent_id}/publications Publish the agent's current draft as a new active version. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the eval agent to publish. Publishing validates the draft before snapshotting it. A graded agent must have between 2 and 5 levels, and every key in `target_level_keys` must match a defined level. A pass/fail agent must have 0 levels and no target level keys set. ### Response ID of the eval agent that was published. ID of the new editable draft created after publishing. ID of the newly published (archived) version. Summary of the version that was published. Unique identifier of the published version. ID of the parent eval agent. Sequential version number of the published version. Name of the published version. Always `"archived"` for a published version. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. Summary of the most recent run against this version, or `null` if no runs exist. ```json Response theme={null} { "errors": null, "data": { "eval_agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "current_version_id": "e5f6a7b8-c9d0-1234-efab-567890123456", "active_version_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "published_version": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "eval_agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 3, "name": "Empathy Check v3", "state": "archived", "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-15T08:00:00.000Z", "latest_run": null } } } ``` # Create Eval Agent Version Source: https://docs.bland.ai/api-v1/post/evals-agents-id-versions POST https://api.bland.ai/v1/evals/agents/{eval_agent_id}/versions Fork a new editable draft version of an eval agent. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the eval agent. ### Body Parameters Display name for the new version. Between 1 and 200 characters. Optional description for the new version. ID of the version to fork from. Defaults to the current draft if not provided. ### Response Unique identifier for the new version. ID of the organization that owns this version. ID of the parent eval agent. Sequential version number assigned to the new draft. Name of the new version. Description of the new version, or `null`. Always `"editable"` for a newly forked draft. One of `text` or `audio`, inherited from the source version. The system prompt for the judge LLM, in Markdown. The grading prompt for the judge LLM, in Markdown. Verdict levels copied from the source version. Each level contains `level_key`, `label`, `prompt_md`, and optionally `color`. Target level keys copied from the source version. Relative weight copied from the source version. Between 0 and 100. ID of the version this was forked from. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. ISO 8601 timestamp for when this version was last updated. ```json Response theme={null} { "errors": null, "data": { "id": "e5f6a7b8-c9d0-1234-efab-567890123456", "org_id": "f0e1d2c3-b4a5-9678-fedc-ba9876543210", "eval_agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 4, "name": "Empathy Check v4", "description": null, "state": "editable", "modality": "audio", "system_prompt_md": "You are an expert call quality reviewer.", "prompt_md": "Did the agent express empathy when the caller described their problem?", "levels": [ { "level_key": "excellent", "label": "Excellent", "prompt_md": "The agent clearly and warmly acknowledged the caller's feelings.", "color": "emerald" }, { "level_key": "poor", "label": "Poor", "prompt_md": "The agent ignored or dismissed the caller's feelings.", "color": "rose" } ], "target_level_keys": ["excellent"], "weight": 10, "created_from_version_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-27T11:30:00.000Z", "updated_at": "2026-05-27T11:30:00.000Z" } } ``` # Create Eval Run Source: https://docs.bland.ai/api-v1/post/evals-runs POST https://api.bland.ai/v1/evals/runs Start a new eval run over a batch of calls. ### Headers Your API key for authentication. ### Body Parameters The call IDs to score. Between 1 and 5000 calls. The eval agents to score with. Maximum 50 agents. Each object: The UUID of the eval agent. Pin a specific version of the agent. Omit to use the latest published version. Relative weight of this agent in the overall score, 0-100. Level keys considered a passing result for this agent. The scoring modality. One of `text`, `audio`, or `full`. Defaults to `text`. Percentage of evaluations that must pass for the run to be marked passing overall, 0-100. Omit to run without a threshold. UUID of a workbench setup to associate with this run. Must be provided together with `workbench_setup_version_id`. UUID of the pinned workbench setup version. The version's agent roster is used when `attached_agents` is omitted. Must be provided together with `workbench_setup_id`. How this run was initiated. One of `manual`, `auto`, or `backfill`. Defaults to `manual`. Key-value metadata to attach to the run. Keys and values must be strings. You must supply either a non-empty `attached_agents` array or a `workbench_setup_version_id` (whose pinned roster supplies the agents). If you provide `workbench_setup_id` or `workbench_setup_version_id`, both fields are required together. A valid billing record must be on file before a run can start. ### Response Unique identifier for the newly created eval run. The organization that owns this run. Initial status of the run. Will be `PENDING` immediately after creation. How the run was triggered. The scoring modality for this run. The call IDs submitted for scoring. The agent attachments submitted with the run. Each object contains `eval_agent_id`, `eval_agent_version_id`, `weight`, and `target_level_keys`. The associated workbench setup, if provided. The pinned workbench setup version, if provided. Number of calls resolved for the run. Number of eval agents resolved for the run. Total call-by-agent evaluations to perform. Number of evaluations completed so far. Always `null` at creation time. Always `null` at creation time. Error code if the run failed, otherwise `null`. Human-readable error message if the run failed, otherwise `null`. Internal workflow identifier, if applicable. Key-value metadata attached to the run. ISO 8601 timestamp when the run was created. Always `null` at creation time. Always `null` at creation time. ```json Response theme={null} { "data": { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "org_id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "status": "PENDING", "triggered_by": "manual", "run_mode": "text", "submitted_call_ids": [ "a1b2c3d4-0000-0000-0000-000000000001", "a1b2c3d4-0000-0000-0000-000000000002" ], "submitted_attached_agents": [ { "eval_agent_id": "11111111-aaaa-bbbb-cccc-dddddddddddd", "eval_agent_version_id": "22222222-aaaa-bbbb-cccc-dddddddddddd", "weight": 100, "target_level_keys": ["pass"] } ], "workbench_setup_id": null, "workbench_setup_version_id": null, "resolved_call_count": 2, "resolved_agent_count": 1, "resolved_atom_count": 2, "completed_atom_count": 0, "summary": null, "billable_cost_usd": null, "error_code": null, "error_message": null, "workflow_id": null, "metadata": {}, "created_at": "2026-05-27T10:00:00.000Z", "started_at": null, "completed_at": null }, "errors": null } ``` # Estimate Eval Run Source: https://docs.bland.ai/api-v1/post/evals-runs-estimates POST https://api.bland.ai/v1/evals/runs/estimates Preview the size and cost of a run before starting it. ### Headers Your API key for authentication. ### Body Parameters Accepts the same body as [Create Eval Run](/api-v1/post/evals-runs). Key fields: The call IDs to include in the estimate. Between 1 and 5000 calls. The eval agents to score with. Required when `workbench_setup_version_id` is not provided. Pinned workbench setup version whose agent roster supplies the agents. Required when `attached_agents` is not provided. Must be provided together with `workbench_setup_id`. ### Response Number of call-by-agent evaluations the run will perform. Estimated number of input tokens consumed by judge calls. Estimated number of output tokens produced by judge calls. Estimated billable cost in USD cents. ```json Response theme={null} { "data": { "resolved_atom_count": 150, "estimated_input_tokens": 420000, "estimated_output_tokens": 15000, "estimated_cost_usd_cents": 87.5 }, "errors": null } ``` # Cancel Eval Run Source: https://docs.bland.ai/api-v1/post/evals-runs-id-cancel POST https://api.bland.ai/v1/evals/runs/{run_id}/cancellations Cancel a pending or running eval run. ### Headers Your API key for authentication. ### Path Parameters The ID of the eval run to cancel. ### Response Unique identifier for the eval run. The organization that owns this run. Updated status of the run. Will be `CANCELLED`. How the run was triggered. One of `manual`, `auto`, `backfill`. The scoring modality. One of `text`, `audio`, `full`. The call IDs that were submitted for scoring. The agent attachments submitted with the run. The associated workbench setup, if any. The pinned workbench setup version, if any. Number of calls resolved for the run. Number of eval agents resolved for the run. Total call-by-agent evaluations in the run. Number of evaluations completed before cancellation. Partial scoring summary if any atoms completed before cancellation, otherwise `null`. Billable cost for evaluations completed before cancellation, or `null` if not yet finalized. Error code if applicable, otherwise `null`. Human-readable error message if applicable, otherwise `null`. Internal workflow identifier, if applicable. Key-value metadata attached to the run. ISO 8601 timestamp when the run was created. ISO 8601 timestamp when the run started, or `null` if it never started. ISO 8601 timestamp when the run was cancelled. ```json Response theme={null} { "data": { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "org_id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "status": "CANCELLED", "triggered_by": "manual", "run_mode": "text", "submitted_call_ids": [ "a1b2c3d4-0000-0000-0000-000000000001", "a1b2c3d4-0000-0000-0000-000000000002", "a1b2c3d4-0000-0000-0000-000000000003" ], "submitted_attached_agents": [ { "eval_agent_id": "11111111-aaaa-bbbb-cccc-dddddddddddd", "eval_agent_version_id": "22222222-aaaa-bbbb-cccc-dddddddddddd", "weight": 100, "target_level_keys": ["pass"] } ], "workbench_setup_id": null, "workbench_setup_version_id": null, "resolved_call_count": 3, "resolved_agent_count": 1, "resolved_atom_count": 3, "completed_atom_count": 1, "summary": null, "billable_cost_usd": 0.01, "error_code": null, "error_message": null, "workflow_id": null, "metadata": {}, "created_at": "2026-05-27T10:00:00.000Z", "started_at": "2026-05-27T10:00:05.000Z", "completed_at": "2026-05-27T10:00:38.000Z" }, "errors": null } ``` # Create User Template Source: https://docs.bland.ai/api-v1/post/evals-user-templates POST https://api.bland.ai/v1/evals/user-templates Save a new eval agent template, from scratch or by snapshotting an existing eval agent. ### Headers Your API key for authentication. ### Body Parameters Display name for the template. Maximum 120 characters. Description of the template. Maximum 4000 characters. Pass `null` to leave blank. Category label for the template. Maximum 64 characters. Pass `null` to leave blank. Evaluation modality. Either `text` or `audio`. System prompt for the eval agent, in Markdown. Maximum 50000 characters. Evaluation prompt, in Markdown. Maximum 50000 characters. Ordered scoring levels. Each level object requires `level_key` (string, 1-64 chars), `label` (string, 1-80 chars), and `prompt_md` (string). The `color` field is optional: one of `rose`, `amber`, `gold`, `emerald`, `blue`, `indigo`, `violet`, or `fog`. Array of `level_key` strings that represent the passing threshold. Access scope for the template. One of `private`, `org`, or `public`. UUID of an existing eval agent to snapshot content from. UUID of a specific version of the eval agent to snapshot. Only used when `from_agent_id` is provided. Defaults to the agent's current version if omitted. There are two creation paths. Pass `from_agent_id` (optionally with `from_version_id`) to snapshot an existing agent's content into the template, or pass inline content fields to build one from scratch. When both are supplied, `from_agent_id` provides the content and inline fields act as overrides. ### Response Unique identifier (UUID) for the new template. UUID of the organization that owns this template. Short key used to reference the template. Display name of the template. Description of the template, or `null`. Category of the template, or `null`. Evaluation modality. Either `text` or `audio`. System prompt for the eval agent, in Markdown. Evaluation prompt, in Markdown. Ordered scoring levels. Array of `level_key` strings that represent the passing threshold. Access scope. One of `private`, `org`, or `public`. UUID of the eval agent this template was snapshotted from, or `null`. UUID of the specific version snapshotted, or `null`. UUID of the user who created the template, or `null`. ISO 8601 timestamp of when the template was created. ISO 8601 timestamp of when the template was last updated. ```json Response theme={null} { "data": { "id": "a1b2c3d4-5678-9abc-def0-1234567890ab", "org_id": "b2c3d4e5-6789-abcd-ef01-234567890abc", "key": "my_hallucination_check", "name": "My Hallucination Check", "description": "Customized hallucination detection for our product domain.", "category": "quality", "modality": "text", "system_prompt_md": "You are an expert evaluator assessing whether an AI agent fabricated information.", "prompt_md": "Review the conversation and identify any claims that were factually incorrect or unsupported.", "levels": [ { "level_key": "no_hallucination", "label": "No Hallucination", "prompt_md": "The agent made no factually incorrect or unsupported claims.", "color": "emerald" }, { "level_key": "hallucination_detected", "label": "Hallucination Detected", "prompt_md": "The agent stated something factually incorrect or unsupported.", "color": "rose" } ], "target_level_keys": ["no_hallucination"], "visibility": "org", "source_agent_id": null, "source_version_id": null, "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-27T10:00:00.000Z", "updated_at": "2026-05-27T10:00:00.000Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Workbench Setup Source: https://docs.bland.ai/api-v1/post/evals-workbench-setups POST https://api.bland.ai/v1/evals/workbench-setups Create a new workbench setup with an empty draft version. ### Headers Your API key for authentication. ### Body Parameters Display name for the setup. Between 1 and 200 characters. Optional description of the setup. ### Response Returns `201` on success. An object containing the new setup and its draft version. Unique identifier for the workbench setup. ID of the organization that owns this setup. Stable slug key for the setup. Display name of the setup. Description of the setup, or `null` if not set. ID of the current editable draft version. ID of the published version, or `null` if never published. Key-value metadata. Values are strings. ISO 8601 timestamp for when the setup was created. ISO 8601 timestamp for when the setup was last updated. ISO 8601 timestamp for when the setup was deleted, or `null` if not deleted. Unique identifier for this version. ID of the organization that owns this version. ID of the parent workbench setup. Monotonically increasing version number. Display name of this version. Description of this version, or `null` if not set. `"editable"` for a draft, `"archived"` for a published snapshot. Eval agents attached to this version. Each item contains `eval_agent_id`, `eval_agent_version_id`, `weight` (0-100), and `target_level_keys` (array of strings). Percentage of calls that must pass for a run to be considered passing (0-100), or `null` if not set. How calls are evaluated. One of `text`, `audio`, or `full`. ID of the default test configuration, or `null` if not set. Default call IDs to evaluate against. Up to 5000 entries. ID of the version this was forked from, or `null` if it is the first version. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. ISO 8601 timestamp for when this version was last updated. `null` on success. ```json Response theme={null} { "errors": null, "data": { "setup": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "org_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "key": "onboarding-quality-check", "name": "Onboarding Quality Check", "description": "Evaluates tone, accuracy, and resolution rate across onboarding calls.", "current_version_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "active_version_id": null, "metadata": {}, "created_at": "2026-05-27T09:00:00.000Z", "updated_at": "2026-05-27T09:00:00.000Z", "deleted_at": null }, "current_version": { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "org_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "workbench_setup_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 1, "name": "Onboarding Quality Check", "description": "Evaluates tone, accuracy, and resolution rate across onboarding calls.", "state": "editable", "attached_agents": [], "pass_threshold_pct": null, "run_mode": "text", "default_test_config_id": null, "default_call_ids": [], "created_from_version_id": null, "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-27T09:00:00.000Z", "updated_at": "2026-05-27T09:00:00.000Z" } } } ``` # Publish Workbench Setup Source: https://docs.bland.ai/api-v1/post/evals-workbench-setups-id-publish POST https://api.bland.ai/v1/evals/workbench-setups/{setup_id}/publications Publish the setup's current draft as a new active version. A setup must have at least one attached agent before it can be published. Each attached agent must also have at least one target level key assigned. ### Headers Your API key for authentication. ### Path Parameters The ID of the workbench setup to publish. ### Response ID of the workbench setup that was published. ID of the new editable draft version created after publishing. ID of the newly published (archived) version. This is now the active version. Summary of the version that was published. Unique identifier for the published version. ID of the parent workbench setup. Version number of the published snapshot. Display name of the version. Always `"archived"` for a published version. Number of eval agents in this version. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. The most recent run against this version, or `null` if none exist. `null` on success. ```json Response theme={null} { "errors": null, "data": { "workbench_setup_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "current_version_id": "e5f6a7b8-c9d0-1234-efab-345678901234", "active_version_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "published_version": { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "workbench_setup_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 3, "name": "Onboarding Quality Check", "state": "archived", "attached_agent_count": 4, "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-20T14:00:00.000Z", "latest_run": null } } } ``` # Create Workbench Setup Version Source: https://docs.bland.ai/api-v1/post/evals-workbench-setups-id-versions POST https://api.bland.ai/v1/evals/workbench-setups/{setup_id}/versions Fork a new editable draft version of a workbench setup. ### Headers Your API key for authentication. ### Path Parameters The ID of the workbench setup to fork a new version from. ### Body Parameters All fields are optional. Display name for the new version. Between 1 and 200 characters. Defaults to the source version's name. Optional description for the new version. ID of the version to fork from. Defaults to the current draft if not provided. ### Response Returns `201` on success. The full newly created version object. Unique identifier for this version. ID of the organization that owns this version. ID of the parent workbench setup. Monotonically increasing version number. Display name of this version. Description of this version, or `null` if not set. Always `"editable"` for a newly created version. Eval agents inherited from the source version. Each item contains `eval_agent_id`, `eval_agent_version_id`, `weight` (0-100), and `target_level_keys` (array of strings). Inherited pass threshold percentage (0-100), or `null` if not set. Inherited run mode. One of `text`, `audio`, or `full`. Inherited default test configuration ID, or `null` if not set. Inherited default call IDs. Up to 5000 entries. ID of the version this was forked from. Identifier of the user who created this version, or `null`. ISO 8601 timestamp for when this version was created. ISO 8601 timestamp for when this version was last updated. `null` on success. ```json Response theme={null} { "errors": null, "data": { "id": "f7a8b9c0-d1e2-3456-abcd-567890123456", "org_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "workbench_setup_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version_number": 5, "name": "Onboarding Quality Check", "description": null, "state": "editable", "attached_agents": [ { "eval_agent_id": "e5f6a7b8-c9d0-1234-efab-345678901234", "eval_agent_version_id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "weight": 50, "target_level_keys": ["good", "excellent"] } ], "pass_threshold_pct": 80, "run_mode": "audio", "default_test_config_id": null, "default_call_ids": [], "created_from_version_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba", "created_at": "2026-05-27T10:00:00.000Z", "updated_at": "2026-05-27T10:00:00.000Z" } } ``` # Create Guard Rail Source: https://docs.bland.ai/api-v1/post/guard-rails POST https://api.bland.ai/v1/guard_rails Create a new guard rail for compliance monitoring. Guard rails monitor AI responses during calls to catch compliance violations and trigger automated actions. Learn more in the [Guard Rails documentation](/tutorials/guard-rails). ### Headers Your API key for authentication. ### Body Parameters #### TCPA Guard Rails The type of TCPA guard rail: * `tcpa:ai_disclosure` - AI must disclose it's an AI * `tcpa:recording_disclosure` - Must disclose the call is being recorded * `tcpa:self_introduction` - Must identify who is calling * `tcpa:opt_out` - Monitors for user opt-out requests The `tcpa:opt_out` type is different from the others: it's not time-based and instead monitors the entire conversation to detect if the agent continues to engage after the user opts out. The `config.end_seconds` field is not needed for this type. Configuration object. Required for time-based TCPA guard rails (`tcpa:ai_disclosure`, `tcpa:recording_disclosure`, `tcpa:self_introduction`). * `end_seconds` (number) - Time window in seconds. If the required disclosure is not made within this time, the configured actions will trigger. Array of sources to attach this guard rail to. * `source_type` (string, required) - Type of source: `PERSONA`, `PATHWAY`, or `INBOUND` * `source_id` (string, required) - ID of the source to attach to * `actions` (array, required) - Actions to take when the guard rail triggers #### Custom Guard Rails (Enterprise) Custom guard rails use your own detection prompt. Limited to 5 per organization. Must be `custom` for custom guard rails. Display name for the guard rail. This doesn't affect the behaviour and is only for your reference. Description of what this guard rail detects. This doesn't affect the behaviour and is only for your reference. Detection prompt that describes what to flag. #### Action Types Each attachment requires an `actions` array. Available action types: | Action Type | Description | Config | | -------------- | ------------------------------- | ------------------------------------ | | `end_call` | Immediately terminate the call | None | | `transfer` | Transfer to a human agent | `{ "phone_number": "+15551234567" }` | | `move_to_node` | Jump to a specific pathway node | `{ "node_id": "node-uuid" }` | ### Response The created guard rail object containing `id`, `org_id`, `type`, `name`, `description`, `prompt`, `config`, `attachments`, `created_at`, and `updated_at`. Any errors that occurred (null if none). ```json TCPA Time-based theme={null} { "type": "tcpa:ai_disclosure", "config": { "end_seconds": 30 }, "attachments": [ { "source_type": "PERSONA", "source_id": "98765432-1234-1234-1234-123456789012", "actions": [ { "type": "end_call" } ] } ] } ``` ```json TCPA Opt-Out theme={null} { "type": "tcpa:opt_out", "attachments": [ { "source_type": "PATHWAY", "source_id": "11111111-2222-3333-4444-555555555555", "actions": [ { "type": "end_call" } ] } ] } ``` ```json Custom (Enterprise) theme={null} { "type": "custom", "name": "No Medical Advice", "description": "Prevents the agent from providing medical advice", "prompt": "Flag if the agent provides any medical advice, diagnosis, or treatment recommendations", "attachments": [ { "source_type": "PERSONA", "source_id": "98765432-1234-1234-1234-123456789012", "actions": [ { "type": "transfer", "config": { "phone_number": "+15551234567" } } ] } ] } ``` ```json Success Response theme={null} { "data": { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "org_id": "12345678-1234-1234-1234-123456789012", "type": "tcpa:ai_disclosure", "name": null, "description": null, "prompt": null, "config": { "end_seconds": 30 }, "attachments": [ { "source_type": "PERSONA", "source_id": "98765432-1234-1234-1234-123456789012", "actions": [ { "type": "end_call" } ] } ], "created_at": "2025-01-15T10:30:00.000Z", "updated_at": "2025-01-15T10:30:00.000Z" }, "errors": null } ``` ```json Error Response (Duplicate Type) theme={null} { "data": null, "errors": [ { "error": "INVALID_PARAMETER", "message": "Cannot create multiple guard rails of the same type" } ] } ``` ```json Error Response (Enterprise Required) theme={null} { "data": null, "errors": [ { "error": "ENTERPRISE_REQUIRED", "message": "Creating custom guard rails are only available for enterprise users" } ] } ``` ```json Error Response (Max Custom Guard Rails) theme={null} { "data": null, "errors": [ { "error": "INVALID_PARAMETER", "message": "Cannot create more than 5 custom guard rails" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Upload Inbound Phone Numbers Source: https://docs.bland.ai/api-v1/post/inbound-insert POST https://api.bland.ai/v1/inbound/insert Add inbound numbers to Bland from your own Twilio account. See [Custom Twilio Integration](/tutorials/custom-twilio) for more information. ### Headers Your API key for authentication. The encrypted\_key of the Twilio account you want to upload numbers from. Learn more about BYOT [here](/tutorials/custom-twilio). ### Body An array of phone numbers you want to upload to Bland. Include the leading `'+'`, country code and the phone number without any special characters. Example: `["+12223334444", "+13334445555"]` ### Response Can be `success` or `error`. A message saying whether the insertion succeeded, or a helpful message describing why it failed. An array of phone numbers that were successfully inserted. Any phone numbers that failed to be inserted will not be included in this array - for example if they are already in your account or not associated with the sepcified Twilio account. ```json theme={null} { "status": "success", "message": "Successfully inserted numbers", "inserted": [ "+12223334444", "+13334445555" ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Delete Inbound Phone Number Source: https://docs.bland.ai/api-v1/post/inbound-number-delete POST https://api.bland.ai/v1/inbound/{phone_number}/delete Remove an inbound number that was uploaded through your own Twilio account. See [Custom Twilio Integration](/tutorials/custom-twilio) for more information. ### Headers Your API key for authentication. The `encrypted_key` for the Twilio account that owns the phone number you want to delete. Learn more about BYOT [here](/tutorials/custom-twilio). ### Path The phone number you want to remove from Bland's system. ### Response Can be `success` or `error`. A message saying whether the deletion succeeded, or a helpful message describing why it failed. ```json theme={null} { "status": "success", "message": "Successfully deleted number from database: +15555555555" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Inbound Number Details Source: https://docs.bland.ai/api-v1/post/inbound-number-update POST https://api.bland.ai/v1/inbound/{phone_number} Update your inbound agent's settings, prompt and other details. ### Headers Your API key for authentication. The `encrypted_key` for the Twilio account that owns the phone number you want to modify. Not required if you are using a Bland phone number. Learn more about BYOT [here](/tutorials/custom-twilio). ### Path Parameters The inbound phone number you wish to update. Formatting Notes: * The `'+'` or `'%2B'` prefix is optional. * Will assume a US country code if no country code is provided. Valid Examples for `+13334445555`: * `%2B13334445555` * `13334445555` * `3334445555` ### Body Provide instructions, relevant information, and examples of the ideal conversation flow. For inbound numbers, consider including additional context about the purpose of the call, and what types of callers to expect. #### Out-of-the-Box Behaviors (Summarized): * Speech pattern: Direct, concise, casual * Spells out symbols, acronyms, abbreviations, percentages, etc. (\$4,000,000 -> "four million dollars") * Asks clarifying questions #### Prompting Tips: * Want to easily test out exactly how your agent will behave? * [Try out Agent Testing!](https://app.bland.ai/home?page=testing) * Aim for less than >2,000 characters where possible. * Simple, direct prompts are the most predictable and reliable. * Frame instructions positively: * `"Do this"` rather than `"Don't do this"`. * Ex. "Keep the conversation casual" rather than "Don't be too formal". * This gives concrete examples of what to do, instead of leaving expected behavior open to interpretation. Set the pathway that your agent will follow. This will override the `prompt` field, so there is no need to pass the 'prompt' field if you are setting a pathway. Warning: Setting a pathway will set the following fields to `null` / their default value - `prompt`, `first_sentence`, `model`, `dynamic_data`, `tools`, `transfer_list` Set to `null` or an empty string to clear the pathway. The version number of the pathway to use for the call. Defaults to the production version. ### Agent Parameters (Body) Set your agent's voice - all available voices can be found with the [List Voices](/api-v1/get/voices) endpoint. Select an audio track that you'd like to play in the background during the call. The audio will play continuously when the agent isn't speaking, and is incorporated into it's speech as well. Use this to provide a more natural, seamless, engaging experience for the conversation. We've found this creates a significantly smoother call experience by minimizing the stark differences between total silence and the agent's speech. Options: * `null` - Default, will play audible but quiet phone static. * `office` - Office-style soundscape. Includes faint typing, chatter, clicks, and other office sounds. * `cafe` - Cafe-like soundscape. Includes faint talking, clinking, and other cafe sounds. * `restaurant` - Similar to `cafe`, but more subtle. * `none` - Minimizes background noise Makes your agent say a specific phrase or sentence for its first response. (Optional) Custom instructions for how the call summary should be generated after the call completes. Use this to provide specific guidance or context for the AI when writing the post-call summary. Maximum length: 2000 characters. Example: ```json theme={null} { "summary_prompt": "Summarize the call in 2-3 sentences, focusing on the customer's main concern and any next steps discussed." } ``` When set to `true`, the AI will not respond or process interruptions from the user. Adjusts how patient the AI is when waiting for the user to finish speaking. Lower values mean the AI will respond more quickly, while higher values mean the AI will wait longer before responding. Recommended range: 50-200 * 50: Extremely quick, back and forth conversation * 100: Balanced to respond at a natural pace * 200: Very patient, allows for long pauses and interruptions. Ideal for collecting detailed information. Try to start with 100 and make small adjustments in increments of \~10 as needed for your use case. Select a model to use for your call. Options: `base` or `turbo`. In nearly all cases, `base` is the best choice for now. There are two different ways to use Bland: * `model: base` * The original, follows scripts/procedures most effectively. * Supports all features and capabilities. * Best for Custom Tools * `model: turbo` * The absolute fastest latency possible, can be verbose at times * Limited capabilities currently (excludes Transferring, IVR navigation, Custom Tools) * Extremely realistic conversation capabilities Request data fields are available to the AI agent during the call when referenced in the associated pathway or task. This data is accessible in variables if the call is answered. For example, let's say in your app you want to programmatically set the name of the person you're calling. You could set `request_data` to: ```json Example theme={null} { "task": "Say hello to the user, who's name is {{name}}", // also works in the prompt, tools, etc. "request_data": { "name": "John Doe" } } ``` Interact with the real world through API calls. Detailed tutorial here: [Custom Tools](/tutorials/custom-tools) Select a supported language of your choice. Optimizes every part of our API for that language - transcription, speech, and other inner workings. The available language options are as follows: * `auto` - Auto Detect * `en` - English * `en-US` - English (US) * `en-GB` - English (UK) * `en-AU` - English (Australia) * `en-NZ` - English (New Zealand) * `en-IN` - English (India) * `zh` - Chinese (Mandarin, Simplified) * `zh-CN` - Chinese (Mandarin, Simplified, China) * `zh-Hans` - Chinese (Mandarin, Simplified, Hans) * `zh-TW` - Chinese (Mandarin, Traditional) * `zh-Hant` - Chinese (Mandarin, Traditional, Hant) * `es` - Spanish * `es-419` - Spanish (Latin America) * `fr` - French * `fr-CA` - French (Canada) * `de` - German * `el` - Greek * `hi` - Hindi * `hi-Latn` - Hindi (Latin script) * `ja` - Japanese * `ko` - Korean * `ko-KR` - Korean (Korea) * `pt` - Portuguese * `pt-BR` - Portuguese (Brazil) * `pt-PT` - Portuguese (Portugal) * `it` - Italian * `nl` - Dutch * `pl` - Polish * `ru` - Russian * `sv` - Swedish * `sv-SE` - Swedish (Sweden) * `da` - Danish * `da-DK` - Danish (Denmark) * `fi` - Finnish * `id` - Indonesian * `ms` - Malay * `tr` - Turkish * `uk` - Ukrainian * `bg` - Bulgarian * `cs` - Czech * `ro` - Romanian * `sk` - Slovak * `hu` - Hungarian * `no` - Norwegian * `vi` - Vietnamese * `babel` - Babel (Experimental) Set the timezone for the call. Handled automatically for calls in the US. This helps significantly with use cases that rely on appointment setting, scheduling, or behaving differently based on the time of day. Timezone options are [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) in the TZ identifier column. A phone number that the agent can transfer to under specific conditions - such as being asked to speak to a human or supervisor. Set to `null` to remove. For best results: * Specify conditions that the agent should transfer to a human under (examples are great!) * In the `task`, refer to the action solely as "transfer" or "transferring". * Alternate phrasing such as "swap" or "switch" can mislead the agent, causing the action to be ignored. A phone number to forward inbound calls to during Bland maintenance windows. Configure this ahead of any announced maintenance period. Setting this field does not affect normal call routing, your agent will continue to handle calls as usual. Bland activates the redirect only during maintenance, at which point calls are immediately forwarded to this number instead of reaching the agent. Set to `null` or an empty string to remove the configured fallback. Attach a [memory store](/api-v1/post/memory-create) to the inbound agent so calls to this number share context across sessions. Pass the `memory_id` returned by [Create Memory](/api-v1/post/memory-create). Set to `null` or an empty string to detach. Array of objects that guides the agent on how to say specific words. Use this to improve clarity for acronyms, names, brand terms, or jargon. ```json theme={null} [ { "word": "example", "pronunciation": "ex-am-ple", "case_sensitive": false, "spaced": false }, { "word": "API", "pronunciation": "A P I", "case_sensitive": true, "spaced": true } ] ``` * `word`: the word you want to guide the LLM on how to pronounce * `pronunciation`: how the AI should pronounce the word, using syllables or space-separated characters. For example, `"A P I"` ensures each letter is spoken clearly rather than read as a word. * `case_sensitive`: whether or not to consider case. Particularly useful with names. EG: 'Max' the name versus 'max' the word. Defaults to false. `Not required`. * `spaced`: whether to match whole words only. When true, "high" will match "high" but not "hightop". When false, it will match any word that contains "high". Defaults to true. `Not required`. Give your agent the ability to transfer calls to a set of phone numbers. Overrides `transfer_phone_number` if a `transfer_list.default` is specified. Will default to `transfer_list.default`, or the chosen phone number. Example usage to route calls to different departments: ```json theme={null} "transfer_list": { "default": "+12223334444", "sales": "+12223334444", "support": "+12223334444", "billing": "+12223334444" } ``` Integrate data from external APIs into your agent's knowledge. Set to `null` or an empty string to clear dynamic data settings. Detailed usage in the [Send Call](/api-v1/post/calls#param-dynamic-data) endpoint. Adjusts how patient the AI is when waiting for the user to finish speaking. Lower values mean the AI will respond more quickly, while higher values mean the AI will wait longer before responding. Recommended range: 50-200 * 50: Extremely quick, back and forth conversation * 100: Balanced to respond at a natural pace * 200: Very patient, allows for long pauses and interruptions. Ideal for collecting detailed information. Try to start with 100 and make small adjustments in increments of \~10 as needed for your use case. These words will be boosted in the transcription engine - recommended for proper nouns or words that are frequently mis-transcribed. For example, if the word "Reece" is frequently transcribed as a homonym like "Reese" you could do this: ```json theme={null} { "keywords": ["Reece"] } ``` For stronger keyword boosts, you can place a colon then a boost factor after the word. The default boost factor is 2. ```json theme={null} { "keywords": ["Reece:3"] } ``` Toggles noise filtering or suppression in the audio stream to filter out background noise. When `true`, DTMF (digit) presses are ignored, disabling menu navigation or call transfers triggered by keypad input. ### Call Settings (Body) When the call starts, a timer is set for the `max_duration` minutes. At the end of that timer, if the call is still active it will be automatically ended. Example Values: `20, 2` When the call ends, we'll send the call details in a POST request to the URL you specify here. The request body will match the response from the [GET /v1/calls/:call\_id](/api-v1/get/calls-id) endpoint. Specify which events you want to stream to the webhook, during the call. Options: * `queue` * `call` * `latency` * `webhook` * `tool` * `dynamic_data` * `citations` (Sent separately, Enterprise only) Example payloads: ```json queue theme={null} // ex 1 { "message": "Call enqueued", "call_id": "12345678-1234-1234-1234-123456789abc", "category": "queue", "log_level": "info" } ``` ```json call theme={null} // ex 1 { "message": "Call connected", "call_id": "12345678-1234-1234-1234-123456789abc", "category": "call", "log_level": "info" } // ex 2 { "message": "Sending first sentence: Hello, thank you for reaching out. I'd like to get to know you a bit better. How are you feeling today?", "call_id": "12345678-1234-1234-1234-123456789abc", "category": "call", "log_level": "info" } // ex 3 { "message": "Agent speech: Hello, thank you for reaching out.", "call_id": "12345678-1234-1234-1234-123456789abc", "category": "call", "log_level": "info" } // ex 4 { "message": "Handling user speech: Yeah. I'm thirty six. And I'm five foot nine.", "call_id": "12345678-1234-1234-1234-123456789abc", "category": "call", "log_level": "info" } // ex 5 { "message": "Webhook Response: 200 | Webhook Response Data: [object Object] | Response Time: 689ms", "call_id": "87654321-4321-4321-4321-cba987654321", "category": "call", "log_level": "info" } ``` ```json latency theme={null} // ex 1 { "message": "TTS: 218ms", "call_id": "12345678-1234-1234-1234-123456789abc", "category": "latency", "log_level": "performance" } // ex 2 { "message": "LLM: 266ms", "call_id": "12345678-1234-1234-1234-123456789abc", "category": "latency", "log_level": "performance" } ``` ```json webhook theme={null} { "message": "Storing dynamic data messages: \n\n answer : \"true\"", "call_id": "87654321-4321-4321-4321-cba987654321", "category": "call", "log_level": "info" } ``` ```json tool theme={null} { "message": "Executing custom tool: Test Tool 4 with input: [object Object]", "call_id": "abcdef12-3456-7890-abcd-ef1234567890", "category": "call", "log_level": "info" } ``` ```json dynamic_data theme={null} { "message": "Storing dynamic data: \n\n vector_data : {\"data\":{\"results\":[{\"id\":\"fedcba98-7654-3210-fedc-ba9876543210\",\"input_text\":\"Here are details on the restaurant...\",\"similarity\":0.103339002763233,\"chunk_index\":0}]},\"errors\":null}", "call_id": "abcdef12-3456-7890-abcd-ef1234567890", "category": "call", "log_level": "info" } ``` ```json citations theme={null} { "call_id": "12345678-1234-1234-1234-123456789abc", "user_id": "11111111-2222-3333-4444-555555555555", "event_type": "citations", "timestamp": "2025-07-03T16:41:15.231Z", "citations": [ { "call_id": "12345678-1234-1234-1234-123456789abc", "variable_name": "User height", "variable_type": "boolean", "value": true, "cited_utterances": [ { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "idx": 3, "start_time": 24.096, "end_time": 27.424, "confidence": 0.17166666666666666, "channel": 1, "transcript": "I am 36 and I am 5'9\".", "speaker_id": "SPEAKER_1_0", "speaker_name": null, "speaker_description": null, "topics": [ "customer_information_provided" ], "topics_meta": "{\"customer_information_provided\":\"customer providing personal details\"}", "utterance_type": "answer" } ], "schema_id": "99999999-8888-7777-6666-555555555555" }, { "call_id": "12345678-1234-1234-1234-123456789abc", "variable_name": "Caller Age", "variable_type": "number", "value": 36, "cited_utterances": [ { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "idx": 3, "start_time": 24.096, "end_time": 27.424, "confidence": 0.17166666666666666, "channel": 1, "transcript": "I am 36 and I am 5'9\".", "speaker_id": "SPEAKER_1_0", "speaker_name": null, "speaker_description": null, "topics": [ "customer_information_provided" ], "topics_meta": "{\"customer_information_provided\":\"customer providing personal details\"}", "utterance_type": "answer" }, { "id": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "idx": 4, "start_time": 30.56, "end_time": 35.455, "confidence": 0.5672727272727273, "channel": 0, "transcript": "All right. So you're 36 years old and five foot nine. That's great. How's your day been so far? Anything exciting happened?", "speaker_id": "SPEAKER_0_0", "speaker_name": null, "speaker_description": null, "topics": [ "day_review_inquiry" ], "topics_meta": "{\"day_review_inquiry\":\"agent inquiring about the customer's day and any exciting events\"}", "utterance_type": "question" } ], "schema_id": "99999999-8888-7777-6666-555555555555" }, { "call_id": "12345678-1234-1234-1234-123456789abc", "variable_name": "Caller feeling", "variable_type": "string", "value": null, "cited_utterances": [], "schema_id": "99999999-8888-7777-6666-555555555555" } ] } ``` Add any additional information you want to associate with the call. This can be useful for tracking or categorizing calls. At the end of each call, a `summary` is generated based on the transcript - you can use this field to add extra instructions and context for how it should be summarized. For example: `"Summarize the call in French instead of English."` To record your phone call, set `record` to true. When your call completes, you can access through the `recording_url` field in the call details or your webhook. The citation schema is an incredibly powerful tool for running ***post call analysis***, including specific variable extractions, conditional logic, and more. You can build a citation schema [here](https://app.bland.ai/dashboard/analytics?tab=citations). > Note: Citation schemas are very powerful and accurate, but also are more resource intensive to run. As such, for the time being, they are an enterprise-only feature. ### Response Whether the update was successful or not - will be `success` or `error`. A message describing the status of the update. An object containing the updated settings for the inbound number. If the update was unsuccessful, this will contain the settings that failed to update. Useful to determine how your request is being interpreted on our end. ```json Response theme={null} { "status": "success", "message": "Successfully updated number +18584139939.", "updates": { "prompt": "(Your prompt)", "voice": "maya", "webhook": null, "first_sentence": "Roberta speaking, how can I help you?", "record": false, "max_duration": 30, "model": "base", //... } } ``` *** Docs for agents: [llms.txt](/llms.txt) # Purchase Phone Number Source: https://docs.bland.ai/api-v1/post/inbound-purchase POST https://api.bland.ai/numbers/purchase Purchase a new phone number (inbound/outbound). ($15/mo. subscription using your stored payment method). ### Headers Your API key for authentication. ### Body Choose a three-digit area code for your phone number. If set as a parameter, a number will only be purchased by exact match if available. Choose a country code for your phone number. Options: `"US"` or `"CA"` for Canada. For others, please contact support. Specify an exact phone number you'd like to use. If provided, will override the `area_code` parameter and does not fall back to any other number. Example of the correct format (Note the `"+1"` is mandatory): `"+12223334444"` *** Docs for agents: [llms.txt](/llms.txt) # Create Inbound Session Source: https://docs.bland.ai/api-v1/post/inbound-session POST https://api.bland.ai/v1/inbound/session Create a session token that can be used to pass variables to inbound calls via SIP headers. This allows you to tie specific data to a call session before the call is initiated. This endpoint creates a session token that can be used to pass variables to inbound calls when connecting via SIP. When you create a session using this endpoint, you receive a token that can be passed as the `x-bland-session-id` SIP header. Any call made to your inbound number with this header will automatically include the variables you specified when creating the session. **Use Case**: This is particularly useful when you need to pass context or variables to an inbound call before the caller connects. For example, you might want to include customer information, campaign data, or other relevant context that your pathway can access during the call. ### Headers Your API key for authentication. ### Body The inbound phone number that this session will be associated with. This should be a phone number you own and have configured for inbound calls. Example format: `"+12223334444"` Optional variables that will be available in your pathway when a call is made using this session token. These variables can include any data you want to pass to the call context. Example: ```json theme={null} { "customer_id": "12345", "campaign_name": "summer_promotion", "user_tier": "premium" } ``` The voice of the agent to use for the call. This can be the name, or the ID of the voice. Example: ```json theme={null} { "voice": "June" } ``` ### Response The session token that should be passed as the `x-bland-session-id` SIP header when making the inbound call. ISO 8601 timestamp indicating when this session token expires. Sessions have a limited lifetime for security purposes. The default is 1 hour. ### SIP Integration To use the session token: 1. Create a session using this endpoint 2. When making a SIP call to your inbound number, include the header: `x-bland-session-id: ` 3. Your Bland call will have access to any variables you specified in the `request_data` field, in addition to any variables you had initially set up for the inbound number. ### Example ```bash theme={null} curl -X POST https://api.bland.ai/v1/inbound/session \ -H "authorization: sk-your-api-key" \ -H "Content-Type: application/json" \ -d '{ "phone_number": "+12223334444", "request_data": { "customer_id": "12345", "campaign_name": "summer_promotion", "priority": "high" }, "voice": "June" }' ``` Response: ```json theme={null} { "token": "550e8400-e29b-41d4-a716-446655440000", "expires_at": "2024-01-15T10:30:00Z" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Inbound Number Label Source: https://docs.bland.ai/api-v1/post/inbound-update-label POST https://api.bland.ai/inbound/update_label Update the label shown for one of your inbound phone numbers. ### Headers Your API key for authentication. ### Body The inbound phone number whose label you want to update. Required format: E.164 (for example, `+12223334444`). The new label to assign to this inbound number. Constraints: * Max length: `150` characters * Set to an empty string (`""`) to clear the label ### Response Success response data. Success message. The inbound phone number that was updated. The updated label value. Error array (null on success). ```json Success theme={null} { "data": { "message": "Label updated successfully", "phone_number": "+18669659045", "label": "apitest" }, "errors": null } ``` ```json Invalid request body (400) theme={null} { "data": null, "errors": [ { "error": "INVALID_REQUEST", "message": "Invalid request body" } ] } ``` ```json Label too long (400) theme={null} { "data": null, "errors": [ { "error": "LABEL_TOO_LONG", "message": "Label is too long" } ] } ``` ```json Auth failure (401) theme={null} { "data": null, "errors": [ { "error": "AUTH_FAILURE", "message": "Unauthorized" } ] } ``` ```json Not found (404) theme={null} { "error": "Phone number not found" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Chat with Knowledge Base Source: https://docs.bland.ai/api-v1/post/knowledge-chat POST https://api.bland.ai/v1/knowledge/chat Performs a conversational query against knowledge bases with context. Query a knowledge base using natural language and receive contextual responses. This endpoint supports both direct queries and conversational context through message history. ### Headers Your API key for authentication. Must be `application/json`. ### Body Parameters Array of chat messages for conversational context. Use this for multi-turn conversations. The role of the message sender (e.g., "user", "assistant", "system"). The content of the message. The ID of the knowledge base to query against. ### Response Chat response with contextual information. The AI-generated response based on the knowledge base content. Additional context information used to generate the response. Array of source documents that were used to generate the response. Unique identifier of the source document. Relevant content from the source document. Additional metadata about the source document. Will be `null` on successful query. ```json Success Response theme={null} { "data": { "response": "Our refund policy allows for full refunds within 30 days of purchase. For products purchased more than 30 days ago, we offer store credit or exchanges. Please contact our customer service team at support@example.com to initiate a refund request.", "context": "Based on company policy documentation regarding refunds and returns", "sources": [ { "id": "doc_01H8X9QK5R2N7P3M6Z8W4Y1V7V", "content": "Refund Policy: Full refunds are available within 30 days of purchase...", "metadata": { "document_type": "policy", "section": "refunds", "last_updated": "2025-01-01" } } ] }, "errors": null } ``` ```json Error Response theme={null} { "data": null, "errors": [ { "error": "KB_ERROR", "message": "Knowledge base not found or not accessible" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Discover Sitemap URLs Source: https://docs.bland.ai/api-v1/post/knowledge-crawl POST https://api.bland.ai/v1/knowledge/crawl Discovers URLs from a website's sitemap for web scraping. Analyzes a website to discover available URLs from its sitemap. This is useful for finding all the pages available on a website before creating a web scraping knowledge base. ### Headers Your API key for authentication. Must be `application/json`. ### Body Parameters The base URL of the website to discover sitemap URLs from. ### Response Discovered URLs and sitemap information. Array of discovered URLs from the website's sitemap. The sitemap URL that was found and processed (if any). Will be `null` on successful discovery. ```bash cURL theme={null} curl -X POST https://api.bland.ai/v1/knowledge/crawl \ -H "authorization: YOUR_API_KEY" \ -H "content-type: application/json" \ -d '{ "url": "https://example.com" }' ``` ```json Request Body theme={null} { "url": "https://docs.example.com" } ``` ```json Success Response theme={null} { "data": { "urls": [ "https://example.com/", "https://example.com/about", "https://example.com/products", "https://example.com/contact", "https://example.com/docs/getting-started", "https://example.com/docs/api-reference", "https://example.com/docs/tutorials" ], "sitemap_url": "https://example.com/sitemap.xml" }, "errors": null } ``` ```json No Sitemap Found theme={null} { "data": { "urls": [], "sitemap_url": null }, "errors": null } ``` ```json Error Response theme={null} { "data": null, "errors": [ { "error": "INVALID_INPUT", "message": "Invalid URL provided" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Upload File Source: https://docs.bland.ai/api-v1/post/knowledge-learn-file POST https://api.bland.ai/v1/knowledge/learn Creates a new knowledge base by uploading a file. Upload a file to create a knowledge base that can be used to provide contextual information to your AI agents. Supported file formats include PDF, Word documents, text files, and more. ### Headers Your API key for authentication. Must be `multipart/form-data` for file uploads. ### Body Parameters (multipart/form-data) Must be `"file"` for file uploads. KB name (defaults to filename if not provided). Optional description of the knowledge base content. The file to upload and process into a knowledge base. ### Response The created knowledge base object. Unique identifier for the knowledge base. Name of the knowledge base. Description of the knowledge base (if provided). Current status: `"PROCESSING"`, `"COMPLETED"`, `"FAILED"`, or `"DELETED"`. Will be `"FILE"` for file-based knowledge bases. ISO timestamp of creation. ISO timestamp of last update. Error message if status is `"FAILED"`. File information for the uploaded file. Original filename. File size in bytes. MIME type of the file. Will be `null` on successful creation. ```bash cURL theme={null} curl -X POST https://api.bland.ai/v1/knowledge/learn \ -H "authorization: YOUR_API_KEY" \ -F "type=file" \ -F "name=Company FAQs" \ -F "description=Frequently asked questions and policies" \ -F "file=@company_faqs.pdf" ``` ```bash With Default Name theme={null} curl -X POST https://api.bland.ai/v1/knowledge/learn \ -H "authorization: YOUR_API_KEY" \ -F "type=file" \ -F "description=Product documentation" \ -F "file=@product_docs.pdf" ``` ```json Success Response theme={null} { "data": { "id": "kb_01H8X9QK5R2N7P3M6Z8W4Y1V5T", "name": "Company FAQs", "description": "Frequently asked questions and policies", "status": "PROCESSING", "type": "FILE", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z", "file": { "file_name": "company_faqs.pdf", "file_size": 2048576, "file_type": "application/pdf" } }, "errors": null } ``` ```json Error Response theme={null} { "data": null, "errors": [ { "error": "KB_UPLOAD_LIMIT_EXCEEDED", "message": "You have reached your knowledge base upload limit" } ] } ``` ```json Rate Limited Response theme={null} { "data": null, "errors": [ { "error": "KB_UPLOAD_RATE_LIMITED", "message": "Please wait 10 seconds between knowledge base uploads, or wait for your current upload to complete." } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Upload Text Source: https://docs.bland.ai/api-v1/post/knowledge-learn-text POST https://api.bland.ai/v1/knowledge/learn Creates a new knowledge base from direct text input. Create a knowledge base by providing text content directly in the request. This is ideal for when you have structured text content that you want to make searchable for your AI agents. ### Headers Your API key for authentication. Must be `application/json` for text-based knowledge bases. ### Body Parameters Must be `"text"` for text-based knowledge bases. Name for the knowledge base. Optional description of the knowledge base content. Text content to be stored in the knowledge base (maximum 1MB). ### Response The created knowledge base object. Unique identifier for the knowledge base. Name of the knowledge base. Description of the knowledge base (if provided). Current status: `"PROCESSING"`, `"COMPLETED"`, `"FAILED"`, or `"DELETED"`. Will be `"TEXT"` for text-based knowledge bases. ISO timestamp of creation. ISO timestamp of last update. Error message if status is `"FAILED"`. Will be `null` on successful creation. ```bash cURL theme={null} curl -X POST https://api.bland.ai/v1/knowledge/learn \ -H "authorization: YOUR_API_KEY" \ -H "content-type: application/json" \ -d '{ "type": "text", "name": "Product Information", "description": "Product specifications and features", "text": "Our flagship product offers advanced AI capabilities with industry-leading accuracy. It supports multiple languages, real-time processing, and seamless integration with existing systems. The product includes comprehensive APIs, detailed documentation, and 24/7 support." }' ``` ```json Request Body theme={null} { "type": "text", "name": "Company Policies", "description": "Internal policies and procedures", "text": "1. Work Hours: Standard work hours are 9 AM to 5 PM, Monday through Friday.\n2. Remote Work: Employees may work remotely up to 3 days per week with manager approval.\n3. Time Off: All employees accrue 15 days of PTO annually.\n4. Equipment: Company laptops must be returned within 30 days of termination." } ``` ```json Success Response theme={null} { "data": { "id": "kb_01H8X9QK5R2N7P3M6Z8W4Y1V6U", "name": "Product Information", "description": "Product specifications and features", "status": "PROCESSING", "type": "TEXT", "created_at": "2025-01-15T11:00:00Z", "updated_at": "2025-01-15T11:00:00Z" }, "errors": null } ``` ```json Error Response theme={null} { "data": null, "errors": [ { "error": "INVALID_INPUT", "message": "Text content exceeds maximum size of 1MB" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Scrape Websites Source: https://docs.bland.ai/api-v1/post/knowledge-learn-web POST https://api.bland.ai/v1/knowledge/learn Creates a new knowledge base by scraping content from web URLs. Create a knowledge base by scraping content from one or more web URLs. This is perfect for creating knowledge bases from documentation sites, blog posts, or other web-based content. ### Headers Your API key for authentication. Must be `application/json` for web scraping knowledge bases. ### Body Parameters Must be `"web"` for web scraping knowledge bases. Name for the knowledge base. Optional description of the knowledge base content. Array of URLs to scrape (maximum 100 URLs). ### Response The created knowledge base object. Unique identifier for the knowledge base. Name of the knowledge base. Description of the knowledge base (if provided). Current status: `"PROCESSING"`, `"COMPLETED"`, `"FAILED"`, or `"DELETED"`. Will be `"WEB_SCRAPE"` for web scraping knowledge bases. Source URLs that were scraped (comma-separated). Base URL derived from the provided URLs. ISO timestamp of creation. ISO timestamp of last update. Error message if status is `"FAILED"`. Will be `null` on successful creation. ```bash cURL theme={null} curl -X POST https://api.bland.ai/v1/knowledge/learn \ -H "authorization: YOUR_API_KEY" \ -H "content-type: application/json" \ -d '{ "type": "web", "name": "Documentation", "description": "Complete product documentation", "urls": [ "https://docs.example.com/overview", "https://docs.example.com/api-reference", "https://docs.example.com/tutorials" ] }' ``` ```json Single URL theme={null} { "type": "web", "name": "Blog Posts", "description": "Latest company blog posts", "urls": [ "https://example.com/blog/latest-features" ] } ``` ```json Multiple URLs theme={null} { "type": "web", "name": "Support Documentation", "description": "Customer support and FAQ pages", "urls": [ "https://support.example.com/faq", "https://support.example.com/troubleshooting", "https://support.example.com/getting-started", "https://support.example.com/advanced-features" ] } ``` ```json Success Response theme={null} { "data": { "id": "kb_01H8X9QK5R2N7P3M6Z8W4Y1V7V", "name": "Documentation", "description": "Complete product documentation", "status": "PROCESSING", "type": "WEB_SCRAPE", "source_urls": "https://docs.example.com/overview,https://docs.example.com/api-reference,https://docs.example.com/tutorials", "base_url": "https://docs.example.com", "created_at": "2025-01-15T12:00:00Z", "updated_at": "2025-01-15T12:00:00Z" }, "errors": null } ``` ```json Error Response theme={null} { "data": null, "errors": [ { "error": "INVALID_INPUT", "message": "URLs array cannot exceed 100 items" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Contact Memory Source: https://docs.bland.ai/api-v1/post/memory-contact POST https://api.bland.ai/v1/memory/contact Create a memory record for a contact scoped to a persona or agent number. If a record already exists for that pair, it is returned instead of creating a duplicate. ### Headers Your API key for authentication. ### Body Parameters The unique identifier of the contact. The persona ID for memory scoping. Either `persona_id` or `agent_number` is required. The agent phone number for memory scoping. Either `persona_id` or `agent_number` is required. ### Response Response containing the memory and creation status. The contact memory object. Unique identifier for the contact memory. Organization ID this memory belongs to. Contact ID this memory is associated with. Persona ID this memory is scoped to (null if agent-based). Agent phone number this memory is scoped to (null if persona-based). Rolling summary (empty for new memories). Structured facts (empty object for new memories). Recent messages array (empty for new memories). Whether a new memory was created (true) or an existing one was returned (false). Error array (null on success). ```json New Memory Created theme={null} { "data": { "memory": { "id": "mem-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "org_id": "11111111-2222-3333-4444-555555555555", "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "persona_id": "persona-12345678", "agent_number": null, "summary": null, "facts": {}, "recent_messages": [], "open_items": [], "memory_history": [], "created_at": "2025-07-22T10:30:00.000Z", "updated_at": "2025-07-22T10:30:00.000Z" }, "created": true }, "errors": null } ``` ```json Existing Memory Found theme={null} { "data": { "memory": { "id": "mem-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "org_id": "11111111-2222-3333-4444-555555555555", "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "persona_id": "persona-12345678", "agent_number": null, "summary": "Customer called about order #8821 which was delayed. Promised a follow-up within 24 hours.", "facts": { "name": "Sarah Chen", "phone": "+14155550192", "preferred_contact": "phone" }, "recent_messages": [ { "role": "user", "content": "Hi, I'm calling about my order", "channel": "call", "timestamp": "2025-07-22T10:30:00.000Z" } ], "open_items": [ { "type": "follow_up", "description": "Follow up on order #8821 delay status", "created_at": "2025-07-22T10:30:00.000Z", "priority": "high", "related_to": { "entity_type": "order", "entity_id": "order-8821" } } ], "memory_history": [], "created_at": "2025-07-20T10:30:00.000Z", "updated_at": "2025-07-22T15:45:00.000Z" }, "created": false }, "errors": null } ``` ```json Error Response theme={null} { "data": null, "errors": [ { "error": "BAD_REQUEST", "message": "persona_id or agent_number is required" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Memory Source: https://docs.bland.ai/api-v1/post/memory-create POST https://api.bland.ai/v1/memory/create Create a new memory to organize and track call interactions by phone numbers. ### Headers Your API key for authentication. ### Body Parameters The name for the new memory. Used to identify and organize your memories. ### Response The created memory object. Unique identifier for the newly created memory. ISO timestamp when the memory was created. Unique identifier for the user who owns the memory. Name of the created memory. Duration setting for the memory (null indicates no duration limit). Error array (null on success). ```json Response theme={null} { "data": { "id": "12345678-1234-1234-1234-123456789012", "created_at": "2025-07-21T07:24:49.883Z", "user_id": "87654321-4321-4321-4321-210987654321", "name": "Docs Example", "memory_duration": null }, "errors": null } ``` ```json Missing Name theme={null} { "data": null, "errors": [ { "error": "INVALID_REQUEST", "message": "Memory name is required." } ] } ``` ```json Server Error theme={null} { "data": null, "errors": [ { "error": "MEMORY_CREATE_ERROR", "message": "Failed to create memory." } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Enable or Disable Memory Source: https://docs.bland.ai/api-v1/post/memory-enable POST https://api.bland.ai/v1/memory/enable Enable or disable memory for a pathway or persona version. ### Headers Your API key for authentication. ### Body Parameters Provide **either** pathway **or** persona identifiers (not both). Pathway ID. Use with `version_number` and `memory_enabled`. Pathway version number. Required when `pathway_id` is provided. Persona ID. Use with `version_id` and `memory_enabled`. Persona version ID (UUID). Required when `persona_id` is provided. Set to `true` to enable memory, `false` to disable. ### Response Success response data. Success message. Error array (null on success). ```json Response (pathway) theme={null} { "data": { "message": "Memory enabled successfully for pathway." }, "errors": null } ``` ```json Response (persona) theme={null} { "data": { "message": "Memory enabled successfully for persona." }, "errors": null } ``` ```json Missing or invalid body theme={null} { "data": null, "errors": [ { "error": "INVALID_REQUEST", "message": "memory_enabled (boolean) is required." } ] } ``` ```json Neither or both pathway/persona theme={null} { "data": null, "errors": [ { "error": "INVALID_REQUEST", "message": "Exactly one of pathway_id or persona_id is required." } ] } ``` ```json Not found / Forbidden theme={null} { "data": null, "errors": [ { "error": "NOT_FOUND", "message": "Pathway not found." } ] } ``` ### Behavior When memory is **enabled**, the system automatically refreshes entity schemas in the background — no additional action required. From that point on, memory is populated automatically on every call or SMS conversation that runs through the pathway or persona version. When memory is **disabled**, no new memory is written. Existing memory data is preserved. *** Docs for agents: [llms.txt](/llms.txt) # Add Call to Memory Source: https://docs.bland.ai/api-v1/post/memory-memory-id-add-call POST https://api.bland.ai/v1/memory/{memory_id}/add-call Add an existing call to a memory. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the memory to add the call to. ### Body Parameters The unique identifier of the call to add to the memory. Must be an existing call in your account. Optional external key for additional memory validation or cross-referencing. ### Response Response data confirming call addition. Success message confirming call was added to memory. Information about the call that was added. The call identifier that was added. The memory identifier the call was added to. Error array (null on success). ```json Response theme={null} { "data": { "message": "Call added to memory successfully", "call": { "call_id": "call_abc123", "memory_id": "mem_123abc" } }, "errors": null } ``` ```json Missing Call ID theme={null} { "data": null, "errors": [ { "error": "INVALID_REQUEST", "message": "Call ID is required." } ] } ``` ```json Server Error theme={null} { "data": null, "errors": [ { "error": "MEMORY_ADD_CALL_ERROR", "message": "Failed to add call to memory." } ] } ``` ### Notes * The call must already exist in your account before it can be added to a memory * The call must be connected to a user existing in the memory * Adding a call to a memory will automatically associate it with the phone number involved in the call *** Docs for agents: [llms.txt](/llms.txt) # Add User to Memory Source: https://docs.bland.ai/api-v1/post/memory-memory-id-add-user POST https://api.bland.ai/v1/memory/{memory_id}/add-user Add a new user/phone number to an existing memory. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the memory to add the user to. ### Body Parameters The phone number of the user to add to the memory. Custom metadata text to associate with this user in the memory. Initial summary text for this user's interactions. Optional external key for additional memory validation or cross-referencing. ### Response Response data confirming user addition. Success message confirming user was added to memory. The user object that was added to the memory. Unique identifier for the user entry in the memory. The memory identifier this user was added to. The phone number that was added. The metadata text associated with this user. The summary text for this user. ISO timestamp when this user was added to the memory. Number of calls associated with this user. ISO timestamp of the most recent call, or null if no calls yet. Error array (null on success). ```json Request theme={null} { "phone_number": "+12345678900", "metadata": "25 year old customer", "summary": "The user described their age" } ``` ```json Response theme={null} { "data": { "message": "User added to memory successfully", "user": { "id": "11111111-2222-3333-4444-555566667777", "memory_id": "12345678-1234-1234-1234-123456789012", "phone_number": "+12345678900", "metadata": "25 year old customer", "summary": "The user described their age", "created_at": "2025-07-22T05:26:49.139Z", "call_count": 0, "last_call_at": null } }, "errors": null } ``` ```json Server Error theme={null} { "data": null, "errors": [ { "error": "MEMORY_ADD_USER_ERROR", "message": "Failed to add user to memory." } ] } ``` ### Notes * If the phone number already exists in the memory, this endpoint will error with a `MEMORY_ADD_USER_ERROR` * Metadata can be any text string relevant to your use case * The summary will be enhanced over time as more calls are added to this user's record *** Docs for agents: [llms.txt](/llms.txt) # Remove Call from Memory Source: https://docs.bland.ai/api-v1/post/memory-memory-id-call-call-id-delete POST https://api.bland.ai/v1/memory/{memory_id}/call/{call_id}/delete Remove a specific call from a memory. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the memory containing the call. The unique identifier of the call to remove from the memory. ### Body Parameters The phone number associated with the call to be removed. Optional external key for additional memory validation or cross-referencing. ### Response Response data confirming call removal and updated summary. Success message confirming call was removed and summary updated. The updated AI-generated summary for the user after call removal. The updated call count for the user after removal. Error array (null on success). ```json Response theme={null} { "data": { "message": "Call removed from memory successfully and updated summary", "summary": "Customer had initial billing inquiry which was resolved. Prefers email communication for follow-ups.", "call_count": 2 }, "errors": null } ``` ```json Server Error theme={null} { "data": null, "errors": [ { "error": "MEMORY_REMOVE_CALL_ERROR", "message": "Failed to remove call from memory." } ] } ``` ### Notes * Removing a call will automatically update the user's summary to reflect the remaining interactions * The call itself is not deleted from your account, only its association with this memory is removed *** Docs for agents: [llms.txt](/llms.txt) # Delete Memory Source: https://docs.bland.ai/api-v1/post/memory-memory-id-delete POST https://api.bland.ai/v1/memory/{memory_id}/delete Permanently delete an entire memory and all associated data including users, calls, and metadata. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the memory to delete. ### Response Response data confirming memory deletion. Success message confirming memory was deleted. Error array (null on success). ```json Response theme={null} { "data": { "message": "Memory deleted successfully" }, "errors": null } ``` ```json Server Error theme={null} { "data": null, "errors": [ { "error": "MEMORY_DELETE_ERROR", "message": "Failed to delete memory." } ] } ``` ### ⚠️ Warning This action is **irreversible**. Deleting a memory will permanently remove: * The memory itself and all its metadata * All user entries and their associated data * All call associations and summaries * Any custom metadata and summaries ## Make sure you have backed up any important data before proceeding with deletion. Docs for agents: [llms.txt](/llms.txt) # Update Memory Source: https://docs.bland.ai/api-v1/post/memory-memory-id-update POST https://api.bland.ai/v1/memory/{memory_id}/update Update the name of an existing memory. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the memory to update. ### Body Parameters The new name for the memory. Cannot be null or undefined. ### Response The updated memory object. Unique identifier for the memory. Updated name of the memory. ISO timestamp when the memory was originally created. Unique identifier for the organization that owns the memory. Currently under development. Error array (null on success). ```json Response theme={null} { "data": { "id": "12345678-1234-1234-1234-123456789012", "created_at": "2025-07-21T07:24:49.883Z", "user_id": "87654321-4321-4321-4321-210987654321", "name": "Test Memory", "memory_duration": null }, "errors": null } ``` ```json Missing or Invalid Data theme={null} { "data": null, "errors": [ { "error": "INVALID_REQUEST", "message": "No update data provided." } ] } ``` ```json Server Error theme={null} { "data": null, "errors": [ { "error": "MEMORY_UPDATE_ERROR", "message": "Failed to update memory." } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get User Memory Details Source: https://docs.bland.ai/api-v1/post/memory-memory-id-user POST https://api.bland.ai/v1/memory/{memory_id}/user Retrieve detailed memory information for a specific user or phone number in a memory store. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the memory. ### Body Parameters The phone number of the user to retrieve memory details for. Optional external key for additional memory validation or cross-referencing. ### Response User memory data. Custom metadata text associated with this user's memory entry. AI-generated summary of interactions with this user. ISO timestamp of the most recent call with this user. Total number of calls with this user. Array of call objects associated with this user. Unique identifier for the call. ISO timestamp when the call was made. AI-generated summary of this specific call. Who answered the call (e.g., "human", "ai"). Call duration in minutes. Whether this was an inbound call (true) or outbound call (false). Error array (null on success). ```json Response theme={null} { "data": { "metadata": "25 year old customer from New York", "summary": "The user had previously discussed their startup and had a follow-up conversation, asking questions about AI and the future of their business.", "last_call_at": "2025-07-22T05:19:46.000Z", "call_count": 1, "calls": [ { "c_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffgggg", "created_at": "2025-07-22T05:19:37.314Z", "summary": "The call appears to be a follow-up conversation about the user's startup, asking questions about AI and the future of their business.", "answered_by": "human", "call_length": 0.3, "inbound": false } ] }, "errors": null } ``` ```json Server Error theme={null} { "data": null, "errors": [ { "error": "MEMORY_ERROR", "message": "Failed to retrieve memory data." } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Remove User from Memory Source: https://docs.bland.ai/api-v1/post/memory-memory-id-user-delete POST https://api.bland.ai/v1/memory/{memory_id}/user/delete Remove a specific user/phone number and all their associated data from a memory. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the memory to remove the user from. ### Body Parameters The phone number of the user to remove from the memory. Optional external key for additional memory validation or cross-referencing. ### Response Response data confirming user removal. Success message confirming user was removed from memory. Error array (null on success). ```json Response theme={null} { "data": { "message": "User +1234567890 removed from memory successfully" }, "errors": null } ``` ```json Missing Phone Number theme={null} { "data": null, "errors": [ { "error": "INVALID_REQUEST", "message": "Phone number is required." } ] } ``` ```json Server Error theme={null} { "data": null, "errors": [ { "error": "MEMORY_REMOVE_USER_ERROR", "message": "Failed to remove user from memory." } ] } ``` ### ⚠️ Warning This action will permanently remove: * The user's entry from the memory * All associated metadata for this user * The user's summary and interaction history * All call associations for this user within this memory ## The actual calls will remain in your account, but their association with this memory will be removed. Docs for agents: [llms.txt](/llms.txt) # Search User Calls in Memory Source: https://docs.bland.ai/api-v1/post/memory-memory-id-user-search POST https://api.bland.ai/v1/memory/{memory_id}/user/search Retrieve call history and data for a specific user/phone number within a memory. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the memory to search within. ### Body Parameters The phone number of the user to search for calls. Optional external key for additional memory validation or cross-referencing. ### Response Array of call objects for this user within the memory. Unique identifier for the call. ISO timestamp when the call was made. AI-generated summary of this specific call. Who answered the call (e.g., "human", "ai"). Call duration in minutes. Whether this was an inbound call (true) or outbound call (false). Error array (null on success). ```json Response theme={null} { "data": [ { "c_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffgggg", "created_at": "2025-07-22T05:19:37.314Z", "summary": "The call appears to be a follow-up conversation about the user's startup, asking questions about AI and the future of their business.", "answered_by": "human", "call_length": 0.3, "inbound": false } ], "errors": null } ``` ```json Missing Phone Number theme={null} { "data": null, "errors": [ { "error": "INVALID_REQUEST", "message": "Phone number is required in request body." } ] } ``` ```json Memory Not Found theme={null} { "data": null, "errors": [ { "error": "MEMORY_NOT_FOUND", "message": "Memory not found or you don't have access to it." } ] } ``` ```json Server Error theme={null} { "data": null, "errors": [ { "error": "MEMORY_ERROR", "message": "Failed to retrieve memory user data." } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update User Memory Data Source: https://docs.bland.ai/api-v1/post/memory-memory-id-user-update POST https://api.bland.ai/v1/memory/{memory_id}/user/update Update the metadata and summary information for a specific user within a memory. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the memory containing the user to update. ### Body Parameters The phone number of the user to update within the memory. Updated metadata to associate with this user. Can include any key-value pairs relevant to your use case. Updated summary text for this user's interactions. Optional external key for additional memory validation or cross-referencing. ### Response Response data confirming user update. Success message confirming user memory data was updated. The updated user object. Unique identifier for the user entry in the memory. The memory identifier this user belongs to. The phone number that was updated. The updated metadata text associated with this user. The updated summary text for this user. ISO timestamp when this user was originally added to the memory. Number of calls associated with this user. ISO timestamp of the most recent call, or null if no calls yet. Error array (null on success). ```json Response theme={null} { "data": { "message": "User memory data updated successfully", "user": { "id": "11111111-2222-3333-4444-555566667777", "memory_id": "12345678-1234-1234-1234-123456789012", "phone_number": "+12345678900", "metadata": "Test here with string metadtata", "summary": "I'm thinking yeah...", "created_at": "2025-07-22T05:32:32.233Z", "call_count": 0, "last_call_at": null } }, "errors": null } ``` ```json Server Error theme={null} { "data": null, "errors": [ { "error": "MEMORY_UPDATE_USER_ERROR", "message": "Failed to update user memory data." } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Reset Contact Memory Source: https://docs.bland.ai/api-v1/post/memory-reset POST https://api.bland.ai/v1/memory/reset Permanently delete all memory for a contact scoped to a specific persona or agent number. All conversation history, facts, summaries, and entities for that pair are removed. This cannot be undone. This action is **irreversible**. All memory data (recent messages, summary, facts, entities) for this contact/persona pair will be permanently deleted. ### Headers Your API key for authentication. ### Body Parameters The unique identifier of the contact whose memory should be reset. The persona ID for memory scoping. Either `persona_id` or `agent_number` is required. The agent phone number for memory scoping. Either `persona_id` or `agent_number` is required. ### Response Success confirmation. Whether the reset was successful. Error array (null on success). ```json Response theme={null} { "data": { "success": true }, "errors": null } ``` ```json Error Response theme={null} { "data": null, "errors": [ { "error": "BAD_REQUEST", "message": "persona_id or agent_number is required" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Move Pathway Source: https://docs.bland.ai/api-v1/post/move-pathway-folder POST https://us.api.bland.ai/v1/pathway/folders/move Moves a pathway to a different folder or to the root level. ### Headers Your API key for authentication. ### Body Parameters The ID of the pathway to move. The ID of the destination folder. If null, the pathway will be moved to the root level. ### Response The ID of the moved pathway. The ID of the original folder. The ID of the new folder, or null if moved to root level. ```json Response theme={null} { "pathway_id": "pathway_123", "old_folder_id": "old_folder_456", "new_folder_id": "new_folder_789" } ``` ``` --- Docs for agents: [llms.txt](/llms.txt) ``` # Invoke Node Test Run Source: https://docs.bland.ai/api-v1/post/node_test_invoke POST https://api.bland.ai/v1/node_tests/invoke Start a node test run for a given node and pathway with a new prompt and sample conversations. ### Headers Your API key for authentication. ### Body Parameters The new prompt to test for this node. This will be used to simulate the agent's responses against the pinned and auto-selected conversations. Either `new_prompt` or `static_text` can be provided, but not both. Static text that the agent will always reply with. Either `static_text` or `new_prompt` can be provided, but not both. This is useful to test variable extractions on static text nodes. The judge prompt to evaluate the test results. If not provided, the default judge prompt will be used. The default judge prompt will evaluate the agent responses against the node prompt. The prompt for the node loop condition. Array of variables to extract from the conversation. The name of the variable to extract. The type of the variable. Must be one of: `"string"`, `"integer"`, or `"boolean"`. A description of what the variable represents. Whether spelling precision should be enforced for this variable. Array of conversation references to include in the test. The system may automatically add up to 4 additional recent completed calls for the same node and pathway. Unique identifier of a call to include in the test run. Type of the conversation. We only support "call" for now. Identifier of the node to test within the specified pathway. Identifier of the pathway that the node and conversations belong to. The version of the pathway to test against. Optional number of permutations to generate for each conversation. If omitted, this defaults to 5. The total generations per conversation will be n\_permutations + 1 (one for the original user messages plus one per permutation). ### Response Identifier of the created node test run. Use this ID with GET /v1/node\_tests/run/:id to retrieve the full results. ```json Request theme={null} { "new_prompt": "You are the best financial advisor...", "judge_prompt": "Evaluate if the response is helpful and accurate.", "loop_prompt": "Continue if the user has more questions.", "extract_variables": [ { "name": "user_name", "type": "string", "description": "The name of the user", "spelling_precision": true } ], "conversations": [ { "type": "call", "id": "330d8a20-27bc-4d00-b67a-8474c9a6d4e1" }, { "type": "call", "id": "906f16de-2719-4b7e-864b-a4b002586e7c" } ], "node_id": "a7bbd409-504b-4ba3-a9d1-12f6bc270f58", "pathway_id": "05f4b269-e79a-4825-b4cd-7778f782bfad", "pathway_version": "2", "n_permutations": 5 } ``` ```json Response theme={null} { "data": { "run_id": "727a85f1-1959-4ec1-95a4-248a2eecf1ae" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Organization Source: https://docs.bland.ai/api-v1/post/orgs POST https://api.bland.ai/v1/orgs/create Create a new organization. ### Headers Your API key for authentication. ### Body The name of the organization. ### Response The created organization details. A unique identifier for the organization. A randomly generated unique slug for the organization. The display name of the organization. URL of the organization's image (if set). The organization's plan. Default: `"starter"`. The timestamp of when the organization was created. The KYC (Know Your Customer) verification level. Default: `0`. The placement group of the organization. Default: `"blandshared"`. Whether the organization is deleted. Default: `false`. Whether the organization has overdue Stripe payments. Default: `false`. Whether the organization is suspended. Default: `false`. The organization's request rate limit. Default: `5`. The type of the organization. Default: `"normal"`. A list of entitlements granted to the organization. Default: `[]`. Whether the organization prefers to use the Bland URL. Default: `true`. Contains error details if the request fails. ```json Response theme={null} { "data": { "id": "00705195-d5f2-4483-829e-07bb34df3625", "org_slug": "efbfd0c0-5017-4945-9156-16b56c11848e", "org_display_name": "Org Name", "org_image_url": null, "org_plan": "starter", "org_creation_date": "2025-02-14T06:06:01.504Z", "kyc_level": 0, "placement_group": "blandshared", "is_deleted": false, "is_stripe_overdue": false, "is_suspended": false, "org_rate_limit": 5, "org_type": "normal", "entitlements": [], "preferences": { "use_bland_url": true } }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Pathway Chat Source: https://docs.bland.ai/api-v1/post/pathway-chat POST https://us.api.bland.ai/v1/pathway/chat/{id} Send a message to a pathway and receive a response. ### Headers Your API key for authentication. ### Path Parameters The chat ID created from the /pathway/chat/create endpoint. ### Body The message to send to the pathway (optional) ### Response Contains the response data for the pathway chat message. The ID of the chat instance. An array of strings containing the assistant's responses to the message sent. The ID of the current node in the pathway after processing the message. The name of the current node in the pathway. An array of objects containing the role and content of each message in the external chat history. The ID of the pathway the chat is associated with. The version of the pathway being used, or null if not specified. Whether the candidate model is being used for this pathway chat. The current state of variables in the pathway execution. Whether the pathway has completed execution. Will be `null` on success. Contains error details if the request failed. ```json Response theme={null} { "data": { "chat_id": "12345678-1234-1234-1234-123456789012", "assistant_responses": ["Hey there, this is the Bland Bistro reservation line. Do you want to make a reservation?"], "current_node_id": "1", "current_node_name": "Start", "chat_history": [ {"role": "user", "content": "hello"}, {"role": "assistant", "content": "Hey there, this is the Bland Bistro reservation line. Do you want to make a reservation?"} ], "pathway_id": "87654321-4321-4321-4321-210987654321", "pathway_version": null, "use_candidate_model": false, "variables": { "callID": "12345678-1234-1234-1234-123456789012" }, "completed": false }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Pathway Chat Source: https://docs.bland.ai/api-v1/post/pathway-chat-create POST https://us.api.bland.ai/v1/pathway/chat/create Create an instance of a pathway chat, which can be used to send and receive messages to the pathway. ### Headers Your API key for authentication. ### Body Pathway ID of the pathway to create a chat instance for. The start node ID of the pathway. If not provided, the pathway will start from the node marked as the start node in the pathway configuration. Custom key-value data to initialize the pathway chat with. This object will be stored as the pathway's initial variables and can be referenced within pathway nodes. The `request_data` must be a valid JSON object (not an array or null). This works the same as [request\_data in v1/calls](/api-v1/post/calls#param-request-data) where variables can be accessed using `{{variable_name}}` syntax within your pathway nodes. ```json theme={null} { "user_name": "John Doe", "account_id": "12345", "preference": "email" } ``` Whether to use the candidate model for this pathway chat. When enabled, the pathway will use an experimental model version for enhanced performance and capabilities. The specific version number of the pathway to use for this chat instance. If not provided, the production version will be used. ### Response Contains the response data for the created pathway chat instance. The ID of the chat instance created. This will be used to send and receive messages to the pathway via the `/v1/pathway/chat/:id` endpoint. A confirmation message. Will say "Chat instance created successfully" on success. The initial variables that were set for this pathway chat instance. This will contain the `request_data` object if it was provided in the request, otherwise it will be `null`. Will be `null` on success. Contains error details if the request failed. ```json Response theme={null} { "data": { "chat_id": "9f8e7d6c-5b4a-3c2d-1e0f-a1b2c3d4e5f6", "message": "Chat instance created successfully", "variables": { "user_name": "John Doe", "account_id": "12345", "preference": "email" } }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Generate Pathway Source: https://docs.bland.ai/api-v1/post/pathway-generate POST https://api.bland.ai/v1/pathway/generate Create an asynchronous pathway generation job from a detailed prompt. ### Headers Your API key for authentication. ### Body A detailed pathway generation prompt. Server-side requirements: * Must be at least 100 characters * Must be 8000 characters or fewer for non-enterprise organizations Optional name to use for the generated pathway ### How it works This endpoint only queues generation and returns a `jobId`. Use `GET /v1/pathway/generate/status/{job_id}` to start processing and poll until generation is complete. ### Response Response object containing the generation job identifier. The job ID for this pathway generation request. `null` on success, or a list of errors. ```json Success theme={null} { "data": { "jobId": "7a9e684f-6a50-4de5-bd95-9fa5f8121ddf" }, "errors": null } ``` ```json Error theme={null} { "data": null, "errors": [ { "message": "PATHWAY_GENERATION_ERROR", "error": "Prompt must be greater than 100 characters." } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Promote Pathway Version Source: https://docs.bland.ai/api-v1/post/pathway-promote POST https://api.bland.ai/v1/pathway/{pathway_id}/publish Promote a pathway version for a pathway ID to either staging or production environment. ### Headers Your API key for authentication. ### Path The ID of the pathway you want to promote ### Body The version number of the pathway you want to promote The environment you want to promote the pathway to. Can be `production` or `staging`. Default is `production`. ### Response A message indicating the status of the request. ```json Response theme={null} { "message": "Pathway published successfully" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Pathway Source: https://docs.bland.ai/api-v1/post/pathways POST https://api.bland.ai/v1/pathway/create Create a new conversational pathway ### Headers Your API key for authentication. ### Body The name of the conversational pathway you want to create A description of the conversational pathway you want to create ### Response Can be `success` or `error`. A unique identifier for the pathway (present only if status is `success`). ```json Response theme={null} { "status": "success", "pathway_id": "9d404c1b-6a23-4426-953a-a52c392ff8f1" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Persona Source: https://docs.bland.ai/api-v1/post/personas POST https://api.bland.ai/v1/personas Create a new persona. ### Headers Your API key for authentication. ### Body Parameters Display name for the persona. Role assigned to the persona. Description of the persona's purpose and use case. Array of tags to associate with the persona. URL of the persona's profile image. Call configuration settings for the persona. Voice identifier to use for calls. Whether to record calls. Language code for the persona. Background audio setting. Maximum call duration in minutes. Whether to wait for greeting before starting. Interruption sensitivity threshold. Orchestration prompt for the persona (optional). Personality and behavior prompt for the persona. Array of default tools enabled for the persona. Array of pathway routing conditions for the persona. Name of the pathway condition. Prompt that triggers this pathway condition. ID of the pathway to route to. Version of the pathway to use. Starting node ID within the pathway. Array of knowledge base IDs to connect to the persona. ### Response The created persona object. Unique identifier for the persona. Display name of the persona. Role assigned to the persona. Description of the persona's purpose. Array of tags associated with the persona. URL of the persona's profile image (null if none). ISO 8601 timestamp of when the persona was created. ISO 8601 timestamp of when the persona was last modified. ISO 8601 timestamp of when the persona was deleted (null if active). ID of the user who owns this persona. ID of the current production version. ID of the current draft version. Complete production version object. Complete draft version object. Any errors that occurred (null if none). ```json Response (Success) theme={null} { "data": { "id": "12345678-1234-1234-1234-123456789012", "name": "Blandie", "role": null, "description": null, "tags": [], "image_url": null, "created_at": "2025-09-23T15:13:36.348Z", "updated_at": "2025-09-23T15:13:36.412Z", "deleted_at": null, "user_id": "12345678-1234-1234-1234-123456789012", "current_production_version_id": "12345678-1234-1234-1234-123456789012", "current_draft_version_id": "12345678-1234-1234-1234-123456789012", "current_production_version": { "id": "12345678-1234-1234-1234-123456789012", "persona_id": "12345678-1234-1234-1234-123456789012", "version_type": "production", "version_number": 1, "orchestration_prompt": null, "personality_prompt": "You are a helpful assistant", "pathway_conditions": null, "kb_ids": [], "call_config": null, "default_tools": [], "promoted_from_version_id": null, "promoted_at": "2025-09-23T15:13:36.368Z", "promoted_by": null, "created_at": "2025-09-23T15:13:36.369Z", "updated_at": "2025-09-23T15:13:36.369Z" }, "current_draft_version": { "id": "12345678-1234-1234-1234-123456789012", "persona_id": "12345678-1234-1234-1234-123456789012", "version_type": "draft", "version_number": 2, "orchestration_prompt": null, "personality_prompt": "You are a helpful assistant", "pathway_conditions": null, "kb_ids": [], "call_config": null, "default_tools": [], "promoted_from_version_id": "12345678-1234-1234-1234-123456789012", "promoted_at": null, "promoted_by": null, "created_at": "2025-09-23T15:13:36.390Z", "updated_at": "2025-09-23T15:13:36.390Z" } }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Attach Phone Numbers to Persona Source: https://docs.bland.ai/api-v1/post/personas-id-inbound-attach POST https://api.bland.ai/v1/personas/{persona_id}/inbound/attach Attach one or more inbound phone numbers to a persona. The same endpoint handles voice, SMS, and WhatsApp numbers — channel capability is determined by the number's own configuration, not by this call. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the persona to attach numbers to. ### Body Parameters Array of E.164 formatted phone numbers to attach to this persona. All numbers must already belong to your account. ### Response The updated persona object with the newly attached inbound numbers. Unique identifier for the persona. Display name of the persona. ID of the user who owns this persona. Array of inbound number objects now attached to this persona. The E.164 formatted phone number. Display label for the number, if set. The persona this number is attached to. Per-number persona settings (e.g. pathway overrides), if configured. ISO 8601 timestamp of when the persona was created. ISO 8601 timestamp of when the persona was last modified. `null` on success, or a list of error objects if the request failed. ```json Response (Success) theme={null} { "data": { "id": "12345678-1234-1234-1234-123456789012", "name": "Support Agent", "user_id": "12345678-1234-1234-1234-123456789012", "inbound_numbers": [ { "phone_number": "+14155551234", "label": "Support Line", "persona_id": "12345678-1234-1234-1234-123456789012", "persona_settings": null }, { "phone_number": "+14155555678", "label": null, "persona_id": "12345678-1234-1234-1234-123456789012", "persona_settings": null } ], "created_at": "2025-09-23T15:13:36.348Z", "updated_at": "2025-09-23T15:13:36.412Z" }, "errors": null } ``` ```json Error Response (Number not found) theme={null} { "data": null, "errors": [ { "error": "INVALID_INBOUND_NUMBERS", "message": "Some phone numbers were not found or do not belong to you" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Detach Phone Numbers from Persona Source: https://docs.bland.ai/api-v1/post/personas-id-inbound-detach POST https://api.bland.ai/v1/personas/{persona_id}/inbound/detach Detach one or more inbound phone numbers from a persona. Detached numbers will no longer use the persona's configuration and will have their persona settings cleared. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the persona to detach numbers from. ### Body Parameters Array of E.164 formatted phone numbers to detach from this persona. Only numbers currently attached to this persona will be affected. ### Response The updated persona object after detaching the specified numbers. Unique identifier for the persona. Display name of the persona. Array of inbound number objects still attached to this persona (after detaching the specified ones). ISO 8601 timestamp of when the persona was last modified. `null` on success, or a list of error objects if the request failed. ```json Response (Success) theme={null} { "data": { "id": "12345678-1234-1234-1234-123456789012", "name": "Support Agent", "user_id": "12345678-1234-1234-1234-123456789012", "inbound_numbers": [], "created_at": "2025-09-23T15:13:36.348Z", "updated_at": "2025-09-23T15:20:00.000Z" }, "errors": null } ``` ```json Error Response (Persona not found) theme={null} { "data": null, "errors": [ { "error": "PERSONA_NOT_FOUND", "message": "Persona not found or access denied" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Promote Persona Version Source: https://docs.bland.ai/api-v1/post/personas-id-versions-promote POST https://api.bland.ai/v1/personas/{persona_id}/versions/promote Promote a persona's draft version to production. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the persona whose draft version should be promoted. ### Response The updated persona object after promotion. Unique identifier for the persona. Display name of the persona. Role assigned to the persona. Description of the persona's purpose. Array of tags associated with the persona. URL of the persona's profile image (null if none). ISO 8601 timestamp of when the persona was created. ISO 8601 timestamp of when the persona was last modified. ISO 8601 timestamp of when the persona was deleted (null if active). ID of the user who owns this persona. ID of the current production version (updated after promotion). ID of the current draft version. Complete production version object (the newly promoted version). Complete draft version object (same as before promotion). Any errors that occurred (null if none). ```json Response theme={null} { "data": { "id": "12345678-1234-1234-1234-123456789012", "name": "Blandy", "role": null, "description": "Helpful Agent for Bland Documentation", "tags": [], "image_url": null, "created_at": "2025-09-23T15:13:36.348Z", "updated_at": "2025-09-23T15:55:57.284Z", "deleted_at": null, "user_id": "12345678-1234-1234-1234-123456789012", "current_production_version_id": "12345678-1234-1234-1234-123456789012", "current_draft_version_id": "12345678-1234-1234-1234-123456789013", "current_production_version": { "id": "12345678-1234-1234-1234-123456789012", "persona_id": "12345678-1234-1234-1234-123456789012", "version_type": "production", "version_number": 3, "orchestration_prompt": null, "personality_prompt": "You are a helpful assistant", "pathway_conditions": null, "kb_ids": [], "call_config": null, "default_tools": [], "promoted_from_version_id": "12345678-1234-1234-1234-123456789013", "promoted_at": "2025-09-23T15:55:57.262Z", "promoted_by": "12345678-1234-1234-1234-123456789012", "created_at": "2025-09-23T15:55:57.263Z", "updated_at": "2025-09-23T15:55:57.263Z" }, "current_draft_version": { "id": "12345678-1234-1234-1234-123456789013", "persona_id": "12345678-1234-1234-1234-123456789012", "version_type": "draft", "version_number": 2, "orchestration_prompt": null, "personality_prompt": "You are a helpful assistant", "pathway_conditions": null, "kb_ids": [], "call_config": null, "default_tools": [], "promoted_from_version_id": "12345678-1234-1234-1234-123456789012", "promoted_at": null, "promoted_by": null, "created_at": "2025-09-23T15:13:36.390Z", "updated_at": "2025-09-23T15:13:36.390Z" } }, "errors": null } ``` ```json Error Response (No Draft) theme={null} { "data": null, "errors": [ { "error": "NO_DRAFT_VERSION", "message": "No draft version to promote", "details": { "persona_id": "12345678-1234-1234-1234-123456789012" } } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Post Call Webhook Source: https://docs.bland.ai/api-v1/post/postcall-webhooks-create POST https://api.bland.ai/v1/postcall/webhooks/create Create and send post call webhooks for specified calls. ## Overview Create and send post call webhooks for one or more call IDs. This endpoint allows you to create webhooks for calls that don't already have webhooks configured. The webhooks will be sent immediately after creation to the specified webhook URL. If the call has already sent a post call webhook, this endpoint will return an error. *** ## Headers Your API key for authentication. *** ## Body Parameters Array of call IDs to create and send webhooks for. Each call ID must be unique within the array. The unique identifier of a call to create a webhook for. The URL where the webhook payloads should be sent. *** ## Response Array of webhook objects for each created webhook. The unique identifier of the call this webhook is for. The webhook payload data that was sent. The URL the webhook was sent to. The ID of the user/org that owns this webhook. Timestamp of when the webhook was created. Array of metadata objects about webhook send attempts. Timestamp of when this webhook attempt was sent. HTTP response code received from the webhook endpoint. Time taken to receive a response from the webhook endpoint. How this webhook was triggered (will be "create" in this case). Array of error objects if any errors occurred. The error code. Possible values: * "invalid\_parameter": Invalid request parameters * "INTERNAL\_SERVER\_ERROR": Server error occurred Detailed error message. *** Docs for agents: [llms.txt](/llms.txt) # Resend Post Call Webhook Source: https://docs.bland.ai/api-v1/post/postcall-webhooks-resend POST https://api.bland.ai/v1/postcall/webhooks/resend Resend post call webhooks for specified calls. ## Overview Resend post call webhooks for one or more call IDs. This endpoint allows you to manually trigger a resend of webhooks that were previously sent when calls completed. This endpoint can only re-send webhooks that were previously sent when calls completed. Webhooks will be re-sent to the same URL they were previously sent to. *** ## Headers Your API key for authentication. *** ## Body Parameters Array of call IDs to resend webhooks for. Each call ID must be unique within the array. The unique identifier of a call to resend the webhook for. *** ## Response Array of webhook log objects for each resent webhook. The unique identifier of the call this webhook is for. The webhook payload data that was resent. The URL the webhook was resent to. The ID of the user/org that owns this webhook. Timestamp of when the webhook was originally created. Array of metadata objects about webhook send attempts. Timestamp of when this webhook attempt was sent. HTTP response code received from the webhook endpoint. Time taken to receive a response from the webhook endpoint. How this webhook was triggered (will be "resend" in this case). Array of error objects if any errors occurred. The error code. Possible values: * "invalid\_parameter": Invalid request parameters * "INTERNAL\_SERVER\_ERROR": Server error occurred Detailed error message. *** Docs for agents: [llms.txt](/llms.txt) # Create Prompt Source: https://docs.bland.ai/api-v1/post/prompts POST https://api.bland.ai/v1/prompts Create and store a prompt for future use. ### Headers Your API key for authentication. ### Body Prompt to store. Name of prompt you want to store as reference. ### Response Prompt object. Prompt to store. Name of prompt you want to store as reference. ```json Response theme={null} { "status": "success", "prompt": { "prompt": "# Final Test", "name": "demo", "id": "PT-02b2ecdi-39f2-443f-8cb0-a6c854c65fc0" } } ``` *** Docs for agents: [llms.txt](/llms.txt) # Attach SIP Configuration Source: https://docs.bland.ai/api-v1/post/sip-attach POST https://api.bland.ai/v1/sip/attach Attach SIP configuration to one or more phone numbers for inbound and/or outbound routing. ### Headers Your API key for authentication. ### Body A single phone number to configure. PSTN numbers are normalized to E.164 (e.g., `+14150000000`); when bound to a trunk (`trunk_id`), non-E.164 SIP identities such as DIDs and extensions are also accepted. Use either `phone_number` or `phone_numbers`, not both. An array of phone numbers or DIDs to configure (up to 100). PSTN numbers are normalized to E.164; trunk-bound numbers also accept DIDs and extensions. Use either `phone_number` or `phone_numbers`, not both. An array of direction objects. Each specifies either `inbound` or `outbound` routing configuration. Must be set to `"sip"`. Bind the numbers to a reusable trunk. When set, outbound endpoint and authentication are inherited from the trunk (no need to repeat `sip_endpoint`/auth per number), and non-E.164 DIDs and extensions are accepted. #### Inbound Direction Object Set to `"inbound"`. Authentication mode: `"ip"` (default) or `"register"`. When set to `"register"`, you must also provide `register_auth`. Required when `auth_mode` is `"register"`. Contains `username` (string) and `password` (string, min 8 characters). Your SIP server address for inbound call forwarding (optional). Format: `sip:host` or `host`. Custom SIP header mappings. See header configuration examples below. Connection options: `port` (number), `transport` (`"udp"`, `"tcp"`, or `"tls"`), `secure_media` (boolean), `sip_username` (string), `sip_password` (string). #### Outbound Direction Object Set to `"outbound"`. Your SIP provider's endpoint, as a valid SIP URI (e.g., `sip:your.provider.com`). Required for outbound unless the numbers are bound to a `trunk_id`, in which case it is inherited from the trunk. Custom SIP header mappings. Connection options: `port` (number), `transport` (`"udp"`, `"tcp"`, or `"tls"`), `secure_media` (boolean), `sip_username` (string), `sip_password` (string). ### Response Array of successfully configured phone numbers. Array of phone numbers that failed to configure, with error reasons. Only returned when using registration-based auth. This is the derived password you must configure in your PBX. ### Header Configuration Examples Headers allow you to map SIP headers to Bland pathway variables and vice versa. ```json Example Request (Outbound with Headers) theme={null} curl -X POST https://api.bland.ai/v1/sip/attach \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "phone_number": "+14150000000", "directions": [ { "type": "inbound", "headers": { "direction": "inbound", "headers": [ { "type": "custom", "key": "X-Cool-Guy", "value": "First_Name" }, { "type": "custom", "key": "Account_Type", "value": "VIP", "passthrough": true }, { "type": "uui", "target": "CustomerId", "purpose": "bland", "encoding": "hex", "content": "id" } ] } }, { "type": "outbound", "sip_endpoint": "sip:your.provider.com", "options": { "port": 5061, "transport": "tls", "secure_media": true, "sip_username": "bland", "sip_password": "password" }, "headers": { "direction": "outbound", "headers": [ { "type": "custom", "key": "Favorite_Color", "value": "X-Favorite-Color" }, { "type": "custom", "key": "x-custom-id", "value": "12345", "passthrough": true }, { "type": "uui", "target": "CustomerKV", "purpose": "bland", "content": "customerid_1234", "encoding": "hex" } ] } } ], "service": "sip" }' ``` ```json Example Request (Batch Attach) theme={null} curl -X POST https://api.bland.ai/v1/sip/attach \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "phone_numbers": ["+14150000001", "+14150000002", "+14150000003"], "directions": [ { "type": "outbound", "sip_endpoint": "sip:trunk.provider.com", "options": { "transport": "tls", "secure_media": true } } ], "service": "sip" }' ``` ```json Example Request (Bind to a Trunk) theme={null} curl -X POST https://api.bland.ai/v1/sip/attach \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "phone_numbers": ["+14155550100", "2001"], "directions": [{ "type": "inbound" }, { "type": "outbound" }], "service": "sip", "trunk_id": "" }' ``` ```json Response theme={null} { "data": { "configured": ["+14150000001", "+14150000002", "+14150000003"], "failed": [] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Detach SIP Configuration Source: https://docs.bland.ai/api-v1/post/sip-detach POST https://api.bland.ai/v1/sip/detach Remove SIP configuration from a phone number for specified directions. ### Headers Your API key for authentication. ### Body The phone number to detach SIP routing from. Must be in E.164 format. Direction(s) to remove. Each object must have a `type` field set to `"inbound"` or `"outbound"`. Must be set to `"sip"`. ```json Example Request theme={null} curl -X POST https://api.bland.ai/v1/sip/detach \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "phone_number": "+14150000000", "directions": [ { "type": "outbound" } ], "service": "sip" }' ``` *** Docs for agents: [llms.txt](/llms.txt) # Discover SIP Endpoint Source: https://docs.bland.ai/api-v1/post/sip-discover POST https://api.bland.ai/v1/sip/discover Auto-discover optimal SIP connection settings by probing your endpoint with DNS resolution and SIP OPTIONS. ### Headers Your API key for authentication. ### Body The hostname or IP address of your SIP endpoint. Specific port to probe. If omitted, ports 5060, 5061, and 5080 are tested. Specific transport to test: `"udp"`, `"tcp"`, or `"tls"`. If omitted, both UDP and TCP are tested. ### Response Unique identifier for this discovery session. Discovery status: `"running"`, `"completed"`, or `"failed"`. The host that was probed. IP addresses resolved from DNS A/AAAA lookups. SRV records found for `_sip._udp`, `_sip._tcp`, `_sips._tcp`. Details of each probe attempt including port, transport, response time, response code, and user agent. Recommended connection settings: `port`, `transport`, `user_agent`, `detected_system` (e.g., "Asterisk", "FreeSWITCH", "Kamailio"), `codecs`, and `methods`. Only one discovery can run per organization at a time. Discovery results are cached for 10 minutes. ```json Example Request theme={null} curl -X POST https://api.bland.ai/v1/sip/discover \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "host": "sip.example.com" }' ``` ```json Response theme={null} { "data": { "discovery_id": "disc_abc123", "status": "completed", "host": "sip.example.com", "resolved_addresses": ["203.0.113.10"], "srv_records": [], "attempts": [ { "port": 5060, "transport": "udp", "response_time_ms": 45, "response_code": 200, "user_agent": "Asterisk PBX 18.0.0" } ], "recommended": { "port": 5060, "transport": "udp", "detected_system": "Asterisk", "codecs": ["PCMU", "PCMA", "G.722"], "methods": ["INVITE", "ACK", "BYE", "CANCEL", "OPTIONS"] }, "started_at": "2026-03-09T12:00:00Z", "completed_at": "2026-03-09T12:00:05Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Parse SIP Destination Source: https://docs.bland.ai/api-v1/post/sip-parse-destination POST https://api.bland.ai/v1/sip/parse-destination Parse and validate a raw SIP destination string into its host, port, user, and transport before attaching it to a trunk. ### Headers Your API key for authentication. ### Body The SIP destination to parse. Accepts flexible formats — a hostname or IP (`sip.provider.com`, `203.0.113.10`), a full SIP URI (`sip:user@host:5061;transport=tls`), or shorthand (`tls://host`, `host:5061`). ### Response Whether the input could be parsed into a usable SIP destination. The parsed destination when `valid` is `true`, otherwise `null`. The resolved host or IP address. The port, when present in the input. The user part of the SIP URI, when present. The transport: `"udp"`, `"tcp"`, or `"tls"`, when present. `true` if the host is a private/non-routable IP address. The normalized SIP destination string. Use the parsed `host`, `port`, and `transport` to populate the `sip_endpoint` and `options` of a trunk or a [`POST /v1/sip/attach`](/api-v1/post/sip-attach) request. ```json Example Request theme={null} curl -X POST https://api.bland.ai/v1/sip/parse-destination \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "input": "sip:your.provider.com:5061;transport=tls" }' ``` ```json Response theme={null} { "data": { "valid": true, "parsed": { "host": "your.provider.com", "port": 5061, "transport": "tls", "is_private_ip": false, "normalized": "sip:your.provider.com:5061;transport=tls" } }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Upload Port Document Source: https://docs.bland.ai/api-v1/post/sip-port-document POST https://api.bland.ai/v1/sip/port/document Upload a Letter of Authorization (LOA) or proof of ownership document for number porting. ### Headers Your API key for authentication. ### Body (Multipart Form Data) The document file to upload. Accepted formats: PDF, JPEG, PNG, GIF, WebP. Maximum file size: 10MB. This should be a utility bill or carrier invoice dated within the last 30 days that shows the account name, owner/authorized user name, and service address. ### Response A unique document identifier to reference when initiating the port request. ```bash Example Request theme={null} curl -X POST https://api.bland.ai/v1/sip/port/document \ -H "Authorization: Bearer " \ -F "file=@/path/to/utility-bill.pdf" ``` ```json Response theme={null} { "data": { "document_sid": "doc_abc123" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Initiate Port Request Source: https://docs.bland.ai/api-v1/post/sip-port-initiate POST https://api.bland.ai/v1/sip/port/initiate Submit a number porting request to transfer phone numbers from another carrier to Bland. ### Headers Your API key for authentication. ### Body Array of phone numbers to port. Each must be in E.164 format. You should verify portability first using `GET /v1/sip/port/check`. Information about the current carrier: * `customer_type` (string) — `"business"` or `"personal"` * `business_name` (string) — Business name on the account (if business) * `first_name` (string) — Account holder first name * `last_name` (string) — Account holder last name * `account_number` (string) — Account number with the losing carrier * `authorized_representative_email` (string) — Email for LOA signing * `notification_emails` (array) — Additional emails for status updates * `address` (object) — Service address: `street`, `street2`, `city`, `state`, `zip`, `country` Requested port date in ISO 8601 format. Must be at least 7 days from today. If omitted, the earliest possible date is used. Array of document SIDs returned from `POST /v1/sip/port/document`. Account PIN from the losing carrier (required for some numbers — check via portability endpoint). ### Response Unique identifier for the port request. Initial status: `"waiting_for_signature"`. URL for electronically signing the Letter of Authorization. Array of phone numbers included in the port request. Number porting typically takes **7–14 business days**. Track progress via `GET /v1/sip/port` or the SIP Dashboard. **Port status flow:** `waiting_for_signature` → `submitted` → `in_progress` → `completed` ```json Example Request theme={null} curl -X POST https://api.bland.ai/v1/sip/port/initiate \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "phone_numbers": ["+14150000000", "+14150000001"], "losing_carrier_information": { "customer_type": "business", "business_name": "Acme Corp", "first_name": "Jane", "last_name": "Doe", "account_number": "ACC-12345", "authorized_representative_email": "jane@acme.com", "notification_emails": ["it@acme.com"], "address": { "street": "123 Main St", "street2": "Suite 100", "city": "San Francisco", "state": "CA", "zip": "94105", "country": "US" } }, "target_port_date": "2026-03-20T00:00:00Z", "documents": ["doc_abc123"] }' ``` ```json Response theme={null} { "data": { "port_request_id": "port_xyz789", "status": "waiting_for_signature", "signature_url": "https://sign.example.com/loa/port_xyz789", "phone_numbers": ["+14150000000", "+14150000001"] }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Send SIP Test Call Source: https://docs.bland.ai/api-v1/post/sip-test-call POST https://api.bland.ai/v1/sip/test-call Place a live test call to your SIP endpoint to verify connectivity. Rate limited to 10 calls per 15 minutes. ### Headers Your API key for authentication. ### Body The phone number with an outbound SIP configuration to test. Must be in E.164 format. ### Response A unique call identifier. Use this to poll the test call status. Confirmation message. Test calls are rate-limited to **10 per 15 minutes** per organization. ```json Example Request theme={null} curl -X POST https://api.bland.ai/v1/sip/test-call \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "phone_number": "+14150000000" }' ``` ```json Response theme={null} { "data": { "call_id": "tc_abc123", "message": "Test call initiated" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update SIP Direction Source: https://docs.bland.ai/api-v1/post/sip-update POST https://api.bland.ai/v1/sip/update Update an existing SIP routing direction for a phone number. ### Headers Your API key for authentication. ### Body The phone number to update. Must be in E.164 format. The updated direction object. Must include `type` (`"inbound"` or `"outbound"`). For outbound updates, you can modify `sip_endpoint`, `options` (port, transport, secure\_media, sip\_username, sip\_password), and `headers`. For inbound updates, you can modify `auth_mode`, `register_auth`, `sip_endpoint`, `options`, and `headers`. ### Response Returned when switching to or updating registration-based auth. Configure this password in your PBX. ```json Example Request theme={null} curl -X POST https://api.bland.ai/v1/sip/update \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "phone_number": "+14150000000", "updates": { "type": "outbound", "sip_endpoint": "sip:new.provider.com", "options": { "port": 5061, "transport": "tls", "secure_media": true } } }' ``` *** Docs for agents: [llms.txt](/llms.txt) # SMS Conversation Analysis Source: https://docs.bland.ai/api-v1/post/sms-analyze POST https://api.bland.ai/v1/sms/analyze Answer questions and extract information from an SMS conversation. ### Headers Your API key for authentication. ### Body The ID of the citation schema to use for extracting variables from the SMS conversation. The ID of the SMS conversation to analyze. ### Response The response data containing analysis results. The status of the analysis operation. Returns "success" on successful completion. The ID of the SMS conversation that was analyzed. The ID of the citation schema that was used for analysis. The name of the citation schema that was used. The total number of variables that were successfully extracted from the conversation. An object containing the extracted variables as key-value pairs, where keys are variable names and values are the extracted data. An array of citation objects that reference where each variable was found in the conversation. The name of the variable this citation references. The message text where the variable was found. The confidence score (0-1) for this extraction. The total number of messages in the conversation that were processed. An array of error objects. Empty array when the request is successful. ```json Response theme={null} { "data": { "status": "success", "conversation_id": "conv_123456", "schema_id": "schema_789", "schema_name": "Customer Intent Analysis", "variables_extracted": 5, "extracted_variables": { "customer_name": "John Smith", "preferred_time": "morning", "service_type": "moving", "urgency": "high", "budget_range": "$500-1000" }, "citations": [ { "variable": "customer_name", "message": "Hi, this is John Smith calling about...", "confidence": 0.95 } ], "messages_processed": 12 }, "errors": [] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Send SMS Batch Source: https://docs.bland.ai/api-v1/post/sms-batch POST https://api.bland.ai/v1/sms/batch Send SMS messages to a large list of recipients from a pre-uploaded CSV file. Processing is handled asynchronously via a background workflow. **Enterprise Feature** - SMS batch sending is only available on Enterprise plans. Contact your Bland representative for access. ### Before You Begin: Upload Your CSV Before calling this endpoint, you must upload your recipient CSV file and get a `file_id`. Upload your CSV via `POST https://api.bland.ai/v1/files/attach` with `file_type: "batches"`. The response will include a `file_id` (UUID) that you pass to this endpoint. **CSV format requirements:** * Must include a column named exactly **`phone_number`** containing E.164-formatted numbers (e.g. `+14155551234`). Numbers without a leading `+` are automatically prefixed. * The `phone_number` column **cannot be remapped** via `column_mapping` — the column must be named `phone_number` in the CSV itself. * Additional columns become dynamic variables available in your pathway via `{{column_name}}` syntax. * Columns named `request_data.fieldname` (dot notation) are automatically parsed into the recipient's `request_data` object. * JSON arrays of objects are also accepted as an alternative to CSV. Example CSV: ```csv theme={null} phone_number,first_name,request_data.account_id +14155551234,Alice,acc_001 +10987654321,Bob,acc_002 ``` *** ### Headers Your API key for authentication. ### Body Parameters The ID of a previously uploaded CSV file containing recipient phone numbers. The file must have been uploaded with `file_type: "batches"`. See [Before You Begin](#before-you-begin-upload-your-csv) above. Default SMS parameters applied to every message in the batch. The E.164 formatted phone number to send messages from. Must be an SMS-enabled inbound number configured on your account. The initial outbound message to send to each recipient. If omitted, the pathway configured on the number will handle the opening message. Default request data to associate with each conversation. Per-recipient `request_data` from the CSV is merged on top of this, with recipient values taking precedence. Custom metadata to attach to each conversation. Returned in all webhook payloads for correlating conversations with your internal systems. An array of outcome IDs to run when each conversation ends. If omitted, the outcomes configured on the SMS number are used. See [Outcomes](/tutorials/outcomes). An array of citation schema IDs to extract when each conversation ends. If omitted, the citation schemas configured on the SMS number are used. See [Citations](/enterprise-features/citations). Maps column names in your CSV to SMS send parameter names. Use this when your CSV column names don't match the expected field names. Use this to map non-phone columns to `request_data` or other SMS parameters. **Note:** `phone_number` cannot be used as a target — the phone number column in your CSV must be named `phone_number` exactly. Map columns to `request_data` to make them available as pathway variables: ```json theme={null} { "customer_name": "request_data", "preferred_lang": "request_data" } ``` Only `request_data` is supported as a target — per-recipient fields like `pathway_id` or `persona_id` cannot be overridden from the CSV. Alternatively, use dot notation column names in your CSV directly (e.g. `request_data.customer_name`) to avoid needing `column_mapping` at all. ### Response Confirmation that the batch was accepted for processing. Confirmation message indicating the batch was queued. The `file_id` used for this batch, for reference. The ID of the background workflow processing this batch. `null` on success, or a list of error objects if the request failed. ```json Request theme={null} { "file_id": "file_abc123", "global": { "agent_number": "+14155551234", "pathway_id": "pathway_xyz789", "channel": "sms" }, "column_mapping": { "customer_name": "request_data" } } ``` ```json Response (Success) theme={null} { "data": { "message": "SMS batch processing initiated via Temporal workflow", "batch_id": "file_abc123", "workflow_id": "workflow_def456" }, "errors": null } ``` ```json Error Response (Missing file_id) theme={null} { "data": null, "errors": [ { "error": "MISSING_FILE_ID", "message": "file_id is required" } ] } ``` ```json Error Response (File not found) theme={null} { "data": null, "errors": [ { "error": "FILE_NOT_FOUND", "message": "File not found or invalid file type for SMS batches" } ] } ``` ```json Error Response (Agent number not found) theme={null} { "data": null, "errors": [ { "error": "AGENT_NUMBER_NOT_FOUND", "message": "Agent number not found or not configured for SMS" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create SMS Conversation Source: https://docs.bland.ai/api-v1/post/sms-create POST https://api.bland.ai/v1/sms/create Create an SMS conversation with specific pathway state without triggering immediate message sending. **Enterprise Feature** - SMS is only available on Enterprise plans. Contact your Bland representative for access. ### Headers Your API key for authentication. ### Body Parameters The E.164 formatted phone number of the user in the conversation. The E.164 formatted phone number used by the agent (must belong to the authenticated account). The content of the message to be stored in the conversation history. Optional Twilio message SID for tracking and correlation purposes. The UUID of the current pathway being used in this conversation. The specific version of the pathway to use (e.g., "latest", "v1.0"). The ID of the current node in the conversational pathway where this conversation is positioned. Optional metadata to associate with the conversation. Used for custom routing or analytics. When set to true, forces creation of a new conversation, archiving any existing active conversation between these numbers. Specifies who sent this message. Allowed values: "USER" or "AGENT". Defaults to "USER" if not specified. Per-conversation timeout override, in seconds. When the user goes silent for this long after an agent message, the timeout flow fires (warning message and/or conversation end). Takes priority over the `time_out` on the number's sms\_config/whatsapp\_config. Persists on the conversation, so subsequent turns use the same override until another `/send` or `/create` replaces it. Per-conversation override for the message sent when the timeout fires. Takes priority over `timeout_message` on sms\_config/whatsapp\_config. Per-conversation override for how long, in seconds, to wait before sending the warning message. Must be less than `time_out`; the request is rejected with `INVALID_TIMEOUT_CONFIG` otherwise. Takes priority over `warning_time` on sms\_config/whatsapp\_config. Per-conversation override for the warning message sent at `warning_time`. Takes priority over `warning_message` on sms\_config/whatsapp\_config. ### Response An object confirming the conversation was created successfully. Confirmation text for the successful conversation creation. ID of the conversation that was created. ID of the Temporal workflow triggered to process the conversation setup. `null` on success, or a list of error objects if the request failed. ```json Response theme={null} { "data": { "message": "SMS conversation created successfully", "conversation_id": "conv_abc123", "workflow_id": "workflow_xyz789" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Send SMS Message Source: https://docs.bland.ai/api-v1/post/sms-send POST https://api.bland.ai/v1/sms/send Send an SMS message from an agent to a user. This creates or resumes a conversation and triggers processing workflows. **Enterprise Feature** - SMS is only available on Enterprise plans. Contact your Bland representative for access. ### Headers Your API key for authentication. A unique key to prevent duplicate message sends. When provided, repeated requests with the same key will return successfully but will not send an additional message or incur extra charges. Useful for safely retrying failed requests without risk of double-sending. ### Body Parameters The E.164 formatted phone number of the user receiving the message. The E.164 formatted phone number used to send the message (must belong to the authenticated account). The content of the SMS message to send. If not passed in, this generates a response using the pathway/prompt the conversation has been setup with. Optional metadata to associate with the conversation or message. Used for custom routing or analytics. Allows you to create a new conversation, archiving the existing conversation and ignores existing sms messages. UUID of a persona to use for this conversation. When provided, the persona's configuration is applied instead of the number's SMS config. Use `persona_version` to select which version to use. Cannot be used as a substitute for `agent_number` — the agent number must still belong to your account. The persona\_id controls *how* the conversation is handled, not *which number* sends it. Which version of the persona to use. Allowed values: `"production"` (default), `"draft"`. Per-dispatch persona overrides. Takes priority over any pathway settings on the persona version or the `pathway_id` field below. Override the persona's pathway for this dispatch. Specific version of the override pathway to use. Specific node to start from within the override pathway. ID of the pathway to use for generating the SMS response. If `persona_id` is provided, this is used as a pathway override within the persona context (lower priority than `persona_settings`). Version of the pathway to use. ID of the specific node within the pathway to start from. This overrides the webhook for the conversation, instead of using the webhook attached to the phone number. Custom metadata to attach to the conversation. This data is returned in all webhook payloads (message and status webhooks), making it useful for correlating conversations with your internal systems. An array of outcome IDs to run when the conversation ends. If omitted, the outcomes configured on the SMS number are used. If provided, overrides the number's configuration. See [Outcomes](/tutorials/outcomes) for details. An array of citation schema IDs to extract when the conversation ends. If omitted, the citation schemas configured on the SMS number are used. If provided, overrides the number's configuration. See [Citations](/enterprise-features/citations) for details. The channel to send the message on. Defaults to "sms". Allowed values: "sms", "whatsapp", "imessage". For numbers provisioned for iMessage, the channel is auto-derived from the number's configuration, so you don't need to set this explicitly. See [iMessage](/tutorials/messaging/imessage) for details. The Twilio SID of the content to send, usually in HXXXX format. The variables to send with the content. Example: ```json theme={null} { "1": "John", "2": "Smith", "3": "Premium Plan" } ``` Per-conversation timeout override, in seconds. When the user goes silent for this long after an agent message, the timeout flow fires (warning message and/or conversation end). Takes priority over the `time_out` on the number's sms\_config/whatsapp\_config. Persists on the conversation, so subsequent turns use the same override until another `/send` or `/create` replaces it. Per-conversation override for the message sent when the timeout fires. Takes priority over `timeout_message` on sms\_config/whatsapp\_config. Per-conversation override for how long, in seconds, to wait before sending the warning message. Must be less than `time_out`; the request is rejected with `INVALID_TIMEOUT_CONFIG` otherwise. Takes priority over `warning_time` on sms\_config/whatsapp\_config. Per-conversation override for the warning message sent at `warning_time`. Takes priority over `warning_message` on sms\_config/whatsapp\_config. ### Response An object confirming the message was sent and referencing the triggered workflow. Confirmation text for the successful send. ID of the conversation that was created or resumed. ID of the message that was sent, if a single message was sent, to track message delivery and status. `null` on success, or a list of error objects if the request failed. ```json Response theme={null} { "data": { "message": "SMS sent successfully", "conversation_id": "convo_abc123", "workflow_id": "workflow_xyz789" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update SMS Configuration Source: https://docs.bland.ai/api-v1/post/sms-update POST https://api.bland.ai/v1/sms/number/update Update the SMS configuration for a phone number owned by the authenticated user. **Enterprise Feature** - SMS is only available on Enterprise plans. Contact your Bland representative for access. ### Headers Your API key for authentication. ### Body Parameters The E.164 formatted phone number to update (must belong to the authenticated user). When the agent sends a response, we’ll send the message details in a POST request to the URL you specify here, along with chat history. Request data fields are available to the AI agent during the call when referenced in the associated pathway or task. Maximum time to wait for a user response, in seconds, before the timeout flow fires. Default is no timeout. Can be overridden per-conversation via `/v1/sms/send` or `/v1/sms/create`. What to do when the timeout fires. Allowed values depend on your configuration (e.g. `"send_sms"` to send `timeout_message`). Message sent when the timeout fires. Can be overridden per-conversation via `/v1/sms/send` or `/v1/sms/create`. Seconds to wait before sending the warning message. Must be less than `time_out`, otherwise the update is rejected. Can be overridden per-conversation via `/v1/sms/send` or `/v1/sms/create`. Message sent at `warning_time`. Can be overridden per-conversation via `/v1/sms/send` or `/v1/sms/create`. Twilio Messaging Service SID, if set. Assistant system prompt or conversational goal. List of tools available to the assistant. The model’s temperature setting, controlling creativity. The ID of the linked conversational pathway (if any). The specific version of the pathway to use. Entry point node ID for the pathway. When `true`, a new conversation is automatically started if the user texts after the current conversation has ended. When `false`, subsequent messages are stored in the ended conversation without triggering a new reply. The timezone used for time-based variables in the conversation (e.g. `"America/New_York"`). Custom prompt used to generate a conversation summary when the conversation ends. When set, an AI-generated summary is included in the status webhook and stored on the conversation. An array of outcome IDs to run when conversations end on this number. See [Outcomes](/tutorials/outcomes). An array of citation schema IDs to extract when conversations end on this number. See [Citations](/enterprise-features/citations). ### Response Contains a confirmation message and the updated SMS configuration. Success message confirming the update. The updated and sanitized SMS configuration object. `null` on success. If an error occurs, this will be an array of error objects. A human-readable description of the error. A machine-readable error code. ```json Response theme={null} { "data": { "message": "SMS config updated for number +15550001111", "sms_config": { "webhook": null, "request_data": [], "time_out": null, "timeout_action": null, "timeout_message": null, "warning_time": null, "warning_message": null, "messaging_service_sid": null, "objective": "Chat with the user", "tools": [], "temperature": 0, "pathway_id": null, "pathway_version": null, "start_node_id": null, "restart_after_end_call": true, "timezone": null, "summary_prompt": null, "disposition_ids": null, "citation_schema_ids": null } }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create a Custom Tool Source: https://docs.bland.ai/api-v1/post/tools POST https://api.bland.ai/v1/tools Create a Custom Tool that can take AI input and call external APIs. ### Headers Your API key for authentication. ### Body This is the name that the AI using the tool will see. Some other internal tools are named `Speak`, `Wait`, `Transfer` and `Finish` - Custom Tools cannot share these names. We've made a list of reserved words that can confuse the AI that cannot be included: * `input` * `speak` * `transfer` * `switch` * `wait` * `finish` * `press` * `button` * `say` * `pause` * `record` * `play` * `dial` * `hang` Choosing too similar of names to the default tools could cause the AI to select the wrong one, so decriptive two to three-word names are preferred. This is the description that the AI using the tool will see. Describe the effect of what the tool does or any special instructions. For reference, here are the default tools' descriptions: * `Speak`: Talk to the person on the other end of the line * `Press Buttons`: Presses buttons on phone. Each character is a different button. * `Wait`: Wait and go silent for an extended period of time (only use if absolutely necessary). * `Finish`: Say a goodbye message and end the call once completed. This is the text that the AI will say while it uses the tool. For example, if the tool is a "GenerateQuote" tool, the speech might be "Please wait while I get you your quote." Since tools can be verbally interrupted, shorter messages that tell the user what the tool/AI are doing are best. Special Note: You can have the AI dynamically generate speech by defining `input.speech` in the `input_schema`. ```json theme={null} { "input_schema": { "example": { "speech": "Checking your account details right now John!", "name": "John Doe", "email": "johndoe@gmail.com" }, "type": "object", "properties": { "speech": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": ["speech", "name", "email"] } } ``` This is the endpoint of the external API that the tool will call. It must begin with `https://` and be a valid URL. This is the HTTP method that the tool will use to call the external API. Valid options are `GET` and `POST`. `SUPPORTS PROMPT VARIABLES` These are the headers that the tool will send to the external API. The headers must be in JSON format. Since prompt variables are supported, you can use them in the headers to send dynamic information to the external API. ```json theme={null} // At the top level of your send call request you can define variables that you can access later using the double curly braces/dot syntax. { "request_data": { "api_key": "sk-1234567890", }, "tools": [ { "headers": { "Authorization": "Bearer {{api_key}}" } } ] } ``` `SUPPORTS PROMPT VARIABLES` This is the body that the tool will send to the external API. The body must be in JSON format. This is the most common place to use Prompt Variables with AI input. Note: `GET` requests do not have a body. ```json theme={null} // AI-generated input is created as the `input` Prompt Variable - and the structure is defined by the input schema. // `input` will match the structure of `input_schema.example` if it is defined. { "input_schema": { "example": { "name": "John Doe", "email": "johndoe@gmail.com" } } "body": { "name": "{{input.name}}", "email": "{{input.email}}" } } ``` `SUPPORTS PROMPT VARIABLES` Append query parameters to the URL. The query must be in JSON format. This is generally used with GET requests and built-in Prompt Variables like `"{{phone_number}}"` or `"{{call_id}}"`. ```json theme={null} // appends ?pn={{phone_number}}&callId={{call_id}} to the URL { "query": { "pn": "{{phone_number}}", "callId": "{{call_id}}" } } ``` This is the schema that the AI input must match for the tool to be used. The schema must be in JSON format. The schema is used to validate the AI input before the tool is used. If the AI input does not match the schema, the tool will not be used and the AI will move on to the next tool. `input_schema.example` can be used to enhance the AI's understanding of the input structure and helps significantly with structured or nested data. Special Note: `input_schema` does not require strict JSON schema structure, and creativity is encouraged. [Look here for a general guide on JSON schema structures.](https://json-schema.org/learn/getting-started-step-by-step) Non-traditional JSON schema structures are supported as well, like these examples: * "options": "monday, wednesday, friday" * "date": "YYYY-MM-DD" * "time": "HH:MM:SS (AM|PM)" * "phone\_number": "+1XXX-XXX-XXXX" Agent input can be nested, and the will be transformed into JSON even if it's initially a string. ```json theme={null} { "input_schema": { "example": { "name": "John Doe", "email": "johndoe@gmail.com" }, "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": ["name", "email"] }, // both of these methods are identical, since {{input}} will be transformed into JSON "body": "{{input}}", "body": { "name": "{{input.name}}", "email": "{{input.email}}" } } ``` Define how you would like to extract data from the response. By default, the entire response body is stored in the `{{data}}` Prompt Variable. The path to the data you want must be in JSON Path format. Generally this means using dot notation to traverse the JSON object and is only required if you need to use that information on other tools or the response is too large. Example: ```json theme={null} // If the external API response is: { "available_times": [ { "time": "10:00 AM", "date": "2022-01-01" }, { "time": "11:00 AM", "date": "2022-01-01" } ], "store_hours": { "open": "9:00 AM", "close": "5:00 PM" }, "address_info": { "street": "123 Main St", "city": "Anytown", "state": "CA", "zip": "12345" } } // You can extract new Prompt Variables like this: { "response": { "available_times": "$.available_times", "store_hours": "$.store_hours", "address_info": "$.address_info", "zip_code": "$.address_info.zip" } } // And then it'll automatically replace them elsewhere (like in the `task`/`prompt`) { "task": "The store is open from {{store_hours.open}} to {{store_hours.close}}.", "prompt": "The store is located at {{address_info.street}}, {{address_info.city}}, {{address_info.state}} {{zip_code}}." } ``` This is the maximum time in milliseconds that the tool will wait for a response from the external API. If the external API does not respond within this time, the tool will fail and the AI will move on to the next tool. The default timeout is 10 seconds (10000 milliseconds). To always wait for a response, set the timeout to an extremely high value like 99999999. ### Response Whether the tool creation succeeded. A tool id that you can use to reference the tool in the future. In a Send Call request, you could pass this tool id in instead of the full Custom Tool object like so: ```json theme={null} { "tools": [ "TL-1234567890" // tool_id (instead of the full Custom Tool object) ] } ``` ```json theme={null} { "status": "success", "tool_id": "TL-1234567890" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Custom Tool Source: https://docs.bland.ai/api-v1/post/tools-tool-id POST https://api.bland.ai/v1/tools/{tool_id} Change your Custom Tool's parameters and characteristics. ### Headers Your API key for authentication. ### Path Parameters The ID of the Custom Tool you want to update. ### Body This is the name that the AI using the tool will see. Some other internal tools are named `Speak`, `Wait`, `Transfer` and `Finish` - Custom Tools cannot share these names. We've made a list of reserved words that can confuse the AI that cannot be included: * `input` * `speak` * `transfer` * `switch` * `wait` * `finish` * `press` * `button` * `say` * `pause` * `record` * `play` * `dial` * `hang` Choosing too similar of names to the default tools could cause the AI to select the wrong one, so decriptive two to three-word names are preferred. This is the description that the AI using the tool will see. Describe the effect of what the tool does or any special instructions. For reference, here are the default tools' descriptions: * `Speak`: Talk to the person on the other end of the line * `Press Buttons`: Presses buttons on phone. Each character is a different button. * `Wait`: Wait and go silent for an extended period of time (only use if absolutely necessary). * `Finish`: Say a goodbye message and end the call once completed. This is the text that the AI will say while it uses the tool. For example, if the tool is a "GenerateQuote" tool, the speech might be "Please wait while I get you your quote." Since tools can be verbally interrupted, shorter messages that tell the user what the tool/AI are doing are best. Special Note: You can have the AI dynamically generate speech by defining `input.speech` in the `input_schema`. ```json theme={null} { "input_schema": { "example": { "speech": "Checking your account details right now John!", "name": "John Doe", "email": "johndoe@gmail.com" }, "type": "object", "properties": { "speech": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": ["speech", "name", "email"] } } ``` This is the endpoint of the external API that the tool will call. It must begin with `https://` and be a valid URL. This is the HTTP method that the tool will use to call the external API. Valid options are `GET` and `POST`. `SUPPORTS PROMPT VARIABLES` These are the headers that the tool will send to the external API. The headers must be in JSON format. Since prompt variables are supported, you can use them in the headers to send dynamic information to the external API. ```json theme={null} // At the top level of your send call request you can define variables that you can access later using the double curly braces/dot syntax. { "request_data": { "api_key": "sk-1234567890", }, "tools": [ { "headers": { "Authorization": "Bearer {{api_key}}" } } ] } ``` `SUPPORTS PROMPT VARIABLES` This is the body that the tool will send to the external API. The body must be in JSON format. This is the most common place to use Prompt Variables with AI input. Note: `GET` requests do not have a body. ```json theme={null} // AI-generated input is created as the `input` Prompt Variable - and the structure is defined by the input schema. // `input` will match the structure of `input_schema.example` if it is defined. { "input_schema": { "example": { "name": "John Doe", "email": "johndoe@gmail.com" } } "body": { "name": "{{input.name}}", "email": "{{input.email}}" } } ``` `SUPPORTS PROMPT VARIABLES` Append query parameters to the URL. The query must be in JSON format. This is generally used with GET requests and built-in Prompt Variables like `"{{phone_number}}"` or `"{{call_id}}"`. ```json theme={null} // appends ?pn={{phone_number}}&callId={{call_id}} to the URL { "query": { "pn": "{{phone_number}}", "callId": "{{call_id}}" } } ``` This is the schema that the AI input must match for the tool to be used. The schema must be in JSON format. The schema is used to validate the AI input before the tool is used. If the AI input does not match the schema, the tool will not be used and the AI will move on to the next tool. `input_schema.example` can be used to enhance the AI's understanding of the input structure and helps significantly with structured or nested data. Special Note: `input_schema` does not require strict JSON schema structure, and creativity is encouraged. [Look here for a general guide on JSON schema structures.](https://json-schema.org/learn/getting-started-step-by-step) Non-traditional JSON schema structures are supported as well, like these examples: * "options": "monday, wednesday, friday" * "date": "YYYY-MM-DD" * "time": "HH:MM:SS (AM|PM)" * "phone\_number": "+1XXX-XXX-XXXX" Agent input can be nested, and the will be transformed into JSON even if it's initially a string. ```json theme={null} { "input_schema": { "example": { "name": "John Doe", "email": "johndoe@gmail.com" }, "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": ["name", "email"] }, // both of these methods are identical, since {{input}} will be transformed into JSON "body": "{{input}}", "body": { "name": "{{input.name}}", "email": "{{input.email}}" } } ``` Define how you would like to extract data from the response. By default, the entire response body is stored in the `{{data}}` Prompt Variable. The path to the data you want must be in JSON Path format. Generally this means using dot notation to traverse the JSON object and is only required if you need to use that information on other tools or the response is too large. Example: ```json theme={null} // If the external API response is: { "available_times": [ { "time": "10:00 AM", "date": "2022-01-01" }, { "time": "11:00 AM", "date": "2022-01-01" } ], "store_hours": { "open": "9:00 AM", "close": "5:00 PM" }, "address_info": { "street": "123 Main St", "city": "Anytown", "state": "CA", "zip": "12345" } } // You can extract new Prompt Variables like this: { "response": { "available_times": "$.available_times", "store_hours": "$.store_hours", "address_info": "$.address_info", "zip_code": "$.address_info.zip" } } // And then it'll automatically replace them elsewhere (like in the `task`/`prompt`) { "task": "The store is open from {{store_hours.open}} to {{store_hours.close}}.", "prompt": "The store is located at {{address_info.street}}, {{address_info.city}}, {{address_info.state}} {{zip_code}}." } ``` This is the maximum time in milliseconds that the tool will wait for a response from the external API. If the external API does not respond within this time, the tool will fail and the AI will move on to the next tool. The default timeout is 10 seconds (10000 milliseconds). To always wait for a response, set the timeout to an extremely high value like 99999999. ### Response Whether the tool creation succeeded. A tool id that you can use to reference the tool in the future. In a Send Call request, you could pass this tool id in instead of the full Custom Tool object like so: ```json theme={null} { "tools": [ "TL-1234567890" // tool_id (instead of the full Custom Tool object) ] } ``` ```json theme={null} { "status": "success", "tool_id": "TL-1234567890" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Translation Session Source: https://docs.bland.ai/api-v1/post/translation-sessions POST https://api.bland.ai/v1/translation/sessions Create a real-time translation session and receive a WebSocket URL for streaming audio Creates a translation session and returns a single-use WebSocket URL. Stream audio in your source language and receive translated speech back in real time — along with transcript events for every translated utterance. See the [Live Translation API tutorial](/tutorials/translation) for the full streaming protocol, audio formats, and integration walkthrough. ## Authentication Your API key for authentication. The key must belong to an organization — user-scoped keys without an organization are rejected with `403 TAAS_ORG_REQUIRED`. ## Body Parameters Language the inbound audio is spoken in. Supported codes: `en`, `es`, `fr`, `de`, `it`, `pt`, `nl`, `pl`, `sv`, `fi`, `da`, `cs`, `el`, `ro`, `ru`, `tr`, `ar`, `hi`, `id`, `tl`, `zh`, `ja`, `ko` Language to translate into. Same supported codes as `source_language`. UUID of a Bland voice to use for the translated speech. Must belong to your organization. Defaults to a standard voice for the target language. Wire format for audio on the WebSocket. One of: * `pcm16` — raw PCM-16 little-endian binary frames * `twilio_ulaw` — Twilio Media Streams JSON envelopes carrying 8kHz μ-law audio, for direct interop with Twilio `` Sample rate of the audio you will send, in Hz. `pcm16` mode only — integer between `8000` and `48000`. `16000` is recommended. Do not set this for `twilio_ulaw` (Twilio audio is always 8kHz). Maximum session length in seconds, between `30` and `1800`. The session ends automatically when this limit is reached. ## Response Unique identifier for the session. Use it with the GET and DELETE endpoints. WebSocket URL to connect to. **Treat this as opaque** — connect to it exactly as returned. Do not parse or reconstruct it. Session token. Already embedded in `ws_url`; returned separately for reference. ISO timestamp. Connect to `ws_url` before this time (10 minutes after creation) or the session is abandoned. The resolved maximum session length. Array of error objects if the request failed The `ws_url` is **single-use**: it authenticates exactly one WebSocket connection. If your connection drops, create a new session — reconnecting with the same URL is rejected with close code `4001`. ## Limits & Billing * Sessions are billed **per minute** of connected time, rounded up. The per-minute rate depends on your plan. * Up to **3 concurrent sessions** per organization (pending sessions count until they expire). Contact us to raise this limit. * A daily translation-minutes rate limit applies per organization. ```bash cURL theme={null} curl -X POST "https://api.bland.ai/v1/translation/sessions" \ -H "Authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "source_language": "en", "target_language": "es", "audio_protocol": "pcm16", "sample_rate": 16000 }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.bland.ai/v1/translation/sessions", { method: "POST", headers: { "Authorization": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ source_language: "en", target_language: "es", audio_protocol: "pcm16", sample_rate: 16000, }), }); const { data } = await response.json(); const ws = new WebSocket(data.ws_url); // connect within 10 minutes ``` ```python Python theme={null} import requests response = requests.post( "https://api.bland.ai/v1/translation/sessions", headers={"Authorization": "YOUR_API_KEY"}, json={ "source_language": "en", "target_language": "es", "audio_protocol": "pcm16", "sample_rate": 16000, }, ) data = response.json()["data"] print(data["ws_url"]) # connect within 10 minutes ``` ```json Success theme={null} { "data": { "session_id": "9592342c-0ed2-4c5e-8ceb-16aa55c804a7", "ws_url": "wss://stream-v2.aws.dc8.bland.ai/ws/translate/eyJhbGciOiJBMjU2R0NNS1ciLCJlbmMiOiJBMjU2R0NN...", "token": "fe120676-1b18-4c87-b6fc-c984e719d3bc", "expires_at": "2026-06-04T18:15:07.885Z", "max_duration_seconds": 1800 }, "errors": null } ``` ```json Concurrency Cap theme={null} { "data": null, "errors": [ { "error": "TOO_MANY_REQUESTS", "message": "CONCURRENCY_CAP_EXCEEDED" } ] } ``` ## WebSocket Connection After creating a session, connect to the returned `ws_url` within 10 minutes: * **URL**: Use `ws_url` exactly as returned — it is opaque and single-use. Do not parse or reconstruct it. * **Protocol**: WebSocket (WSS) * **Authentication**: Embedded in the URL — no headers required * **Frames**: Binary frames carry audio; text frames carry JSON control events You can start sending audio immediately on connection open — frames are buffered server-side until the pipeline is ready. ### Audio Format: `pcm16` | Direction | Format | | -------------- | ----------------------------------------------------------------------------------- | | Client → Bland | Binary frames of raw PCM-16 little-endian mono audio at your declared `sample_rate` | | Bland → Client | Binary frames of raw PCM-16 little-endian mono audio at **16,000 Hz** | No framing or headers — raw samples only. 20ms chunks (640 bytes at 16kHz) are typical. ### Audio Format: `twilio_ulaw` All frames are JSON text in [Twilio Media Streams](https://www.twilio.com/docs/voice/media-streams) shape — base64 8kHz μ-law audio in `media.payload`. Send a `start` event first so outbound envelopes echo your `streamSid`: ```json theme={null} { "event": "start", "start": { "streamSid": "MZ..." } } { "event": "media", "media": { "payload": "" } } { "event": "stop" } ``` Outbound translated audio arrives as `{"event":"media","streamSid":"","media":{"payload":""}}`. ### Control Events JSON text frames from the server, discriminated by `type`: | Event | When | Key fields | | --------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `ready` | Pipeline warmed up; transcripts begin flowing after this | `session_id` | | `transcript` | One finalized utterance was translated | `turn_id`, `original`, `translation`, `source_language`, `target_language`, `is_final` | | `tts_complete` | All translated audio for a turn has been written to the WebSocket | `turn_id`, `audio_duration_ms` | | `session_ended` | Terminal notification — last JSON frame before close | `reason`, `session_seconds`, `end_reason` | | `error` | Fatal session failure, followed by `session_ended` and close | `code`, `message`, `fatal` | ```json Example transcript event theme={null} { "type": "transcript", "turn_id": "5862a126-2e88-46b1-bb95-0ed5c57155c1", "original": "Hello. This is a translation test.", "translation": "Hola. Esta es una prueba de traducción.", "source_language": "en", "target_language": "es", "is_final": true } ``` * `audio_duration_ms` is currently always `0` — a placeholder. Do not rely on it. * A `tts_complete` may be absent for a turn whose speech synthesis failed — don't block on it. The transcript still arrives. * Error codes that can fire: `taas/audio_protocol_mismatch` and `taas/internal_error`, both `fatal: true`. * `session_ended.reason` is one of `client_disconnect`, `max_duration`, `error`, `api_terminated`. ### Close Codes | Code | Meaning | | ------ | ------------------------------------------------------ | | `1000` | Normal close after `session_ended` | | `1011` | Internal server error | | `4001` | Invalid, expired, or already-used session token | | `4002` | Session not found | | `4003` | Session already ended | | `4004` | First frame didn't match the declared `audio_protocol` | | `4005` | `max_duration_seconds` reached | ## Notes * Translated audio can arrive faster than real time — buffer client-side and play at the natural rate * Reconnection is not supported; if the WebSocket drops, create a new session * The WebSocket closes automatically at `max_duration_seconds` # Create Category Source: https://docs.bland.ai/api-v1/post/triage-categories POST https://api.bland.ai/v1/triage/categories Create a custom issue category. ## Overview Adds a category to your org's catalog. Issue `category` is free-form on creation, so this endpoint is only needed when you want a category to appear in pickers before any issue uses it. *** ## Headers Your API key for authentication. *** ## Body Parameters Category name. 1-64 characters. Case is preserved. *** ## Response Returns `201 Created` with the new category. UUID of the new category. `null` on success. ```json Response theme={null} { "data": { "id": "5cc60a90-dfa3-4bd9-a8e7-5ee4dd1e1b87", "org_id": "5fa6dc9e-ec4d-4f94-9e0e-21f6f6a1e8f1", "name": "Voicemail Detection", "created_at": "2026-05-07T05:32:42.086Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Issue Source: https://docs.bland.ai/api-v1/post/triage-issues POST https://api.bland.ai/v1/triage/issues Create a triage issue. ## Overview Opens a new triage issue, optionally with the calls, SMS conversations, or files that prompted it. Issues are the unit of work in [Triage](https://app.bland.ai/dashboard/monitor/triage). *** ## Headers Your API key for authentication. *** ## Body Parameters Short, human-readable summary of the issue. 1-200 characters. How urgent the issue is. Must be one of: * `critical` * `high` * `medium` * `low` Free-form category label, 1-64 characters. Categories are scoped to your org and reused across issues. The dashboard ships with these defaults out of the box, but you can add your own with [Create Category](/api-v1/post/triage-categories): * `Transcription` * `Speech` * `Dialogue` * `Routing` * `Tools` * `Latency` * `Telephony` * `Bug` Longer explanation of the problem. Maximum 10,000 characters. Shown to Norm as part of the evidence snapshot when you prompt the agent. Initial status. Defaults to `todo` if omitted. Must be one of: * `backlog` * `todo` * `in_progress` * `in_review` * `done` * `closed` Where the issue originated. Must be one of: * `manual`, created by a user from the dashboard or API (default) * `automated`, created by an automated rule (e.g. an alert binding) * `client`, created by a client integration on the user's behalf User ID of the person ultimately accountable for the issue. User ID of the person currently working on the issue. Evidence to attach to the issue at creation. Each entry links the issue to a call, SMS conversation, or uploaded file. ```json theme={null} { "resource_links": [ { "resource_type": "call", "resource_id": "d8ef6e50-830b-4c73-a956-3b04a1f28550" }, { "resource_type": "file", "resource_id": "54eaa506-8b68-4be7-8d14-1ff260899eee" } ] } ``` * `resource_type`, one of `call`, `sms_conversation`, or `file`. * `resource_id`, the ID of the resource. For calls this is the `call_id` returned by [Send Call](/api-v1/post/calls). *** ## Response Returns `201 Created` with the newly created issue. The created issue. Internal UUID of the issue. Use this in all `/v1/triage/issues/{id}/...` endpoints. Short, human-friendly issue identifier (for example `T-1001`) shown in the dashboard. The org that owns this issue. Sequential issue number within your org. Matches the numeric portion of `triage_id`. One of `backlog`, `todo`, `in_progress`, `in_review`, `done`, `closed`. One of `critical`, `high`, `medium`, `low`. One of `manual`, `automated`, `client`. User ID of the caller that created the issue. External system link (for example a GitHub issue) bound to this triage issue, if any. Number of attached resources (calls, SMS, files). Number of flags raised against attached calls. Number of related issues linked to this one. The most recent Norm session bound to this issue, including its run state and any draft pathway version Norm is working against. `null` if Norm has never been prompted for this issue. `true` while Norm is actively running against the issue. `true` if there is activity since the caller last viewed the issue. ISO 8601 timestamp. ISO 8601 timestamp. ISO 8601 timestamp of the most recent activity entry. `null` on success, or a list of error objects if the request failed. ```json Response theme={null} { "data": { "id": "68007859-4325-4ea2-bbd6-e7c8be3a233a", "triage_id": "T-1001", "org_id": "685b69b7-b903-4d98-9755-af3c957df9e3", "number": 1001, "title": "Agent skipped the verification step", "description": "On the Aug 12 demo flow the agent jumped to the closing node without asking for the email confirmation.", "status": "todo", "severity": "high", "source": "manual", "category": "Routing", "owner_id": null, "assignee_id": "beed099d-e493-4142-a68b-af13bd72c035", "author_id": "4d5ac1b5-1f24-46d3-8355-5debfd029a65", "external_link": null, "created_at": "2026-05-06T21:09:57.081Z", "updated_at": "2026-05-06T21:09:57.081Z", "last_activity_at": "2026-05-06T21:09:57.081Z", "resource_count": 1, "flag_count": 0, "relation_count": 0, "latest_agent_session": null, "is_processing": false, "has_unread_activity": false }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Agent Session Source: https://docs.bland.ai/api-v1/post/triage-issues-id-agent-sessions POST https://api.bland.ai/v1/triage/issues/{id}/agent-sessions Create a Norm agent session on an issue. ## Overview Creates a Norm session on an issue. Most callers can skip this, [Prompt Norm](/api-v1/post/triage-issues-id-agent-sessions-session-id-prompts) creates a session implicitly on the first prompt. Use this only when you want to mount the session in your UI before the first prompt is sent. *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. *** ## Body Parameters This endpoint takes no body parameters. Pass an empty body or `{}`. *** ## Response Returns `201 Created` with a session summary. Internal UUID of the session. Pass this as `{session_id}` to [Prompt Norm](/api-v1/post/triage-issues-id-agent-sessions-session-id-prompts). ID of the agent profile backing this session, from [List Agents](/api-v1/get/triage-agents). Always `Norm`. Lifecycle status. New sessions are returned with `status: "active"`. The full set of values that can appear on a session (for example via the issue's `latest_agent_session.status` field) is: `pending`, `active`, `awaiting_input`, `complete`, `error`, `cancelled`. `null` on success. Returns 404 if the issue does not exist. ```json Response theme={null} { "data": { "id": "0431f6ad-fdd3-4408-a6cc-909842d1db41", "agent_profile_id": "66720f06-f492-4ce6-a2f2-cd84fd54613e", "agent_name": "Norm", "status": "active" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Prompt Norm Source: https://docs.bland.ai/api-v1/post/triage-issues-id-agent-sessions-session-id-prompts POST https://api.bland.ai/v1/triage/issues/{id}/agent-sessions/{session_id}/prompts Send a prompt to Norm. Returns 202 with a run ID. ## Overview Dispatches a Norm run against the issue. Asynchronous, returns 202 once queued. Progress, tool calls, and final output stream into the issue's [Activity feed](/api-v1/get/triage-issues-id-activity) as `entry_kind: "agent"` entries. The first word of `detail` is parsed as an intent. Slashes are optional. * `/fix` (default), full read+write toolbelt including pathway editing, tool config, and snippet/pipeline tests. * `/verify`, read-only. Norm checks the current draft against the evidence and reports. * `/status`, read-only. Norm summarizes current state, leading diagnosis, and any draft verification. * `/debug`, alias for `/fix`. The `@norm` mention in [Add Comment](/api-v1/post/triage-issues-id-comments) calls this same flow. *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. Internal UUID of the agent session, from [Create Agent Session](/api-v1/post/triage-issues-id-agent-sessions) or the `latest_agent_session.id` field on the issue. *** ## Body Parameters The prompt to send to Norm. 1-4000 characters. Begin with `/fix`, `/verify`, `/status`, or `/debug` to set the intent. The intent prefix is stripped before the message reaches Norm. *** ## Response Returns `202 Accepted`. The body acknowledges the dispatch but does not include Norm's reply. Subscribe to the issue's [Activity feed](/api-v1/get/triage-issues-id-activity) (or refetch it on a poll) to read Norm's progress and final output. ID of the session the prompt was dispatched to. Matches the `{session_id}` in the URL. ID of the Norm run created for this prompt. Each prompt produces one run; multi-turn conversations on the same session produce multiple runs. The parsed intent. One of `fix`, `verify`, or `status`. `/debug` is normalized to `fix`. `null` on success. Returns 404 if the issue or session does not exist, or if the session does not belong to the named issue. ```json Response theme={null} { "data": { "session_id": "0431f6ad-fdd3-4408-a6cc-909842d1db41", "run_id": "56cae586-0670-4f1b-8113-96a2421d56d5", "intent": "fix" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Add Comment Source: https://docs.bland.ai/api-v1/post/triage-issues-id-comments POST https://api.bland.ai/v1/triage/issues/{id}/comments Comment on an issue. Mention @norm to dispatch a Norm investigation. ## Overview Adds a comment to the issue's activity feed. If the body contains `@norm`, the same call also dispatches a Norm investigation, creating a session if none exists. The mention is stripped before the prompt reaches Norm. The HTTP response returns once the comment is saved, so the comment is durable even if the dispatch fails. *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. *** ## Body Parameters Comment body. 1-4000 characters. Include `@norm` anywhere in the body to also dispatch a Norm investigation. Optional array of resource link IDs (from [List Resources](/api-v1/get/triage-issues-id-resources)) to attach to this comment as inline references. The dashboard renders these as chips alongside the comment. *** ## Response Returns `201 Created` with the comment timeline entry. See [List Activity](/api-v1/get/triage-issues-id-activity#response) for the full field list. An `IssueTimelineEntry` with `entry_kind: "issue"` and `type: "comment"`. `null` on success. Returns 404 if the issue does not exist. ```json Response theme={null} { "data": { "entry_kind": "issue", "id": "5a9d0fa9-27b7-414c-9e49-5fc32f240c01", "issue_id": "4f9a7c2d-7f88-4dc4-9d1e-be83c5067f1c", "type": "comment", "actor": { "kind": "user", "id": "1f4cabe4-5f9b-4b30-bc4f-fcd3e94a5b15", "label": "John Bland", "avatar_url": null }, "detail": "@norm please look at the routing logic on the closing node, this looks like the same bug from T-1029.", "from_status": null, "to_status": null, "metadata": null, "resources": [], "referenced_issues": [], "created_at": "2026-05-07T05:26:21.449Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Add Flag Source: https://docs.bland.ai/api-v1/post/triage-issues-id-flags POST https://api.bland.ai/v1/triage/issues/{id}/flags Flag a moment on an attached call. ## Overview Flags pinpoint where on a call something went wrong. The `call_id` must already be attached as a resource on this issue, otherwise the request fails with `409 conflict` and `{ error: "call_not_attached" }`. Flag types accumulate into a reusable per-org catalog (see [List Flag Types](/api-v1/get/triage-flag-types)). *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. *** ## Body Parameters ID of the attached call this flag points at. Must already be attached as a resource on this issue. Flag type. Free-form, but normalized to lower\_snake\_case before storage. Reusing a type increments its `usage_count` in [List Flag Types](/api-v1/get/triage-flag-types). Free-text note explaining why this moment was flagged. 1-4000 characters. ID of the pathway node the flag is attached to, if known. Display name of the pathway node, captured at flag time so the dashboard can render the node name even if the pathway later changes. Zero-based index of the message turn in the call transcript that this flag points at. Verbatim text of the flagged message, captured at flag time. *** ## Response Returns `201 Created` with the new flag. Internal UUID of the flag. The normalized flag type (lower\_snake\_case). Empty string if no note was provided. User ID of the caller that filed the flag. `null` on success. ```json Response theme={null} { "data": { "id": "ad0931e4-b0e1-4bd6-a5b1-09e7c9123dba", "org_id": "f5b40b9e-bc05-4b8a-9af1-d8f6a8a3a201", "issue_id": "9bbe5547-d5b1-4b83-9f80-87c4af7c6b34", "call_id": "3aefc79d-1870-4514-b32b-b9212ae32bc8", "type": "missed_handoff", "note": "Agent transferred without confirming the email.", "node_id": null, "node_name": null, "message_index": 12, "message_text": "OK, transferring you now.", "author_id": "75c5c7da-a5d6-4e26-a51e-1ae8ef2bfa4a", "created_at": "2026-05-07T05:26:11.327Z" }, "errors": null } ``` ```json Call Not Attached theme={null} { "data": null, "errors": [ { "error": "call_not_attached", "message": "Call must be attached to issue first" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Link Related Issue Source: https://docs.bland.ai/api-v1/post/triage-issues-id-relations POST https://api.bland.ai/v1/triage/issues/{id}/relations Link an issue to another issue. ## Overview Creates a typed link from one issue to another. Relations are directed: stored on the source issue (`{id}`) and outgoing to `related_issue_id`. The same relation appears with `direction: "incoming"` when listed from the target issue. *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the source issue. *** ## Body Parameters Internal UUID of the target issue. Relationship type. Must be one of: * `related_to` * `blocks` * `duplicate_of` *** ## Response Returns `201 Created` with the new relation. Internal UUID of the relation. Source issue UUID. Target issue UUID. Short identifier of the target issue (e.g. `T-1004`), denormalized for display. Title of the target issue, denormalized for display. `related_to`, `blocks`, or `duplicate_of`. Always `outgoing` on creation, since the relation lives on the source issue. User ID of the caller that created the relation. `null` on success. Returns 404 if either issue does not exist or is not in your org. ```json Response theme={null} { "data": { "id": "172c839b-130d-4712-a09c-b767a78542ea", "org_id": "f5b40b9e-bc05-4b8a-9af1-d8f6a8a3a201", "issue_id": "9bbe5547-d5b1-4b83-9f80-87c4af7c6b34", "related_issue_id": "849ee9ce-be6b-4f9c-8e55-2736aeeb579f", "related_triage_id": "T-1004", "related_title": "Caller transferred to wrong queue", "relation_type": "duplicate_of", "created_by_id": "75c5c7da-a5d6-4e26-a51e-1ae8ef2bfa4a", "created_at": "2026-05-07T05:28:29.358Z", "direction": "outgoing" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Attach Resource Source: https://docs.bland.ai/api-v1/post/triage-issues-id-resources POST https://api.bland.ai/v1/triage/issues/{id}/resources Attach a call, SMS conversation, or file to an issue. ## Overview Attaches a resource as evidence on an issue. Resources are what Norm reads during an investigation. Attaching the same resource twice is a no-op. For calls specifically, [Attach Call](/api-v1/put/triage-issues-id-calls-call-id) is a shorthand that takes the `call_id` directly. *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. *** ## Body Parameters Type of resource to attach. One of `call`, `sms_conversation`, or `file`. ID of the resource. For calls, this is the `call_id` returned by [Send Call](/api-v1/post/calls). *** ## Response Returns `201 Created` with the new resource link. If the resource was already attached, returns the existing link with `200 OK`. Internal UUID of the resource link. Use this to detach with [Remove Resource](/api-v1/delete/triage-issues-id-resources-resource-link-id). `call`, `sms_conversation`, or `file`. The original resource ID you attached. Display title resolved from the resource itself. For calls this is typically a one-line summary of the conversation. `available` if the underlying resource still exists and is readable, or `unavailable` if it has been deleted or is not accessible. Extra metadata snapshotted from the resource at attach time, for example the call's `created_at`. User ID of the caller that attached the resource. ISO 8601 timestamp. `null` on success. Returns 404 if the issue or the underlying resource cannot be found in your org. ```json Response theme={null} { "data": { "id": "1d8cec02-6b7c-43f9-9f1f-86d4f31b6d8a", "issue_id": "9bbe5547-d5b1-4b83-9f80-87c4af7c6b34", "org_id": "f5b40b9e-bc05-4b8a-9af1-d8f6a8a3a201", "resource_type": "call", "resource_id": "3e3af63d-0cc0-4525-b742-72a5367fd072", "title": "Caller asked to be transferred to billing after the agent failed to verify their account.", "status": "available", "metadata": { "created_at": "2026-04-30T14:11:08.000Z" }, "attached_by_id": "75c5c7da-a5d6-4e26-a51e-1ae8ef2bfa4a", "created_at": "2026-05-07T05:25:56.361Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Pathway Version Source: https://docs.bland.ai/api-v1/post/update-pathway-version POST https://api.bland.ai/v1/pathway/{pathway_id}/version/{version_number} Updates a specific version of a pathway, including its version name, nodes, and edges. ### Headers Your API key for authentication. ### Path Parameters The ID of the pathway for which to create a new version. The version number of the pathway to update. ### Request Body The name of the new pathway version. An array of node objects defining the structure of the pathway. * `id` — Unique identifier of the node * `type` — Type of the node (e.g., "Default", "End Call", "Webhook") * `data` — Object containing node-specific data * `name` — Name of the node * `text` or `prompt` — Text or prompt associated with the node * Other properties specific to the node type An array of edge objects defining the connections between nodes. * `id` — Unique identifier of the edge * `source` — ID of the source node * `target` — ID of the target node * `label` — Label for this edge ### Response The status of the operation (e.g., "success"). A message describing the result of the operation. ```json Response theme={null} { "status": "success", "message": "Version updated successfully" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Folder Source: https://docs.bland.ai/api-v1/post/update_pathway_folder PATCH https://us.api.bland.ai/v1/pathway/folders/{folder_id} Updates the name of a specific folder for the authenticated user. ### Headers Your API key for authentication. ### Path Parameters The ID of the folder to update. ### Body Parameters The new name for the folder. ### Response The unique identifier of the updated folder. The updated name of the folder. The ID of the parent folder, if applicable. ```json Response theme={null} { "folder_id": "updated_folder_123", "name": "Updated Folder Name", "parent_folder_id": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Pathway Source: https://docs.bland.ai/api-v1/post/update_pathways POST https://api.bland.ai/v1/pathway/{pathway_id} Update a conversational pathway's fields - including name, description, nodes and edges. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the conversational pathway you want to update. ### Body The name of the conversational pathway A description of the pathway An array of node objects representing the conversation flow points in your pathway. Each node contains: **Common Node Structure:** ```json theme={null} { "id": "unique_node_identifier", "type": "Node_Type", "data": { "name": "Display Name", // Node-specific configuration goes here } } ``` **Available Node Types:** `Default`, `End Call`, `Transfer Call`, `Webhook`, `Knowledge Base`, `SMS`, `Custom Code`, `Press Button`, `Wait for Response`, `Transfer Pathway`, `Scheduling`, and more. **Node Examples:** ```json Start Node theme={null} { "id": "1", "type": "Default" "data": { "name": "Start", "text": "Hey there, how are you doing today?", "isStart": true, }, } ``` ```json Default Node theme={null} { "id": "randomnode_1710288871721", "type": "Default" "data": { "name": "New Node", "text": "Select a node or edge and press backspace to remove it", "globalPrompt": "This is a phone call. Do not use exclamation marks.\n\nConvert 24HR format timings to 12 HR format - e.g 14:00 should be written as 2 PM.", }, } ``` ```json End Node theme={null} { "id": "randomnode_1710288752186", "type": "End Call" "data": { "name": "End call", "prompt": "Say goodbye to the user", }, } ``` ```json Webhook Node theme={null} { "id": "randomnode_1710288752186", "type": "Webhook", "data": { "url": "https://api.bland.ai/reservation", "body": "{\n \"date\" : \"{{date}}\",\n \"time\" : \"{{time}}\",\n \"guests\": {{number_of_people}}\n}", "name": "Reservation Booking", "text": "Please give me a moment as I check our bookings..", "method": "POST", "extractVars": [ [ "date", "string", "Desired Date of reservation, in MM/DD/YYYY format" ], [ "time", "string", "Desired Time of Reservation in 24HR Format e.g 13:30" ], [ "number_of_people", "integer", "Number of people for the reservation" ] ], "responseData": [ { "data": "$.reserved", "name": "reservation_success", "context": "" }, { "data": "$.available_slots", "name": "available_slots", "context": "Available slots for the date provided" } ], "responsePathways": [ [ "reservation_success", "==", "true", { "id": "randomnode_1710288752186", "name": "Reservation Successful" } ], [ "reservation_success", "==", "false", { "id": "randomnode_1712265110018", "name": "Find new timeslot" } ] ] } } ``` ```json Knowledge Base Node theme={null} { "id": "randomnode_1710288752186", "type": "Knowledge Base", "data": { "name": "Restaurant Questions", "prompt": "Answer any questions that the user may have regarding the restaurant, by referring to the knowledge base you have. \n\nAnswer the question in 1 line, and then ask if they have any more questions." "kb": "Opening Hours : 9am - 5pm\nStore Locations : \n426 Ivy Street San Francisco, \nSan Jose" } } ``` ```json Global Node theme={null} { "id": "randomnode_1710288871721", "type": "Default" "data": { "name": "Answer any questions", "prompt": "You are to answer any questions the user has.", "isGlobal": true, "globalLabel": "user asks a question" }, } ``` ```json Transfer Call Node theme={null} { "id": "randomnode_1710288752186", "type": "Transfer Call", "data": { "name": "Transferring the call", "text": "Transferring the call now. Please hold.." "transferNumber": "+19547951234" } } ``` * `name` — name of the node * `isStart` — whether the node is the start node. There can only be 1 start node in a pathway. Either `true` or `false`. * `isGlobal` — whether the node is a global node. Global nodes are nodes that can be used in multiple pathways. Either `true` or `false`. * `globalLabel` — the label of the global node. Should be present if `isGlobal` is true. * `type` — Type of the node. Can be `Default`, `End Call`, `Transfer Node`, `Knowledge Base`, or `Webhook`. * `text` — If static text is chosen, this is the text that will be said to the user. * `prompt` — If dynamic text is chosen, this is the prompt that will be shown to the user. * `condition` — The condition that needs to be met to proceed from this node. * `transferNumber` * If the node is a transfer node, this is the number to which the call will be transferred. * `kb` * If the node is a knowledge base node, this is the knowledge base that will be used. * `pathwayExamples` * The fine-tuning examples for the agent at this node for the pathways chosen * `conditionExamples` * The fine-tuning examples for the condition at this node for the condition chosen * `dialogueExamples` * The fine-tuning examples for the dialogue at this node for the dialogue chosen. * `modelOptions` * `modelName` — The name of the model to be used for this node. * `interruptionThreshold` — The sensitivity to interruptions at this node * `interruptibility` — How readily the AI stops speaking when the caller talks over it on this node: `0` block (the AI finishes speaking, same as `block_interruptions: true`), `1` difficult, `2` balanced (default), `3` easy. Applies only while this node is active; other nodes use the agent's setting. Useful per node: e.g. difficult on a legal-disclaimer node. * `temperature` — The temperature of the model. * `extractVars` * An array of array of strings. \[\[`varName`, `varType`, `varDescription`]] e.g `[["name", "string", "The name of the user"], ["age", "integer", "The age of the user"]]` Update the pathway's [**global prompt**](/tutorials/pathways#global-prompt-for-all-nodes) by adding an object to the array of nodes. ```json Global Prompt theme={null} { "globalConfig": { "globalPrompt": "This is a phone call. Do not use exclamation marks.\n\nConvert 24HR format timings to 12 HR format - e.g 14:00 should be written as 2 PM." }, "position": { "x": 0, "y": 0 } } ``` An array of edge objects that define the connections and flow between nodes in your pathway. Each edge contains: **Common Edge Structure:** ```json theme={null} { "source": "source_node_id", "target": "target_node_id", "data": { "label": "When this path should be taken", // Optional: conditions, descriptions, etc. } } ``` * `id` — unique id of the edge * `source` — id of the source node * `target` — id of the target node * `label` — Label for this edge. This is what the agent will use to decide which path to take. ## Complete JSON Structure Example For a comprehensive example of how pathways are structured with multiple nodes and edges in a realistic use case, download our example template: [Download pathway example](../../tutorials/tutorials-assets/pathway_json_example.json) This example contains a complete car rental pathway with: * Multiple node types (Default, Transfer Call, Webhook, End Call, etc.) * Complex edge routing and conditions * Variable extraction and model configuration * Real-world conversation flow patterns ### Response Can be `success` or `error`. A unique identifier for the pathway (present only if status is `success`). Data about all the nodes in the pathway. Data about all the edges in the pathway. ```json Response theme={null} { "status": "success", "message": "Pathway updated successfully", "pathway_data": { "pathway_id": "9d404c1b-6a23-4426-953a-a52c392ff8f1", "name": "Updated Demo Pathway", "description": "This is an updated description", "nodes": [ { "id": "1", "data": { "name": "Start", "text": "Hey there, how are you doing today?", "isStart": true, }, "type": "Default" }, { "id": "randomnode_1710288752186", "data": { "name": "End call", "prompt": "Click 'Add New Node' on the right to add a new node", }, "type": "End Call" }, { "id": "randomnode_1710288871721", "data": { "name": "New Node", "prompt": "Click 'Add New Node' on the right to add a new node", }, "type": "Default" } ], "edges": [ { "id": "1", "source": "1", "target": "randomnode_1710288752186", "data": { "name": "End call", "prompt": "Click 'Add New Node' on the right to add a new node", } }, { "id": "2", "source": "1", "target": "randomnode_1710288871721", "data": { "name": "New Node", "prompt": "Click 'Add New Node' on the right to add a new node", } } ] } } ``` *** Docs for agents: [llms.txt](/llms.txt) # Upload Media Source: https://docs.bland.ai/api-v1/post/upload-media POST https://api.bland.ai/v1/knowledgebases/upload-media Upload a media file as a new knowledge base Upload media files along with optional metadata like name and description. ### Headers Your API key for authentication. ### Body The media file to be uploaded. Must be an .mp3 or .mp4 file. Name for the uploaded media file Description for the uploaded media file *** Docs for agents: [llms.txt](/llms.txt) # Upload Text Source: https://docs.bland.ai/api-v1/post/upload-text POST https://api.bland.ai/v1/knowledgebases/upload Upload a text file as a new knowledge base Upload text files along with optional metadata like name and description. ### Headers Your API key for authentication. ### Body The text file to be uploaded. Must be a .pdf, .txt, .doc, or .docx file. Name for the uploaded text file Description for the uploaded text file *** Docs for agents: [llms.txt](/llms.txt) # Create a Knowledge Base Source: https://docs.bland.ai/api-v1/post/vectors POST https://api.bland.ai/v1/knowledgebases Create a new knowledge base. Usage: Pass the `vector_id` into your agent's `tools` to enable the agent to use the vector store. ```json theme={null} "tools": [ "KB-55e64dae-1585-4632-ae97-c909c288c6bc" ] ``` ### Headers Your API key for authentication. ### Body The name of the knowledge base. Make this a clear name that describes the contents of the store. A description of the knowledge base. This can be a longer description of the contents of the store, or what terms to use to search for vectors in the store. This is visible to the AI, so making it descriptive can help the AI understand when to use it or not. The full text document to be stored and vectorized. ### Response The unique identifier for the knowledge base. Will start with "KB-". ```json theme={null} { "vector_id": "KB-55e64dae-1585-4632-ae97-c909c288c6bc" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Check Voice Name Availability Source: https://docs.bland.ai/api-v1/post/voices-check-name-availability POST https://api.bland.ai/v1/voices/check_name_availability Check whether a voice name is available before cloning. ## Overview Returns whether a proposed voice name is available in your org's library. Use this to validate input before calling [Clone Voice](/api-v1/post/clone), which rejects the request outright if the name is taken. Names are scoped per org and case-insensitive. *** ## Headers Your API key for authentication. *** ## Body Parameters Voice name to check. 1-30 characters. *** ## Response `success` on success. `true` if the name is available, `false` if it is already in use. Human-readable confirmation. ```json Available theme={null} { "status": "success", "result": true, "message": "Voice name \"DocTestVoice\" is available" } ``` ```json Taken theme={null} { "status": "success", "result": false, "message": "Voice name \"DocTestVoice\" is already in use" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Rate Voice Source: https://docs.bland.ai/api-v1/post/voices-id-rate POST https://api.bland.ai/v1/voices/{id}/rate Give a public library voice a 1-5 star rating. ## Overview Records your rating (1-5) for a voice in the Bland library. Ratings are aggregated and surfaced as `average_rating` and `total_ratings` on each voice. Each caller can have at most one active rating per voice, sending a new rating overwrites the previous one. Send `DELETE` to the same path to clear your rating. This call is throttled to 20 ratings per minute per org. *** ## Headers Your API key for authentication. *** ## Path Parameters UUID of the voice to rate. *** ## Body Parameters Rating value, 1 to 5. *** ## Response `success` on success. The voice's new total rating count. The voice's new average rating. ```json Response theme={null} { "status": "success", "total_ratings": 8, "average_rating": 4.875 } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Voice Settings Source: https://docs.bland.ai/api-v1/post/voices-id-settings POST https://api.bland.ai/v1/voices/{id}/settings Update the consistency/expressiveness defaults on a voice you own. ## Overview Updates one or more synthesis defaults on a voice you own. Equivalent to [Update Voice Config](/api-v1/patch/voices-id-config), kept under both verbs and paths for backwards compatibility. New integrations should use this `POST /settings` form. At least one of the body fields must be provided. *** ## Headers Your API key for authentication. *** ## Path Parameters UUID of the voice. *** ## Body Parameters Default consistency for V1 and V2 voices. V1: 0-1 float (higher is more consistent). V2: 0-64 integer (lower is more consistent). Reject values outside that range. Default expressiveness for V1 and V2 voices. 0-1 float. Boost flag for V3 voices only. `true` adds language-consistency prompting at the cost of some flexibility for code-switching. Disable if your agent needs to speak languages outside the source sample. *** ## Response Echoes back the resolved settings on success. For V1 and V2 voices: The engine identifier of the voice. For V3 voices: To see the rest of the voice's fields after an update, call [Get Voice](/api-v1/get/voices-id). ```json V2 Response theme={null} { "consistency": 16, "expressiveness": 0.8, "service": "BTTS_V2" } ``` ```json V3 Response theme={null} { "boost_language_consistency": true, "service": "BTTS_V3" } ``` ```json Nothing Provided theme={null} { "data": null, "errors": [ { "error": "INVALID_REQUEST", "message": "At least one of consistency, expressiveness or boost_language_consistency must be provided" } ] } ``` ```json Out of Range theme={null} { "data": null, "errors": [ { "error": "INVALID_CONSISTENCY", "message": "consistency must be a number between 0 and 64" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Add Library Voice Source: https://docs.bland.ai/api-v1/post/voices-library-add-id POST https://api.bland.ai/v1/voices/library/add/{id} Add a shared library voice to your org so it can be used in your calls and TTS. ## Overview Adds a voice from the public Bland voice library to your org's voice list. Once added, the voice can be used like any other voice you own: passed to [Speak](/api-v2/post/tts), configured via [Update Voice Config](/api-v1/patch/voices-id-config), renamed, and so on. The original library voice is unchanged. The endpoint returns a new voice record that lives in your org and points at the same underlying model. This call is throttled to 30 add operations per minute per org. *** ## Headers Your API key for authentication. *** ## Path Parameters UUID of the shared voice to add. *** ## Response `success` on success. Human-readable confirmation. The newly added voice in your org. See [Get Voice](/api-v1/get/voices-id#response) for the field list. The `id` is unique to your org, the `voice_id` field points at the underlying model. ```json Response theme={null} { "status": "success", "message": "Voice is in your library", "voice": { "id": "73d4c04b-1e15-4272-9c7f-8d2955914ba9", "name": "StephenD_v1 (published)", "description": null, "public": false, "ratings": 0, "tags": ["Beige Clone V2", "male"], "user_id": "fea2a74f-9bd7-4b5d-a52e-c3c1a3f58bb0", "voice_id": "ff595c98-da38-4617-ada3-df42561a2379", "service": "BTTS_V2", "finetuned": false, "consistency": null, "expressiveness": null, "voice_meta": null, "is_creator_voice": false } } ``` ```json Rate Limited theme={null} { "data": null, "errors": [ { "error": "Rate Limit Exceeded", "message": "Too many library adds, please try again later." } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Add Voice Sample Source: https://docs.bland.ai/api-v1/post/voices-samples POST https://api.bland.ai/v1/voices/samples Append training samples to an existing voice clone you own. ## Overview Appends one or more audio samples to an existing voice clone, retraining the voice on the expanded sample set. Sample limits depend on the voice's engine. **BTTS V1** voices accept up to 5 samples total. **BTTS V2** and **BTTS V3** voices are single-sample by design and do not accept additional samples; use [Clone Voice](/api-v1/post/clone) to create a new voice instead. Sent as `multipart/form-data`. *** ## Headers Your API key for authentication. *** ## Form Fields UUID of the voice to add samples to. Must be a voice your org owns. WAV files to append. Each file 1-60 seconds, max 10 MB. The combined sample count after this call cannot exceed 5 for a V1 voice. *** ## Response `success` on success. The samples currently attached to the voice after the update. See [List Voice Samples](/api-v1/get/voices-id-samples#response) for field shape. ```json Response theme={null} { "status": "success", "samples": [ { "id": "d15b199a-1b79-4664-9a9a-b149ee3b136a", "voice_id": "73d4c04b-1e15-4272-9c7f-8d2955914ba9", "transcription": null, "duration_seconds": 11.4, "created_at": "2026-06-22T21:34:31.347Z" } ] } ``` ```json No Files theme={null} { "data": null, "errors": [ { "error": "BAD_REQUEST", "message": "No audio files provided" } ] } ``` ```json Wrong Engine theme={null} { "data": null, "errors": [ { "error": "INTERNAL_SERVER_ERROR", "message": "Adding samples is only supported for BTTS voices" } ] } ``` ```json Too Many Samples theme={null} { "data": null, "errors": [ { "error": "Validation Error", "message": "Cannot add 2 sample(s). Voice already has 4 samples. Maximum allowed is 5 samples per voice." } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Widget Source: https://docs.bland.ai/api-v1/post/widget POST https://api.bland.ai/v1/widget Creates a new widget. ### Headers Your API key for authentication. ### Body UUID of the pathway to associate with the widget. Must be defined if `agent_prompt` is null. Prompt to use for the widget agent. Must be defined if `pathway_id` is null. Array of domains where the widget can be embedded. Rate limit for messages (minimum: 0). Widget configuration object (flexible JSON). Supports `timeoutSeconds` to configure conversation timeout (default: 86400 seconds / 24 hours). Optional UUID of agent to associate with widget. Optional URL to receive post-conversation webhook payloads when conversations end. See [Post-Conversation Webhooks](/tutorials/chat-widget#post-conversation-webhooks) for payload details. ### Response HTTP status code (200 for success). The created widget object containing: * `id` (string): Generated widget UUID * `pathway_id` (string): Associated pathway UUID * `agent_id` (string | null): Associated agent UUID or null * `allowed_domains` (string\[]): Array of allowed domains * `messages_per_minute` (number): Rate limit for messages * `config` (object): Widget configuration object * `webhook_url` (string | null): Post-conversation webhook URL or null * `created_at` (string): ISO timestamp * `updated_at` (string): ISO timestamp Always null on successful response. ```json Response theme={null} { "status": 200, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "pathway_id": "a0f0d4ed-f5f5-4f16-b3f9-22166594d7a7", "agent_id": null, "allowed_domains": ["example.com", "subdomain.example.com"], "messages_per_minute": 10, "config": { "theme": "light", "position": "bottom-right", "timeoutSeconds": 3600 }, "webhook_url": "https://example.com/webhook", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Custom Component Source: https://docs.bland.ai/api-v1/post/widget-custom-components POST https://api.bland.ai/v1/widget/custom_components Create a new custom component. ### Headers Your API key for authentication. ### Body Widget identifier UUID to associate with the custom component. Pathway UUID to associate with the custom component. Pathway node ID to display the custom component on. Widget width dimension (e.g., "100%", "500px"). Widget height dimension (e.g., "300px", "100%"). Array of available agent variable names to pass into the custom component iframe URL as query params. URL for the iframe source. ### Response HTTP status code (200 for success). * `id` (string): Custom component UUID * `org_id` (string): Organization UUID * `widget_id` (string): Widget identifier UUID * `pathway_id` (string): Associated pathway UUID * `pathway_node` (string): Pathway node ID to display the custom component on * `width` (string): Widget width dimension * `height` (string): Widget height dimension * `variables` (string\[]): Array of variable names to pass into the custom component iframe URL as query params * `iframe_url` (string): URL for the iframe source * `created_at` (string): ISO timestamp * `updated_at` (string): ISO timestamp Always null on successful response. ```json Response theme={null} { "data": [ { "created_at": "2025-10-02T21:45:27.633Z", "updated_at": "2025-10-02T21:45:27.633Z", "id": "70b56282-8db5-4e26-aad9-098c099fb1db", "org_id": "99a0d526-6910-4f31-92b8-72834d0827fb", "widget_id": "7d1a8c0d-5346-4f96-9f5c-d888e273eaf0", "pathway_id": "05f4b269-e79a-4825-b4cd-7778f782bfad", "pathway_node": "1", "width": "100%", "height": "300px", "variables": [ "firstName" ], "iframe_url": "https://widget-custom-components.vercel.app" } ], "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Send Live Agent Message Source: https://docs.bland.ai/api-v1/post/widget-thread-webhook POST https://api.bland.ai/v1/widget/{id}/threads/{thread_id}/webhook Send a message from a live agent to the user, or end the conversation. Use this endpoint to send messages from your live agent platform back to the user in the widget. This is the counterpart to the webhooks Bland sends to your system during a [live agent escalation](/tutorials/chat-widget#escalate-to-live-agents). ### Headers Your API key for authentication. ### Path Parameters The widget ID. The thread ID from the `INITIAL_CONVERSATION` webhook payload. ### Body The request body accepts two payload types: Send a message to the user. Must be `"MESSAGE"`. The message content to display to the user. Identifier for the live agent sending the message. This can be used to distinguish between different agents in the conversation. Optional ISO 8601 timestamp for the message. Defaults to the current time if not provided. End the live agent session. Must be `"END_CONVERSATION"`. Optional identifier for the agent ending the conversation. ### Response HTTP status code (200 for success). For `MESSAGE` requests, returns the created message object. For `END_CONVERSATION` requests, returns the updated thread object with `ended_at` timestamp. Array of error objects if the request failed, otherwise null. ### Error Codes | Status | Error | Description | | ------ | ------------------- | ----------------------------------- | | 400 | `INVALID_PARAMETER` | Request body validation failed. | | 400 | `THREAD_ENDED` | The thread has already been ended. | | 404 | `NOT_FOUND` | Thread not found with the given ID. | ```bash Send Message theme={null} curl -X POST "https://api.bland.ai/v1/widget/{widget_id}/threads/{thread_id}/webhook" \ -H "Authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "MESSAGE", "content": "Hi! I am a live agent. How can I help you today?", "sender_id": "agent_123" }' ``` ```bash End Conversation theme={null} curl -X POST "https://api.bland.ai/v1/widget/{widget_id}/threads/{thread_id}/webhook" \ -H "Authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "END_CONVERSATION", "sender_id": "agent_123" }' ``` ```json Message Response theme={null} { "data": { "created_at": "2025-12-10T19:27:02.941Z", "updated_at": "2025-12-10T19:27:02.941Z", "id": "30a3e35d-9ffb-4810-aef7-2600346107e6", "org_id": "99a0d526-6910-4f31-92b8-72834d0827fb", "widget_id": "b5f3fb6b-2285-4c73-95be-6609eca09986", "thread_id": "f5ff280b-b0d8-4261-a1ed-b74003e733a2", "pathway_session_id": null, "sender_type": "LIVE_AGENT", "sender_id": "49e6e820-f5b7-4fb1-8aa8-7fb162fbcf91", "content": "You have a great day too!" }, "errors": null } ``` ```json End Conversation Response theme={null} { "data": { "created_at": "2025-12-10T19:25:00.809Z", "updated_at": "2025-12-10T20:26:41.180Z", "ended_at": "2025-12-10T20:26:41.179Z", "live_agent_handoff_at": "2025-12-10T19:25:04.745Z", "id": "f5ff280b-b0d8-4261-a1ed-b74003e733a2", "org_id": "99a0d526-6910-4f31-92b8-72834d0827fb", "widget_id": "b5f3fb6b-2285-4c73-95be-6609eca09986", "visitor_id": "ec14ee83-fa2b-493a-b009-0e29414a1e97", "live_agent_endpoint_url": "https://webhook.site/32d53101-7d67-4879-b350-6aa2d1e12ada", "language": "en" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Test Scenario Source: https://docs.bland.ai/api-v1/put/agent-testing-scenarios-id PUT https://api.bland.ai/v1/agent-testing/scenarios/{id} Update an existing test scenario. If assertions are provided, they replace all existing assertions. ### Headers Your API key for authentication. ### Path Parameters The scenario ID. ### Body Parameters Name of the scenario. Must be unique within the pathway/persona. Description of what the scenario tests. One of: `CUSTOM`, `VOICEMAIL`, `VOICEMAIL_SCREENER`, `ANGRY_CALLER`, `BELLIGERENT_CALLER`, `CONFUSED_CALLER`, `CALL_SCREENER`, `HAPPY_PATH`, `EDGE_CASE`. One of: `AGENT`, `REPLAY`, `HISTORICAL`. Prompt instructing the simulated caller how to behave. Display name for the tester persona. Max conversation turns before the test ends. Maximum value is 50. Custom request data to pass to the pathway (e.g., variables). ID of the pathway node where the simulated conversation should begin. Use this to test a specific branch of a pathway without rewiring the flow. Set to `null` to fall back to the pathway's default start node. If the ID does not match a node in the current pathway version, the run fails with an `Invalid start_node_id` error. Enable Bland Tone naturalness scoring. If true, this scenario must pass before the pathway can be promoted to production. Whether the scenario is enabled. Pre-seeded messages for `REPLAY` scenarios. Additional instructions for test execution. Arbitrary metadata to attach to the scenario. Array of assertion definitions. If provided, replaces all existing assertions. The assertion type. One of: `LLM_JUDGE`, `BLAND_TONE`, `VARIABLE_EXTRACTED`, `NODE_REACHED`, `NODES_VISITED`, `WEBHOOK_TRIGGERED`, `REGEX_MATCH`, `STRING_CHECK`, `CUSTOM_LLM`, `TRAVERSAL_MATCH`. Type-specific configuration for the assertion. Display name for the assertion. Whether this assertion must pass for the scenario to pass. Weight of this assertion in the overall score. Order in which the assertion is evaluated. ### Response Unique identifier for the scenario. Organization ID that owns this scenario. The pathway ID being tested (null if testing a persona). The persona ID being tested (null if testing a pathway). Name of the scenario. Description of the scenario. Scenario category. Type of scenario. Prompt for the simulated caller. Display name for the tester persona. Maximum conversation turns. Custom request data. Starting node ID. Whether Bland Tone scoring is enabled. Whether this scenario is required for promotion. Whether the scenario is enabled. Pre-seeded messages for replay scenarios. Additional instructions for test execution. Arbitrary metadata. Array of assertion objects. Unique identifier for the assertion. The assertion type. Display name for the assertion. Type-specific configuration. Whether this assertion must pass. Weight of this assertion in the overall score. Evaluation order. ISO 8601 timestamp of when the scenario was created. ISO 8601 timestamp of when the scenario was last updated. ```json Response theme={null} { "id": "a1b2c3d4-5678-9abc-def0-1234567890ab", "org_id": "b2c3d4e5-6789-abcd-ef01-234567890abc", "pathway_id": "c3d4e5f6-789a-bcde-f012-34567890abcd", "persona_id": null, "name": "Angry Caller Test - Updated", "description": "Tests the agent's ability to de-escalate an angry caller with updated assertions", "category": "ANGRY_CALLER", "scenario_type": "AGENT", "tester_persona_prompt": "You are a frustrated customer who has been waiting on hold for 30 minutes. You are upset about a billing error on your account.", "tester_persona_name": "Frustrated Customer", "max_turns": 20, "request_data": null, "start_node_id": null, "bland_tone_enabled": true, "is_required_for_promotion": true, "enabled": true, "input_messages": null, "advanced_instructions": null, "metadata": null, "assertions": [ { "id": "d4e5f6a7-89ab-cdef-0123-4567890abcde", "type": "LLM_JUDGE", "name": "De-escalation", "config": { "prompt": "Did the agent successfully de-escalate the situation and address the customer's concerns?", "output_type": "score", "threshold": 0.8 }, "is_required": true, "weight": 1.5, "order": 0 }, { "id": "e5f6a7b8-9abc-def0-1234-567890abcdef", "type": "NODE_REACHED", "name": "Reached Resolution", "config": { "node_id": "resolution-node" }, "is_required": true, "weight": 1.0, "order": 1 } ], "created_at": "2026-04-10T12:00:00.000Z", "updated_at": "2026-04-14T10:30:00.000Z" } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Knowledge Base Source: https://docs.bland.ai/api-v1/put/knowledge-id PUT https://api.bland.ai/v1/knowledge/{knowledge_base_id} Updates a knowledge base's name and/or description. Updates the metadata (name and description) of an existing knowledge base. This endpoint does not modify the content of the knowledge base, only its descriptive information. ### Headers Your API key for authentication. Must be `application/json`. ### Path Parameters The unique identifier of the knowledge base to update. ### Body Parameters New name for the knowledge base. If not provided, the current name is retained. New description for the knowledge base. Pass `null` to remove the description entirely. ### Response The updated knowledge base object. Unique identifier for the knowledge base. Updated name of the knowledge base. Updated description of the knowledge base. Current status: `"PROCESSING"`, `"COMPLETED"`, `"FAILED"`, or `"DELETED"`. Type of knowledge base: `"FILE"`, `"WEB_SCRAPE"`, or `"TEXT"`. Source URLs for web scrape type (comma-separated). Base URL for web scrape type. ISO timestamp of creation. ISO timestamp of last update. Error message if status is `"FAILED"`. File information for file-type knowledge bases. Original filename. File size in bytes. MIME type of the file. Will be `null` on successful update. ```bash Update Name Only theme={null} curl -X PUT https://api.bland.ai/v1/knowledge/kb_01H8X9QK5R2N7P3M6Z8W4Y1V5T \ -H "authorization: YOUR_API_KEY" \ -H "content-type: application/json" \ -d '{ "name": "Updated Company FAQs" }' ``` ```json Update Both Name and Description theme={null} { "name": "Updated Company FAQs", "description": "Updated frequently asked questions and company policies for 2025" } ``` ```json Remove Description theme={null} { "name": "Company FAQs", "description": null } ``` ```json Success Response theme={null} { "data": { "id": "kb_01H8X9QK5R2N7P3M6Z8W4Y1V5T", "name": "Updated Company FAQs", "description": "Updated frequently asked questions and company policies for 2025", "status": "COMPLETED", "type": "FILE", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T15:45:00Z", "file": { "file_name": "company_faqs.pdf", "file_size": 2048576, "file_type": "application/pdf" } }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Attach Call Source: https://docs.bland.ai/api-v1/put/triage-issues-id-calls-call-id PUT https://api.bland.ai/v1/triage/issues/{id}/calls/{call_id} Attach a call to an issue. ## Overview Convenience over [Attach Resource](/api-v1/post/triage-issues-id-resources) for when you already have the `call_id`. Idempotent. Returns the full updated issue with `resource_count` incremented. *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. The `call_id` returned by [Send Call](/api-v1/post/calls). *** ## Response The updated issue. See [Create Issue](/api-v1/post/triage-issues#response) for the full field list. `null` on success. Returns 404 if the issue or the call cannot be found in your org. ```json Response theme={null} { "data": { "id": "cb27e5fb-b1f0-4b6f-9f10-13ac35617a87", "triage_id": "T-1042", "org_id": "1c5d7f1f-9f59-4d7f-a0a3-dd3a8b6e7f0e", "number": 1042, "title": "Agent skipped the verification step", "description": "", "status": "todo", "severity": "high", "source": "manual", "category": "Routing", "owner_id": null, "assignee_id": null, "author_id": "8e3d68e0-c2c5-49ea-b4a3-e7c9a1437f76", "external_link": null, "created_at": "2026-05-07T05:32:42.221Z", "updated_at": "2026-05-07T05:32:42.671Z", "last_activity_at": "2026-05-07T05:32:42.671Z", "resource_count": 1, "flag_count": 0, "relation_count": 0, "latest_agent_session": null, "is_processing": false, "has_unread_activity": true }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Mark Issue Viewed Source: https://docs.bland.ai/api-v1/put/triage-issues-id-view PUT https://api.bland.ai/v1/triage/issues/{id}/view Mark an issue as viewed by the calling user. ## Overview Records the calling user's view at the current time. Clears `has_unread_activity` on subsequent fetches for this user. View timestamps are per-user, so each org member has their own unread state. *** ## Headers Your API key for authentication. *** ## Path Parameters Internal UUID of the issue. *** ## Response The issue that was marked viewed. ISO 8601 timestamp the view was recorded at. `null` on success. Returns 404 if the issue does not exist. ```json Response theme={null} { "data": { "issue_id": "4f9a7c2d-7f88-4dc4-9d1e-be83c5067f1c", "last_viewed_at": "2026-05-07T05:26:21.694Z" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Batches Source: https://docs.bland.ai/api-v2/get/batches GET https://api.bland.ai/v2/batches/list Retrieve a list of all batches created by your organization. ### Headers Your API key for authentication. ### Query Parameters Optional. The number of results to return. Optional. The number of results to skip (used for pagination). ### Response A list of batches created by your organization. The unique identifier of the batch. The ID of the org that created the batch. A JSON string representing the global call properties used in the batch. The timestamp when the batch was created. A preview of the call objects included in the batch. A human-readable description of the batch. Always `null` on success. ```json Response theme={null} { "data": [ { "id": "652ad643-9gca-477c-97c3-9d8e6t74d7af", "user_id": "64602f94-d670-43d2-8474-bcdcb9522c4f", "base_prompt": "{\"record\":true,\"task\":\"Say hello to the user\"}", "created_at": "2025-05-08T19:28:12.627Z", "call_objects": [ { "task": "Say hello to the user", "phone_number": "+1234567890" } ], "description": "My first batch" } ], "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Batch Source: https://docs.bland.ai/api-v2/get/batches-id GET https://api.bland.ai/v2/batches/{batch_id} Retrieve metadata for a specific batch. This does not include logs, use the logs endpoint for that. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the batch you want to fetch. ### Response Metadata and configuration details of the batch. The unique identifier of the batch. The ID of the org that created the batch. A JSON string representing shared call properties such as `task` or `record`. The timestamp of when the batch was created. A preview of call objects in the batch. A human-readable label or description for the batch. Always `null` on success. ```json Response theme={null} { "data": { "id": "a9a033b7-44d8-40c6-aaec-42cd43106273", "user_id": "657ad643-92ca-477c-97cc-9d8e6e74d7af", "base_prompt": "{\"record\":true,\"task\":\"Say hello to the user\"}", "created_at": "2025-05-08T19:28:12.627Z", "call_objects": [ { "task": "Say hello to the user", "phone_number": "+1234567890" } ], "description": "Untitled Batch" }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Get Batch Logs Source: https://docs.bland.ai/api-v2/get/batches-id-logs GET https://api.bland.ai/v2/batches/{batch_id}/logs Retrieve logs for a specific batch. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the batch whose logs you want to fetch. ### Query Parameters Optional. The number of log entries to return. Optional. The number of log entries to skip (used for pagination). Optional. Sort order of logs.
Valid values: `"asc"` or `"desc"` (default is `"desc"`).
### Response A list of log entries related to the batch's lifecycle and execution. The unique identifier for the log entry. The ID of the batch associated with the log. The organization ID tied to the batch. The type of log event.\
Examples: `"lifecycle"`, `"complete"`
The time the log was generated. Additional information related to the event. Contents vary depending on the `event_type`. Always `null` on success. ```json Response theme={null} { "data": [ { "id": "6398342c-d7de-4a11-ba86-3d86e5746699", "batch_id": "f6ef9224-0ec3-43e4-98a1-bb2a8765d110", "org_id": "f52eb4b2-c8b6-44a6-a36c-2749aa930c86", "event_type": "complete", "timestamp": "2025-05-08T19:28:42.748Z", "payload": { "calls_total": 1, "calls_failed": 0, "calls_successful": 1 } }, { "id": "a24616b4-be8f-42e4-be29-4c5ec005756c", "batch_id": "f6ef9224-0ec3-43e4-98a1-bb2a8765d110", "org_id": "f52eb4b2-c8b6-44a6-a36c-2749aa930c86", "event_type": "lifecycle", "timestamp": "2025-05-08T19:28:15.560Z", "payload": { "message": "Requested: 1. Validated: 1. Dispatched: 1. CPS: 1.12.", "state_change": "in_progress" } } ], "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # List Tools Source: https://docs.bland.ai/api-v2/get/tools GET https://api.bland.ai/v2/tools Retrieve a paginated list of your tools. Returns tools that are not tied to a specific resource connection. ### Headers Your API key for authentication. ### Query Parameters Page number for pagination. Minimum `1`. Defaults to `1`. Number of results per page. Minimum `1`, maximum `1000`. Defaults to `50`. Filter results by searching the tool's `name` and `description` fields. Field to sort results by. Currently only `"created_at"` is supported. Sort direction. Allowed values: `"asc"`, `"desc"`. Defaults to `"desc"`. This endpoint only returns tools that are **not** tied to a specific resource connection (`resource_id: null`). Tools created as part of a connected integration resource are excluded. ### Response Array of integration tool objects. Unique identifier for the tool (prefixed with `TL-`). The tool's name. The tool's description. The integration key (e.g. `"slack"`). The action within the integration. JSON Schema for the tool's input parameters. Text the AI says while using this tool. Timeout in milliseconds. Whether response caching is enabled. Maximum retry attempts. Seconds between retries. Human-readable label, if set. Whether the tool is active and available for use. Whether the tool is in draft state. Whether the tool is publicly visible. ISO 8601 timestamp of when the tool was created. Pagination metadata. The current page number. Number of results per page. Whether there are additional pages of results. The next page number, or `null` if there are no more pages. `null` on success, or a list of error objects if the request failed. ```json Response (Success) theme={null} { "data": { "tools": [ { "id": "TL-abc123def456", "name": "SendSlackMessage", "description": "Sends a message to a Slack channel", "integration": "slack", "action": "send_message", "input_schema": { "type": "object", "properties": { "channel": { "type": "string" }, "message": { "type": "string" } }, "required": ["channel", "message"] }, "speech": "Sending that message to Slack now.", "timeout": 10000, "cache": false, "max_retries": 0, "cooldown": null, "label": null, "is_active": true, "is_draft": false, "public": false, "created_at": "2025-09-23T15:13:36.348Z" } ], "pagination": { "page": 1, "limit": 50, "hasMore": false, "nextPage": null } }, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Tool Execution Logs Source: https://docs.bland.ai/api-v2/get/tools-logs GET https://api.bland.ai/v2/tools/logs Retrieve per-execution logs for your tools with optional filtering and pagination. ### Headers Your API key for authentication. ### Query Parameters **Pagination** Page number. Defaults to `1`. Results per page. Maximum `100`. Defaults to `50`. **Filters** Filter logs by a specific tool ID. Filter logs by a specific resource ID. Filter logs by integration key (e.g. `"slack"`). Filter logs by action name. Filter by execution status. Allowed values: `"success"`, `"error"`. Filter logs by the call ID that triggered the tool execution. Filter logs by error type (only applies to failed executions). **Date Range** ISO 8601 date string. Only return logs created after this timestamp. ISO 8601 date string. Only return logs created before this timestamp. **Size Filters** Only return logs where execution time is greater than this value (in ms). Only return logs where execution time is less than this value (in ms). Only return logs where input payload size is greater than this value (in KB). Only return logs where input payload size is less than this value (in KB). Only return logs where output payload size is greater than this value (in KB). Only return logs where output payload size is less than this value (in KB). ### Response Array of tool execution log entries. Unique log entry identifier. ID of the tool that was executed. ID of the resource used, if any. Integration key that was invoked. Action that was invoked. Execution result: `"success"` or `"error"`. ID of the call that triggered this execution. Time taken to execute the tool in milliseconds. Size of the input payload in KB. Size of the output payload in KB. Error category if the execution failed. ISO 8601 timestamp of when the execution occurred. Total number of logs matching the filters. Total number of pages. The current page number. Number of results per page. ```json Response (Success) theme={null} { "logs": [ { "id": "log_abc123", "tool_id": "TL-abc123def456", "resource_id": null, "integration": "slack", "action": "send_message", "status": "success", "call_id": "call_xyz789", "execution_time_ms": 342, "input_size_kb": 0.5, "output_size_kb": 1.2, "error_type": null, "created_at": "2025-09-23T15:13:36.348Z" } ], "totalLogs": 1, "totalPages": 1, "currentPage": 1, "pageSize": 50 } ``` *** Docs for agents: [llms.txt](/llms.txt) # Tool Execution Stats Source: https://docs.bland.ai/api-v2/get/tools-logs-stats GET https://api.bland.ai/v2/tools/logs/stats Retrieve aggregated execution statistics for your tools, grouped and filtered by integration, status, date, and more. Maximum date range is 90 days. ### Headers Your API key for authentication. ### Query Parameters **Grouping** Comma-separated list of fields to group results by. Supported values: `integration`, `action`, `status`, `tool_id`, `resource_id`, `error_type`, `date`. Example: `group_by=integration,status` **Metrics** Comma-separated list of metrics to compute. Use `"count"` for total execution count, or `"field:avg"` for averages. Supported aggregate fields: `execution_time_ms`, `input_size_kb`, `output_size_kb`. Defaults to `"count"`. Example: `metrics=count,execution_time_ms:avg` **Date Range** Preset time period. Allowed values: `"today"`, `"week"`, `"month"`. Overridden by `start_date`/`end_date` if both are provided. Start of the date range (ISO 8601). Maximum range is 90 days from `end_date`. End of the date range (ISO 8601). Maximum range is 90 days from `start_date`. **Filters** Filter stats to a specific tool ID. Filter stats to a specific resource ID. Filter by integration key. Filter by action name. Filter by execution status. Allowed values: `"success"`, `"error"`. Filter by error type. Filter to a specific call ID. Maximum number of groups to return. Minimum `1`, maximum `1000`. Defaults to `50`. ### Response Array of aggregated result objects. Each entry contains the grouped dimensions and the requested metric values. Integration key (present when grouped by `integration`). Action name (present when grouped by `action`). Execution status (present when grouped by `status`). Tool ID (present when grouped by `tool_id`). Date string (present when grouped by `date`). Total execution count (present when `count` is in `metrics`). Average execution time in ms (present when `execution_time_ms:avg` is in `metrics`). Average input size in KB (present when `input_size_kb:avg` is in `metrics`). Average output size in KB (present when `output_size_kb:avg` is in `metrics`). Metadata about the query that was executed. ```json Request theme={null} GET /v2/tools/logs/stats?group_by=integration,status&metrics=count,execution_time_ms:avg&period=week ``` ```json Response (Success) theme={null} { "results": [ { "integration": "slack", "status": "success", "count": 142, "execution_time_ms_avg": 318.5 }, { "integration": "slack", "status": "error", "count": 3, "execution_time_ms_avg": 10000.0 } ], "meta": { "group_by": ["integration", "status"], "metrics": ["count", "execution_time_ms:avg"], "period": "week" } } ``` *** Docs for agents: [llms.txt](/llms.txt) # List TTS Models Source: https://docs.bland.ai/api-v2/get/tts-models GET https://api.bland.ai/v2/tts/models List what each TTS model supports. ## Overview Lists the encodings, sample rates, containers, and controls each model supports. Use it to build a picker, validate a request before sending it, or check what a new model added. You do not choose a model — the voice you pass decides it. It comes back in the `x-model` header on [Synthesize Speech](/api-v2/post/tts). For one model, use `GET /v2/tts/models/:id`. Prefer **`btts-3` or newer**. `expressiveness` and `stability` are calibrated for it, and 48 kHz is the rate it renders natively. `btts-2` is listed because it still synthesizes, but the controls are not tuned for it. *** ## Headers Your API key. *** ## Response Array of model manifests. Model identifier, for example `btts-3`. Same value as the `x-model` header. Supported audio codecs. Pass one as `audio.encoding`. Supported PCM sample rates in Hz. `mulaw` is fixed at 8000 regardless of this list. Supported byte framings (`raw`, `wav`). Supported voice controls and their allowed ranges. Each entry is an object with `min` and `max`. ```json Response theme={null} { "models": [ { "id": "btts-3", "encodings": ["pcm_s16le", "mulaw"], "sample_rates": [8000, 16000, 24000, 44100, 48000], "containers": ["raw", "wav"], "controls": { "expressiveness": { "min": 0, "max": 1 }, "stability": { "min": 0, "max": 1 } } }, { "id": "btts-2", "encodings": ["pcm_s16le", "mulaw"], "sample_rates": [8000, 16000, 24000, 44100, 48000], "containers": ["raw", "wav"], "controls": { "expressiveness": { "min": 0, "max": 1 }, "stability": { "min": 0, "max": 1 } } } ] } ``` ```json Not found (GET /v2/tts/models/:id) theme={null} { "error": { "code": "not_found", "message": "Unknown model: btts-9" } } ``` ### Error codes | Code | HTTP | Meaning | | ----------- | ---- | ------------------------------------------------------------- | | `not_found` | 404 | `GET /v2/tts/models/:id` was called with an unknown model ID. | *** Docs for agents: [llms.txt](/llms.txt) # Speech (OpenAI-compatible) Source: https://docs.bland.ai/api-v2/post/audio-speech POST https://api.bland.ai/v2/audio/speech Use Bland voices through the OpenAI text-to-speech request and error shapes. ## Overview This endpoint implements OpenAI's `/audio/speech` contract. If you already use an OpenAI SDK or a compatible router such as LiteLLM, change the base URL, API key, and model to route speech through Bland. ```python theme={null} import os from pathlib import Path from openai import OpenAI client = OpenAI( api_key=os.environ["BLAND_API_KEY"], base_url="https://api.bland.ai/v2", ) with client.audio.speech.with_streaming_response.create( model="btts-3", voice="coral", input="Hello from Bland.", ) as response: response.stream_to_file(Path("hello.mp3")) ``` For LLM tokens, interruptions, and the lowest conversational latency, use [Realtime Speech (WebSocket)](/api-v2/post/tts-ws). For a complete input string with Bland-specific audio controls, use [Synthesize Speech (HTTP)](/api-v2/post/tts). ## Headers `Bearer `. OpenAI SDKs send this from their `api_key` or `apiKey` configuration. ## Body parameters `btts-3` or `btts-2`. OpenAI model IDs such as `tts-1` and `gpt-4o-mini-tts` are not aliased. Unknown IDs return `400` with code `model_not_found`. The model must match the selected Bland voice. A mismatch returns `400` with code `model_voice_mismatch`. Non-empty text to speak. Maximum 4,096 characters. A recognized OpenAI voice name, mapped to a Bland core voice, or a Bland voice UUID for the full catalog. | OpenAI name | Bland voice | | ------------------------------------------------- | ----------- | | `alloy`, `ash`, `coral`, `fable` | River | | `amber`, `august`, `lily`, `nova`, `shimmer` | Karen | | `ballad`, `blue`, `echo`, `onyx`, `sage`, `verse` | Matthew | Names are case-insensitive. An unrecognized name returns `400`. `mp3`, `opus`, `aac`, `flac`, `wav`, or `pcm`. `pcm` is raw 24 kHz signed 16-bit little-endian mono audio. The other formats use a 48 kHz render and include their normal file or stream framing. Only `1.0` is accepted. Other values return `400` because Bland does not currently expose speed control on this endpoint. Only `audio` is supported. `sse` returns `400`. Accepted and ignored. This OpenAI field has no Bland equivalent. ## Response The response body contains audio bytes. `Content-Type` matches the requested format: | `response_format` | `Content-Type` | | ----------------- | -------------- | | `mp3` | `audio/mpeg` | | `opus` | `audio/ogg` | | `aac` | `audio/aac` | | `flac` | `audio/flac` | | `wav` | `audio/wav` | | `pcm` | `audio/pcm` | MP3, Opus, AAC, FLAC, and raw PCM can begin streaming before synthesis completes. WAV is buffered until its final RIFF header length is known. Unique request ID. Include it in support requests. ## Errors Errors use OpenAI's envelope so SDK error handling remains readable: ```json theme={null} { "error": { "message": "The model 'tts-1' does not exist. Supported models: btts-3, btts-2.", "type": "invalid_request_error", "param": "model", "code": "model_not_found" } } ``` | Condition | HTTP | Code | | --------------------------------------- | ---- | ---------------------- | | Missing or malformed field | 400 | `null` | | Unknown model | 400 | `model_not_found` | | Model does not match the selected voice | 400 | `model_voice_mismatch` | | Unsupported voice type | 400 | `null` | | Out of credits | 402 | `insufficient_quota` | | Professional voice is still a draft | 403 | `voice_not_live` | | Voice UUID is not found or accessible | 404 | `voice_not_found` | | Synthesis fails before audio begins | 500 | `synthesis_failed` | ## Examples ```bash cURL theme={null} curl -X POST "https://api.bland.ai/v2/audio/speech" \ -H "Authorization: Bearer $BLAND_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "btts-3", "input": "Hello from Bland.", "voice": "coral", "response_format": "mp3" }' \ --output hello.mp3 ``` ```python OpenAI SDK theme={null} import os from pathlib import Path from openai import OpenAI client = OpenAI( api_key=os.environ["BLAND_API_KEY"], base_url="https://api.bland.ai/v2", ) with client.audio.speech.with_streaming_response.create( model="btts-3", voice="coral", input="Hello from Bland.", ) as response: response.stream_to_file(Path("hello.mp3")) ``` ```python LiteLLM theme={null} import os import litellm litellm.speech( model="openai/btts-3", voice="coral", input="Hello from Bland.", api_base="https://api.bland.ai/v2", api_key=os.environ["BLAND_API_KEY"], ) ``` ```js Node.js theme={null} import fs from "node:fs/promises"; import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.BLAND_API_KEY, baseURL: "https://api.bland.ai/v2", }); const response = await client.audio.speech.create({ model: "btts-3", voice: "coral", input: "Hello from Bland.", }); await fs.writeFile("hello.mp3", Buffer.from(await response.arrayBuffer())); ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Batch Source: https://docs.bland.ai/api-v2/post/batches POST https://api.bland.ai/v2/batches/create Create a new batch of calls using direct input. ### Headers Your API key for authentication. Optional encrypted key used for securing batch payloads. Learn more about BYOT [here](/tutorials/custom-twilio). ### Body A list of individual call objects to include in the batch. Each object follows the same schema as `/v1/calls`. ```json Example theme={null} "call_objects": [ { "phone_number": "+1234567890", "task": "Say hello to the nice person!", "start_time": "2026-01-01 12:00:00-05:00", // Provide a UUID v7 Compliant ID for this Call ahead of time. // Requires entitlements to use. Contact your Account Executive for more information. "b_cid": "" // Remainder of /v1/call properties ... }, { "phone_number": "+1234567891", "task": "Say hello to the bad person!", "record": false, "start_time": "2026-01-01 1:00:00-05:00" //timezone is optional, defaults to UTC // /v1/call properties } ] ``` Global call properties to apply to all `call_objects`, unless overridden per entry. \ \ **Required keys:** * Must include at least one of: `"task"` or `"pathway_id"`. \ \ **Forbidden keys:** * `"phone_number"` is **not allowed** in the global object. Example: ```json Example theme={null} "global": { "task": "Say hello to the nice person!", "record": true, "start_time": "2026-01-01 12:00:00-05:00" //timezone is optional, defaults to UTC // /v1/call properties } ``` A short label for the batch shown in the dashboard. Maximum 60 characters. Defaults to `"Untitled Batch"` if not provided. Optional URL to receive batch status updates. We send a single POST per lifecycle phase and one final POST when the batch completes or fails. Payload is JSON with `batch_id`, `status`, and `timestamp`; final events include `calls_total` / `calls_successful` / `calls_failed` or `code` and `reason` on failure. Your endpoint should respond with 200 within a few seconds; we wait up to 10 seconds per call. See [Status webhook](#status-webhook) below for payload details. ### Response The response includes the `batch_id` of the newly created batch. The unique identifier for the batch. Always `null` on success. ```json Response theme={null} { "data": { "batch_id": "8b8e8c57-9e6e-4e4d-84d2-9826b2268c22" }, "errors": null } ``` ### Status webhook If you provide **`status_webhook`**, we POST to that URL at each lifecycle phase and once when the batch finishes. All requests use `Content-Type: application/json`. **Status values:** `validating` | `dispatching` | `in_progress` | `in_progress_chunked` | `waiting_for_scheduled_calls` | `completed` | `failed` | `completed_partial` **Common fields on every request:** `batch_id` (string), `status` (string), `timestamp` (ISO 8601). Progress events may include `message` (string). Final events include call counts or error details as below. **Progress examples:** ```json Validating theme={null} { "batch_id": "42eb41ed-1842-40c3-b2e6-47d690c179ad", "status": "validating", "timestamp": "2026-02-20T15:00:05.123Z" } ``` ```json In progress (with message) theme={null} { "batch_id": "42eb41ed-1842-40c3-b2e6-47d690c179ad", "status": "in_progress", "message": "Requested: 100. Validated: 100. Dispatched: 100. CPS: 12.50.", "timestamp": "2026-02-20T15:00:18.789Z" } ``` **Final events:** ```json Completed theme={null} { "batch_id": "42eb41ed-1842-40c3-b2e6-47d690c179ad", "status": "completed", "calls_total": 100, "calls_successful": 98, "calls_failed": 2, "timestamp": "2026-02-20T15:30:00.000Z" } ``` ```json Failed theme={null} { "batch_id": "42eb41ed-1842-40c3-b2e6-47d690c179ad", "status": "failed", "code": "source_invalid", "reason": "Entry #7 did not have a phone number.", "timestamp": "2026-02-20T15:00:10.000Z" } ``` ```json Completed partial (e.g. timeout) theme={null} { "batch_id": "42eb41ed-1842-40c3-b2e6-47d690c179ad", "status": "completed_partial", "code": "batch_early_exit", "reason": "Condition not met within 86400 seconds", "calls_total": 50, "calls_successful": 45, "calls_failed": 5, "timestamp": "2026-02-21T15:00:00.000Z" } ``` We send one attempt per event with a 10-second timeout. If the request fails or times out, we log and continue; the workflow is not retried or failed. Respond with 2xx quickly and perform any heavy work asynchronously. *** Docs for agents: [llms.txt](/llms.txt) # Stop Batch Source: https://docs.bland.ai/api-v2/post/batches-id-stop POST https://api.bland.ai/v2/batches/{batch_id}/stop Stop a batch that is currently running or scheduled. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the batch to stop. ### Response Always `null` on success. `null` if the batch was successfully stopped. ```json Response theme={null} { "data": null, "errors": null } ``` *** Docs for agents: [llms.txt](/llms.txt) # Create Tool Source: https://docs.bland.ai/api-v2/post/tools POST https://api.bland.ai/v2/tools Create a new tool. Tools connect to built-in integrations (e.g. Slack, OpenAPI) and are invoked automatically by your agent during calls and SMS conversations. ### Headers Your API key for authentication. ### Body Parameters The name the AI will see when deciding to use this tool. Must be at least 1 character. Avoid names that conflict with reserved internal tools: `input`, `speak`, `transfer`, `switch`, `wait`, `finish`, `press`, `button`, `say`, `pause`, `record`, `play`, `dial`, `hang`. Description of what the tool does. Shown to the AI to help it decide when to use this tool. The integration key to use. Must be one of: `bland-sms`, `custom-code`, `slack`, `salesforce`, `rest_api`, `hubspot`, `calendly`, `cal-com-v2`, `notion`. The action key to invoke within the integration. To discover available action keys, call `GET /v1/integrations/{integration}/actions`. Returns `400 ACTION_NOT_FOUND` with the list of valid actions if the key is invalid. Must be a valid OpenAI function calling parameter schema. Defines the parameters the AI will fill in when invoking this tool. ```json theme={null} { "type": "object", "properties": { "channel": { "type": "string" }, "message": { "type": "string" } }, "required": ["channel", "message"] } ``` Request body template sent to the integration. Supports prompt variables from `input_schema` (e.g. `"{{input.channel}}"`). Text the AI says aloud while executing this tool (e.g. `"One moment while I send that message."`). Maximum time in milliseconds to wait for the integration to respond. Minimum `1000`, maximum `60000`. Whether to cache the tool's response. Accepts `true`, `false`, `"true"`, or `"false"`. Defines which fields to extract from the integration response and make available as prompt variables. Variable name to assign the extracted value. JSON path to the value in the response (e.g. `"$.message_id"`). Optional description of what this data represents. Number of times to retry the tool on failure. Minimum `0`, maximum `4`. Seconds to wait between retries. Minimum `1`, maximum `30`. UUID of a connected resource (e.g. a Slack workspace or Salesforce org) to scope this tool to. The resource must be active and belong to your account. Returns `404` if the ID is invalid or inactive. To list available resource IDs for an integration, call `GET /v1/integrations/{integration}/resources`. Whether this tool is publicly visible. Defaults to `false`. Optional human-readable label for this tool. ### Response `"success"` on success, `"error"` on failure. The ID of the newly created tool. `null` on success, or a list of error objects if the request failed. ```json Request theme={null} { "name": "SendSlackMessage", "description": "Sends a message to a Slack channel", "integration": "slack", "action": "send_message", "input_schema": { "type": "object", "properties": { "channel": { "type": "string" }, "message": { "type": "string" } }, "required": ["channel", "message"] }, "speech": "Sending that message to Slack now.", "timeout": 10000 } ``` ```json Response (Success) theme={null} { "status": "success", "data": { "id": "abc123def456" }, "errors": null } ``` ```json Error (INVALID_PARAMETER) theme={null} { "data": null, "errors": [ { "code": "INVALID_PARAMETER", "message": "name is required" } ] } ``` ```json Error (INVALID_TOOL_TYPE) theme={null} { "data": null, "errors": [ { "code": "INVALID_TOOL_TYPE", "message": "The specified tool type is not supported" } ] } ``` ```json Error (INTEGRATION_NOT_FOUND) theme={null} { "data": null, "errors": [ { "code": "INTEGRATION_NOT_FOUND", "message": "Integration 'my_integration' is not available. Available integrations: bland-sms, custom-code, slack, salesforce, rest_api, hubspot, calendly, cal-com-v2, notion" } ] } ``` ```json Error (ACTION_NOT_FOUND) theme={null} { "data": null, "errors": [ { "code": "ACTION_NOT_FOUND", "message": "Action 'my_action' not found for integration 'slack'. Available actions: send_message, create_channel" } ] } ``` ```json Error (RESOURCE_NOT_FOUND) theme={null} { "data": null, "errors": [ { "code": "RESOURCE_NOT_FOUND", "message": "Resource not found or is inactive" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Update Tool Source: https://docs.bland.ai/api-v2/post/tools-tool-id POST https://api.bland.ai/v2/tools/{tool_id} Update an existing tool. All fields are optional. Only the fields you provide will be updated. ### Headers Your API key for authentication. ### Path Parameters The unique identifier of the tool to update. ### Body Parameters All fields are optional. Only fields included in the request body will be updated. The name the AI will see when deciding to use this tool. Description of what the tool does. The integration key to update. Must be one of: `bland-sms`, `custom-code`, `slack`, `salesforce`, `rest_api`, `hubspot`, `calendly`, `cal-com-v2`, `notion`. The action key to invoke within the integration. To discover available action keys, call `GET /v1/integrations/{integration}/actions`. Returns `400 ACTION_NOT_FOUND` with the list of valid actions if the key is invalid. Must be a valid OpenAI function calling parameter schema. Defines the parameters the AI will fill in when invoking this tool. Request body template sent to the integration. Text the AI says aloud while executing this tool. Maximum time in milliseconds to wait for the integration. Minimum `1000`, maximum `60000`. Whether to cache the tool's response. Defines which fields to extract from the integration response. Variable name to assign the extracted value. JSON path to the value in the response. Optional description of what this data represents. Number of times to retry the tool on failure. Minimum `0`, maximum `4`. Seconds to wait between retries. Minimum `1`, maximum `30`. UUID of a connected resource (e.g. a Slack workspace or Salesforce org) to scope this tool to. The resource must be active and belong to your account. Returns `404` if the ID is invalid or inactive. To list available resource IDs for an integration, call `GET /v1/integrations/{integration}/resources`. Whether this tool is publicly visible. Human-readable label for this tool. ### Response `"success"` on success, `"error"` on failure. The ID of the updated tool. `null` on success, or a list of error objects if the request failed. ```json Request (Partial Update) theme={null} { "description": "Sends an urgent message to a Slack channel", "timeout": 15000 } ``` ```json Response (Success) theme={null} { "status": "success", "data": { "id": "abc123def456" }, "errors": null } ``` ```json Error (TOOL_NOT_FOUND) theme={null} { "data": null, "errors": [ { "code": "TOOL_NOT_FOUND", "message": "Tool not found" } ] } ``` ```json Error (INVALID_PARAMETER) theme={null} { "data": null, "errors": [ { "code": "INVALID_PARAMETER", "message": "timeout must be between 1000 and 60000" } ] } ``` ```json Error (TOOL_V2_UPDATE_VALIDATION_ERROR) theme={null} { "data": null, "errors": [ { "code": "TOOL_V2_UPDATE_VALIDATION_ERROR", "message": "Validation failed for the provided tool configuration" } ] } ``` ```json Error (INVALID_TOOL_TYPE) theme={null} { "data": null, "errors": [ { "code": "INVALID_TOOL_TYPE", "message": "The specified tool type is not supported" } ] } ``` ```json Error (INTEGRATION_NOT_FOUND) theme={null} { "data": null, "errors": [ { "code": "INTEGRATION_NOT_FOUND", "message": "Integration 'my_integration' is not available. Available integrations: bland-sms, custom-code, slack, salesforce, rest_api, hubspot, calendly, cal-com-v2, notion" } ] } ``` ```json Error (ACTION_NOT_FOUND) theme={null} { "data": null, "errors": [ { "code": "ACTION_NOT_FOUND", "message": "Action 'my_action' not found for integration 'slack'" } ] } ``` ```json Error (RESOURCE_NOT_FOUND) theme={null} { "data": null, "errors": [ { "code": "RESOURCE_NOT_FOUND", "message": "Resource not found or is inactive" } ] } ``` *** Docs for agents: [llms.txt](/llms.txt) # Synthesize Speech (HTTP) Source: https://docs.bland.ai/api-v2/post/tts POST https://api.bland.ai/v2/tts Generate speech from a complete input string over HTTP. ## Overview Use this endpoint when the complete text is available before synthesis begins. It returns a streaming raw response or a complete WAV file in one HTTP request. For LLM tokens, multiple conversational turns, and interruption support, use [Realtime Speech (WebSocket)](/api-v2/post/tts-ws). It is the primary endpoint for realtime TTS. `text` and `voice` are the only required fields. You get 48 kHz PCM frames by default, ready to play or forward to a client. Set `audio.container` to `wav` for a file you can download and open. Use a **`BTTS_V3`** voice. `expressiveness` and `stability` are calibrated for it, and 48 kHz is the rate it renders natively. `BTTS_V2` voices synthesize, but the controls are not tuned for them. Read `x-model` to see which model a voice resolved to. **Coming from `/v1/speak`?** `container: "raw"` returns bare audio frames. The v1 endpoints wrapped `pcm_` in a WAV header, so v1 clients usually skip 44 bytes before playback. Doing that here removes 44 bytes of real audio. Drop the header handling, or ask for `container: "wav"`. ## Pricing Text-to-speech is currently billed at **\$0.015 per 1,000 characters**, the same rate on every plan. This is a limited-time launch offer, discounted from the standard \$0.04 per 1,000 characters. Each request carries a minimum charge of \$0.001, so very short generations bill at the minimum rather than the per-character rate. Some public-library voices carry an additional per-character creator fee. For a completed response, the charge comes back in the `x-cost` header. An interrupted raw stream can bill less because delivery accounting happens after that header is sent. Billing follows delivery. A synthesis that fails before any bytes are written is not charged, and a fully delivered request is charged for the whole `text`. If a raw response is interrupted mid-stream, billing estimates the delivered characters at synthesized-chunk granularity. Individual audio bytes cannot be mapped to exact source characters. *** ## Headers Your API key. *** ## Body Parameters The text to speak. Maximum 5,000 characters. Insert a pause with `<|N|>`, where N is a positive number of seconds: `"Welcome to Bland. <|0.8|> How can I help?"` Voice UUID. Names are not accepted. Get a UUID from [List Voices](/api-v1/get/voices). Output format. All fields optional. Audio codec. * `pcm_s16le`: 16-bit signed little-endian PCM. * `mulaw`: 8-bit mu-law, 8 kHz only. For telephony. Output sample rate in Hz: `8000`, `16000`, `24000`, `44100`, or `48000`. 48 kHz is what `BTTS_V3` renders natively, so it is the fastest path. With `mulaw`, the rate is fixed at `8000` and any other value returns a `400`. How the bytes are framed. * `raw`: bare audio frames. For streaming and voice agents. * `wav`: one RIFF/WAVE file with a correct-length header. The full render is buffered before the first byte goes out, since a valid header needs the final size. For downloads. Trying the endpoint by hand? Use `wav`. `raw` returns bare samples that most players cannot open. How the voice performs. Both are optional and range from `0.0` to `1.0`. Higher is more varied intonation; lower is flatter and more monotone. Higher is more consistent between renders; lower is more creative and varied. *** ## Response Audio in the encoding and container you asked for. * `raw` + `pcm_s16le` → `Content-Type: audio/pcm` * `raw` + `mulaw` → `Content-Type: audio/basic` * `wav` (any encoding) → `Content-Type: audio/wav` These headers arrive with the first byte. Unique ID for this request. Include it in support tickets. The model that produced the audio, for example `btts-3`. Set by the voice you chose. The voice UUID used. Output sample rate in Hz. Full-response cost in USD. It matches the final charge when the response completes; an interrupted raw stream may have a lower delivery-based charge. Milliseconds to the first audio byte. For `wav`, the full render time. ### Errors Every error returns the same shape, with a stable machine-readable code: ```json theme={null} { "error": { "code": "voice_not_found", "message": "Voice … was not found or is not accessible." } } ``` | Code | HTTP | Meaning | | ------------------------- | ---- | ------------------------------------------------------------------ | | `invalid_request` | 400 | A required field is missing or has the wrong shape. | | `text_too_long` | 400 | `text` exceeds 5,000 characters. | | `unsupported_encoding` | 400 | `audio.encoding` is not an allowed value. | | `unsupported_sample_rate` | 400 | `audio.sample_rate` is not allowed for the encoding. | | `unsupported_container` | 400 | `audio.container` is not `raw` or `wav`. | | `unsupported_voice` | 400 | The voice exists but is not a `BTTS_V2` or `BTTS_V3` voice. | | `insufficient_credits` | 402 | The account is out of credits. | | `voice_not_live` | 403 | The professional voice is still a draft. Promote it to live first. | | `voice_not_found` | 404 | The voice UUID does not exist, or you cannot access it. | | `synthesis_failed` | 500 | Synthesis failed before or during streaming. | *** ## Examples ### Downloadable WAV file ```bash cURL theme={null} curl -X POST "https://api.bland.ai/v2/tts" \ -H "Authorization: Bearer $BLAND_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "Hello world.", "voice": "29158307-9893-4149-8a75-bc9ce313d64e", "audio": { "encoding": "pcm_s16le", "sample_rate": 24000, "container": "wav" }, "controls": { "expressiveness": 0.7, "stability": 0.5 } }' \ --output hello.wav ``` ### Default (48 kHz PCM, raw) ```bash cURL theme={null} curl -X POST "https://api.bland.ai/v2/tts" \ -H "Authorization: Bearer $BLAND_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "Welcome to Bland.", "voice": "29158307-9893-4149-8a75-bc9ce313d64e" }' \ --output out.pcm ``` ### Telephony (μ-law, 8 kHz) ```bash cURL theme={null} curl -X POST "https://api.bland.ai/v2/tts" \ -H "Authorization: Bearer $BLAND_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "Your appointment is confirmed for Tuesday at 3 PM.", "voice": "29158307-9893-4149-8a75-bc9ce313d64e", "audio": { "encoding": "mulaw", "sample_rate": 8000 } }' \ --output prompt.ulaw ``` ```http Response headers theme={null} HTTP/2 200 content-type: audio/pcm x-request-id: 5f9c…-…-… x-model: btts-3 x-voice-id: 29158307-9893-4149-8a75-bc9ce313d64e x-sample-rate: 48000 x-cost: 0.001000 x-latency: 312 *** Docs for agents: [llms.txt](/llms.txt) # Realtime Speech (WebSocket) Source: https://docs.bland.ai/api-v2/post/tts-ws Stream LLM text into one realtime session and receive speech as binary audio frames. ## Overview ```text theme={null} wss://api.bland.ai/v2/tts/ws ``` Use this endpoint when text arrives incrementally, such as tokens from an LLM. Keep one WebSocket open for the conversation. Bland buffers incoming text, finds useful speech boundaries, and starts returning audio before the turn is complete. The connection supports one active turn at a time. A new `context_id` immediately preempts the active turn, which makes interruption and barge-in a normal part of the protocol. Stream a turn token by token and save the returned audio. Learn how buffering, playback, cancellation, and billing work. Use a `BTTS_V3` voice for the native 48 kHz path and its calibrated performance controls. `BTTS_V2` voices also synthesize. If you already have the complete text and want a file response, use [Synthesize Speech (HTTP)](/api-v2/post/tts). Existing OpenAI SDK integrations can use [Speech (OpenAI-compatible)](/api-v2/post/audio-speech). ## Authentication Credentials are checked in this order: 1. `?token=` for browser clients. Mint it from your backend with [Mint Stream Input Token](/api-v1/post/speak-stream-input-token). 2. `Authorization: Bearer ` for server-side clients. A bare `Authorization: ` value is also accepted. 3. `Sec-WebSocket-Protocol: bland.api_key.`. 4. `?api_key=`, which is deprecated because URLs can enter logs. Never put a long-lived API key in browser code. Mint a short-lived stream token on your backend and connect with `?token=`. A request with no credentials is rejected before the WebSocket opens. Server-side clients receive HTTP `401` with code `AUTH_REQUIRED`. Browsers only report that the connection failed because the browser WebSocket API does not expose upgrade response bodies. An invalid or expired credential is rejected after the upgrade with an `AUTH_FAILED` control frame and close code `4001`. ## Framing * Client and server control messages are JSON text frames. * Audio is sent as raw binary WebSocket frames, without JSON, base64, or a container header. * Every binary frame after `utterance_start` and before its matching `utterance_end` belongs to that turn. Use the WebSocket library's binary indicator to distinguish audio from control messages. Do not try to parse a binary audio frame as JSON. ## Client messages ### `init` Send `init` once as the first message. Wait for `ready` before sending text. ```json theme={null} { "type": "init", "voice": "29158307-9893-4149-8a75-bc9ce313d64e", "audio": { "encoding": "pcm_s16le", "sample_rate": 48000 }, "controls": { "expressiveness": 0.6, "stability": 0.5 } } ``` Must be `init`. Bland voice UUID. Get one from [List Voices](/api-v1/get/voices). The voice is fixed for the life of the connection, so open another connection to change voices. Requested raw audio format. `pcm_s16le` for signed 16-bit little-endian PCM, or `mulaw` for G.711 mu-law telephony audio. For PCM: `8000`, `16000`, `24000`, `44100`, or `48000`. Mu-law is fixed at `8000`. Optional performance controls. Both values must be between `0.0` and `1.0`. Higher values create more varied intonation. Lower values are flatter. Higher values make repeated renders more consistent. Lower values allow more variation. ### `speak` Append a text delta to a turn. Send each LLM token or any larger fragment as soon as it is available. Do not resend the full accumulated response. ```json theme={null} { "type": "speak", "context_id": "turn-42", "text": "Hello" } ``` ```json theme={null} { "type": "speak", "context_id": "turn-42", "text": ", how can I help?" } ``` Your unique ID for this turn. Reuse it for every text delta in the same turn. Sending `speak` with a different ID preempts the active turn before starting the new one. The next text delta. A single character is valid. One turn may contain at most 4,000 characters in total. ### `end_of_turn` Tell Bland that no more text will arrive for the turn. Bland flushes the remaining buffered text, finishes its audio, and sends `utterance_end` with reason `complete`. ```json theme={null} { "type": "end_of_turn", "context_id": "turn-42" } ``` Always send this after the LLM finishes normally. Wait for that turn's `utterance_end` before sending `close`. ### `cancel` Stop the active turn without starting a replacement. Buffered text is discarded and the server sends `utterance_end` with reason `cancelled`. ```json theme={null} { "type": "cancel", "context_id": "turn-42" } ``` Use `cancel` when a user interrupts and replacement text is not ready. If you already have replacement text, send `speak` with a new `context_id`; the new turn preempts the old one automatically. ### `close` End the session, settle outstanding usage, receive `done`, and close the WebSocket normally. ```json theme={null} { "type": "close" } ``` `close` does not flush an unfinished turn. It ends that turn as `cancelled`. To finish speaking, send `end_of_turn`, wait for `utterance_end`, then send `close`. ## Server messages ### `ready` The voice, connection, and billing admission are ready. You can now send text. ```json theme={null} { "type": "ready", "session_id": "2B17uYlR6p48uPpN", "encoding": "pcm_s16le", "sample_rate": 48000 } ``` ### `utterance_start` Sent as soon as the first `speak` message for an admitted turn is accepted. It arrives before any audio and before `utterance_end`, including when the turn is cancelled before producing audio. ```json theme={null} { "type": "utterance_start", "context_id": "turn-42" } ``` ### Binary audio Each binary frame contains raw mono audio in the encoding and sample rate negotiated by `ready`. Frame sizes are not fixed. Concatenate or enqueue the frames in arrival order. The server may produce audio faster than it plays. Your application must use a playback queue or forward frames to a media transport that provides one. See [Buffering audio for playback](/tts/realtime-concepts#buffering-audio-for-playback). ### `utterance_end` Exactly one terminal message is sent for each started turn. ```json theme={null} { "type": "utterance_end", "context_id": "turn-42", "reason": "complete", "frames": 18, "duration_ms": 842 } ``` `complete`, `preempted`, `cancelled`, or `failed`. Number of binary audio frames delivered for the turn. It can be `0`. Elapsed wall-clock time from starting the turn to ending it. This is not the audio playback duration. ### `error` ```json theme={null} { "type": "error", "code": "insufficient_credits", "message": "Your account is out of credits.", "context_id": "turn-43" } ``` `context_id` is present when the error belongs to one turn. Some message errors leave the session open. Session-level protocol, idle, and slow-consumer errors close it. ### `done` The session has settled and is about to close normally. ```json theme={null} { "type": "done", "session_id": "2B17uYlR6p48uPpN" } ``` ## Error codes | Code | Scope | Meaning | | ------------------------- | ------------------ | -------------------------------------------------------------------------------------- | | `AUTH_REQUIRED` | HTTP upgrade | No credential was supplied. The server returns HTTP `401` without opening a WebSocket. | | `AUTH_FAILED` | Connection | The supplied credential is invalid or expired. | | `INSUFFICIENT_CREDITS` | Connection | The wallet gate rejected the connection before initialization. | | `USER_BANNED` | Connection | The authenticated user is banned. | | `ORG_DELETED` | Connection | The authenticated organization no longer exists or is deleted. | | `ORG_SUSPENDED` | Connection | The authenticated organization is suspended. | | `ORG_STRIPE_OVERDUE` | Connection | The authenticated organization has overdue invoices. | | `STATE_LOOKUP_FAILED` | Connection | Bland could not safely verify account state. | | `invalid_message` | Message or session | A frame is not valid JSON, has an unknown type, or has an invalid field. | | `init_required` | Session | A message other than `close` arrived before `init`. | | `already_initialized` | Session | `init` was sent more than once. | | `invalid_request` | Message or session | A field is invalid for the current state. | | `voice_not_found` | Session | The voice does not exist or is not accessible. | | `unsupported_voice` | Session | The voice is not a `BTTS_V2` or `BTTS_V3` voice. | | `voice_not_live` | Session | A professional voice is still a draft. Promote it to live first. | | `unsupported_encoding` | Session | The requested encoding is not supported. | | `unsupported_sample_rate` | Session | The sample rate is invalid for the encoding. | | `context_overflow` | Turn | One turn exceeded 4,000 characters. | | `insufficient_credits` | Turn | The current turn was refused because the account is out of credits. | | `rate_limited` | Session | The organization has no available speech concurrency slot. | | `idle_timeout` | Session | No client message arrived for 60 seconds. | | `slow_consumer` | Session | The client did not read audio fast enough. | | `synthesis_failed` | Turn or session | The voice session or turn could not synthesize. | ## Billing and concurrency * The connection occupies one speech concurrency slot from successful `init` until it closes, including gaps between turns. * The wallet is checked again before every turn. * Each turn is settled separately and has the current minimum charge of \$0.001 when it delivers billable audio. * A synthesized text chunk becomes billable when the server accepts its first audio frame for delivery. Preemption or cancellation does not charge text that remained buffered or produced no audio. * Character attribution is estimated at synthesized-chunk granularity. Bland cannot map individual audio frames back to exact source characters. * Public creator voices may add their published per-character creator fee. See [Realtime TTS concepts](/tts/realtime-concepts#billing-on-interrupted-turns), [Speech Limits](/speech/limits), and [Synthesize Speech (HTTP)](/api-v2/post/tts#pricing) for more detail. *** Docs for agents: [llms.txt](/llms.txt) # January 5, 2026 Source: https://docs.bland.ai/changelog/01_05_2026 Pathway generation improvements, web widget enhancements, and warm transfer stability fixes ### Improvements **Pathways & Routing** * Improved timeout rate when generating pathways * Persists new pathway nodes/edges after pathway transfers, fixing "nodes or edges missing" errors when warm transfers trigger reconnections **SMS** * \[Enterprise] SMS logs maintain text whitespace formatting **Citations** * \[Enterprise] Rejects call creation if citation\_schema\_ids are included but record: false is set **Web Widget** * Allow searching through web widget logs * Adds support for post chat webhooks for web widget **API & Development** * \[Enterprise] Fixed race condition where both citations and post call webhook would be sent separately while combined webhooks are enabled # January 12, 2026 Source: https://docs.bland.ai/changelog/01_12_2026 Salesforce Case creation, org-level webhook fallback, and SMS timeout messaging ### Improvements **Integrations** * Added Salesforce Case creation with custom field support to the Salesforce integration **API & Development** * Added org level fallback URL for webhooks that automatically applies when a webhook URL isn't passed in call configuration **SMS** * \[Enterprise] Added customizable timeout message to SMS agent for both prompt and pathway configurations SMS timeout message configuration interface > This new feature allows you to add a customized timeout message to be sent in the SMS agent once it has been reached. Works with both prompt and pathway calls. **Call Logs & Management** * Removed download and play buttons in call logs when a call wasn't recorded **Pathways & Routing** * \[Enterprise] Fixed test proxy agent for warm transfer nodes **Web Widget** * Added markdown rendering for widget messages # January 20, 2026 Source: https://docs.bland.ai/changelog/01_20_2026 Triggers and Automations, Knowledge Base editing, and BTTS V2 voice rollout ### BTTS V2 Voice Launch We are excited to roll out major improvements to our text to speech experience over the next week. When your account is upgraded, you will see a new voice appear tagged as BTTSV2 in your [voices page](https://app.bland.ai/dashboard/voices). BTTSV2 is significantly more expressive and stable, and is the new version of voices that we are rolling out to customers going forward. Attached is a [prompting guide](/tts/voices) that outlines best practices for using these new voices. In most cases, BTTSV2 should behave one to one with existing voices, though some differences may appear depending on usage and prompting. **Supported Languages:** English, Spanish, German, French, Czech, Dutch, Bulgarian, Chinese, Danish, Estonian, Finnish, Korean, Japanese, Norwegian, Italian, Polish, and Russian. **Experimental Support:** Hungarian, Swedish, Romanian, Greek, Portuguese, Indonesian, Serbo-Croatian, Slovenian, Slovak, and Welsh. **TLDR:** Voices flagged as Legacy in the voice UI will be upgraded to BTTSV2. All other V1 voices will remain unchanged, so your experience will stay the same if you are not using a legacy voice. *** ### Triggers and Automations \[Beta] Automate your workflows with visual trigger builders that respond to events from Salesforce, Notion, and more. * Build out your automations through our drag-and-drop UI * Connect to trigger sources such as Salesforce, Notion, and more soon * Configure actions to automatically send calls, and soon webhooks, SMS, and Slack messages * Adjust trigger conditions with scheduling (immediate, business hours, custom) and conditional logic with change detection (e.g., only trigger if Status changed to "Hot") * Test with mock data before deploying and track execution history Triggers gallery showing automation cards with event sources and action types Visual automation builder with drag-and-drop canvas Integration connections for event sources Action selection panel for configuring trigger responses Call configuration panel with persona and pathway settings Test trigger interface with mock data and condition results *** ### Knowledge Base Editing Edit your knowledge base files directly in Bland with full version control and change previews. * Edit text, pdf, and docx files with code editor, CSV spreadsheets with inline editing, and web scrape URL management * Full version control with history, compare versions side-by-side, and restore previous versions * Diff previews to see exactly what changed before saving your new version * Integrated chat widget to test against any version * Upload new files while keeping version history Knowledge base editing page with Monaco code editor Visual diff view showing changes before saving CSV knowledge base viewing page Spreadsheet-style CSV editor with inline editing PDF knowledge base viewer with extracted text *** ### Improvements **Call Logs & Management** * Enhanced call details page with additional call context (Interruption Threshold, Temperature, Noise Cancellation) and reorganized metadata into cleaner sections * Call log export enhancements for larger file size and faster email trigger speed **Pathways & Routing** * Fixed edge case where node positions within pathways would not persist after save, version promotion, or reopen, and added node positions to [GET pathway details endpoint](/api-v1/get/pathway) * Added request data to personas **Integrations** * Added support for URL encoded webhooks in [new tools](https://app.bland.ai/dashboard/tools) **Web Widget** * Added test request data capability to web widget configuration page **Citations** * \[Enterprise] Improved citation testing UX with floating call log details panel for real-time analysis # February 2, 2026 Source: https://docs.bland.ai/changelog/02_02_2026 Watchtower and other platform improvements ### Watchtower \[Enterprise] Enterprise hallucination prevention that addresses incorrect value extraction and false loop condition assessments at scale. * Runs critical decisions multiple times in parallel to identify consensus patterns, then automatically flags low confidence when outputs diverge across variable extractions and loop conditions * When unreliable results are detected, retry with clarification prompts, transfer to human agents, or route to alternative pathway nodes * Surfaces unreliable nodes and uses fail-safe protocols that handle uncertainty gracefully instead of returning confident but incorrect responses Watchtower compliance and evaluation settings

Enable watchtower under the Compliance & Policy Management section page of the dashboard

Watchtower node configuration interface with guard rail controls

This node uses watchtower to enable guard rails specifically on the loop condition, which will transfer the call if the condition fails after unreliable results are detected

*** ### Improvements **[Automations & Integrations](https://app.bland.ai/dashboard/automations)** * Added Slack notifications and webhook triggers for internal automation events * Hubspot integration enhancements including custom field support, user-defined validation rules, and association-based automation triggers for calling contacts linked to tickets, tasks, and deals **Voice & Telephony** * \[Enterprise] Added background audio support for SIP calls # February 9, 2026 Source: https://docs.bland.ai/changelog/02_09_2026 Pathway UI redesign, memory upgrades, and SMS support for personas ### Pathway UI Update Complete redesign of the pathway testing interface with resizable panels, advanced debugging capabilities, and conversation branching. * Drag to resize panels or open floating windows, and pin key messages for quick access, with your layout preferences saved between sessions * Branch new conversation paths from any message during testing to explore alternate scenarios without restarting * Toggle detailed execution logs showing secondary actions (loop conditions, variable extractions, routing) * Run test simlulations on historic calls using your drafted node changes Resizable testing panel and node drawer with drag handles

Along with converting our node views into draggable panels, you can pop them out to create floating windows

Branch indicator showing alternate conversation paths

At any point during a test chat, edit your user message to branch to a new conversation, where that input was used and subsequent agent responses are changed. You can view and swith between these from the conversation UI

Advanced mode showing detailed execution logs and secondary actions

View detailed logs including webhooks, knowledge base calls, and node transitions (routes and loops)

Test Node button in drawer that opens testing panel with draft state

Reference previous calls using your pathway, and generate user responses based on a node's prompting

Testing panel showing draft node configuration in action

Run your prompting against the generated user responses and see how often your outputs meet your LLM grading goal

*** ### Upgraded Memory Massive update to our memory feature, bridging voice and SMS modalities. [Learn more about memory](https://docs.bland.ai/tutorials/memories) * Memory context automatically synced between phone calls and SMS conversations for the same contact * New memory UI that displays new information added to contact based on their conversation * Enable or disable memory per pathway and persona *** ### Improvements **Personas** * Personas now support SMS conversations with full feature parity to voice calls **Pathways & Routing** * Transfer pathway node now accepts variables as input for dynamic pathway routing **UI/UX Improvements** * Added prompter role to permission set for granular access control. Prompters are able to read and write pathways, but cannot publish or deploy # February 16, 2026 Source: https://docs.bland.ai/changelog/02_16_2026 Bland Console, canary deployments, and pathway blocks library ### Norm, The Bland Console Meet Norm, our new AI assistant built directly into the pathway editor. Norm understands your entire pathway and lets you propose changes in plain language. Just describe what you want, then review a clear diff of every node and edge before you apply the update. * Changes are applied to a forked version of your pathway, keeping your original intact until you're ready to publish * Reference specific nodes by name using @ mentions for targeted changes, with the AI asking for confirmation or clarification before applying anything * View before and after content for every node and edge changed Bland Console chat interface embedded in the pathway editor

Describe changes in plain language directly from the pathway editor

Diff view showing proposed node and edge changes before applying

Review every proposed change before applying to your pathway

*** ### Canary Deployments \[Enterprise] Test new agent releases against live traffic before committing to a full rollout, with dedicated canary infrastructure running alongside production and full control over traffic routing. Available under your org's settings page, under [Releases](https://app.bland.ai/dashboard/settings/releases) [Learn more about Infrastructure & Releases](/enterprise-features/infrastructure-and-releases) *** ### Pathway Blocks Save any group of nodes and edges as a reusable block and insert it into any pathway with one click. * Select 2 or more nodes and save them as a named block with a description and category * Browse your saved blocks alongside Bland-curated blocks in the node library * Insert any block directly onto the canvas with "Add to Pathway" Pathway blocks tab in the node library showing saved blocks

Select groups of nodes within your pathway to be saved as a block

Save pathway block form with name, description, and category fields

After selecting, click the save button in the bottom left to create a new block

Inserting a pathway block onto the canvas

Insert any block directly onto the canvas with one click through the "Add New Node" pane

*** ### Improvements **Pathways & Routing** * Existing edges can now be dragged and dropped onto a new target node to reroute without deleting and recreating them * Node drawer prompt section now includes a markdown toggle and draggable cheatsheet window, with accordion state remembered between sessions **Call Logs & Management** * Fixed inbound calls not properly displaying the pathway version used within the call logs page **Citation Testing** * Redesigned citation testing flow with a multi-stage interface for call selection, running tests, and viewing results as a slide-over panel instead of a modal **Web Widget** * Webhook settings now include a mode toggle to send events on every message or only when the conversation ends **UI/UX Improvements** * Redesigned home dashboard with updated layout, new summary stats showing total calls, daily average, and active regions, and reorganized sections for call distribution and recent activity # February 23, 2026 Source: https://docs.bland.ai/changelog/02_23_2026 Standards, Outcomes, and native widget components ### Standards Standards are our new node-level regression framework that runs your node prompts through fixed scenarios (simulations for dialogue, permutations for loop conditions and variable extractions) ten times each to automatically catch behavior regressions when prompts change. [Learn more about Standards](/tutorials/standards) Standards tab in the pathway testing panel showing defined standards

Open Standards at individual nodes

Building a Standard view showing a source call, simulation prompt, and success definition

Select a source call to automatically generate a simulation prompt and success definition

Test Results view showing pass and fail outcomes across all 10 test iterations

View pass and fail outcomes across all 10 test iterations

*** ### \[Enterprise] Outcomes Extract structured data from your calls using custom JavaScript that runs automatically as part of the post-call workflow. * Define output fields and Bland generates a transformation script from a real call. Select any past call as test input to generate code from the actual data structure * Backtest against real calls in the editor * Attach outcomes to outbound calls, batch calls, inbound numbers, and send-call nodes. Results surface in a new tab on every call log with post call webhooks enabled Outcomes list page showing defined outcomes Outcomes editor showing output field definitions and generated transformation script Backtest output panel showing outcome run results and AI fix feedback

Define output fields and generate a transformation script from a real call

Outcome results surfaced inline on a call log

Run backtests against real calls in the editor

*** ### Improvements **Web Widget** * Added native Quick Replies, Accordions, and Cards components to the web widget, rendering interactive UI elements inline in chat without requiring an iframe **Call Logs & Management** * Redesigned call logs with a unified event timeline, inline resizable side panel, rebuilt audio player, and rich text notes **Pathways & Routing** * Improved node and pathway autosaving stability # March 11, 2026 Source: https://docs.bland.ai/changelog/03_11_2026 Pathway testbed, SIP wizard, and Bland Speech ### Pathway Testbed An interactive testing environment for individual pathway nodes, accessible directly from the testing panel. * Run any node against custom inputs to see prompt outputs, variable extractions, and condition evaluations in real time * Review full conversation histories and rerun with adjusted variables or prompts without placing a live call * Standards are integrated directly into the testbed so you can view and run regression checks alongside your manual tests Pathway chat panel with Open in testbed button on a conversation message

Open any node directly in the testbed from an active chat session

Testbed showing node prompt on the left and standard configuration on the right

Edit the node prompt and configure simulation scenarios and success criteria side by side

Simulation results showing 10/10 passing with conversation transcript preview

Review simulation results and inspect individual conversation transcripts

Variable extraction standard showing exact match evaluation with actual vs expected comparison

Validate variable extraction with exact match evaluation across 10 simulations

Loop condition standard showing True/False success definition with 10/10 passing results

Test loop conditions with a True/False success definition and configurable threshold

*** ### SIP Wizard \[Enterprise] A new SIP dashboard with a guided setup wizard, call logs, monitoring, and number porting. * Step-by-step setup wizard covers trunk direction, auto-discovery, destination routing, authentication, firewall configuration, and inbound number assignment * Place a live test call directly from the final wizard step to verify connectivity before going live * Full SIP dashboard with dedicated call logs, SIP trace viewer, and monitoring configuration for alerts, codecs, and failover SIP Configuration wizard step 1 — choose between Inbound and Outbound SIP

Start by choosing inbound or outbound — each is configured separately

SIP Configuration wizard step 2 — select your provider and enter SIP server address

Select your provider and enter your SIP server address

SIP Trunks dashboard showing trunk list with direction, endpoint, and call logs

Manage all your trunks and view per-trunk call logs from the SIP dashboard

Port A Number wizard showing LOA info form with carrier and address details

Port existing numbers with a guided LOA form — carrier details, authorized rep, and target port date

*** ### Bland Speech A standalone text-to-speech product now available directly from the dashboard. [Try it here.](https://app.bland.ai/dashboard/tts) * Synthesize speech from any text using the full Bland voice library, with live audio playback, cost estimates, and a persistent generation history * Browse, preview, and add voices from the voice library to your account, or clone and manage custom voices in the voice lab * Access usage analytics and a complete developer API reference, plus quick-start code examples in cURL, Python, and Node.js Text to Speech synthesis page with popular voices grid, text input, and Generate Speech button

Pick a voice, type your text, and generate speech directly from the dashboard

Developer API page showing authentication, code examples in cURL and Node, and streaming docs

Quick-start code examples and full API reference including streaming

*** ### Improvements **Pathways & Routing** * Added a persistent save banner to node and edge drawers so unsaved changes are always visible **Call Logs & Management** * Fixed call logs not correctly displaying pathway context when calls crossed a Transfer Pathway node * Live Translation logs are now captured per call and surfaced in call details, showing source and target language alongside original and translated text **Tools** * Redesigned tool creation with a step-by-step flow covering setup, output variables, and value inputs **API** * Added `timezone` parameter to `GET /v1/calls` for timezone-aware date filtering * Added org-level option to exclude `pathway_logs` from post-call webhook payloads # March 23, 2026 Source: https://docs.bland.ai/changelog/03_23_2026 Tools on pathway nodes, custom standards messages, and widget translation ### Tools on Pathway Nodes Condense your pathways by running tools directly inside Default nodes. What previously required dedicated separate nodes can now live inline, with suport for more tool types being revealed soon. * Attach webhook configurations to a Default node. The Bland agent decides when to call the tool based on the dialogue prompt and conversation context (reference the name of the tool from within your dialogue prompt) * Route the call based on what the tool returns using configurable response pathways, with variable extraction from the tool output * Set speech behavior during tool execution, configure timeout and retry limits, and extract variables from the response, all inline with the node Pathway canvas comparing old approach with multiple separate Custom Tool nodes versus new approach with tools embedded directly in Default nodes

What used to require a separate node for every tool call can now live inside a single Default node. Reference the name of your tool within the dialogue prompt to describe when it shoudld be triggered

Tools tab inside the Default node drawer with a webhook tool attached

Each tool is configured with its own name, webhook, and settings directly inside the node

Webhook configuration showing URL, authentication, headers, and response variable extraction fields

Each tool is configured with its own name, webhook, and settings directly inside the node

Response pathways section showing routing conditions based on tool output values

You can also choose how the agent handles the request response. Decide to respond naturally and continue, or respond and follow defined pathways to route the call

*** ### Improvements **Standards** * Custom messages can now be set when configuring a standard, rather than relying solely on auto-generated simulation prompts Standards panel with custom conversation field highlighted

Set a custom conversation directly on the standard instead of selecting one from your call history

Standards panel with custom conversation set and simulation running

Build out conversation history exactly as you see fit. With additional section for adding the conversation happening at that node (for variable extraction and loop condition standards)

Custom conversation modal showing context history and node conversation builder

Test the standard on simulation prompt and success definition

**Web Widget** * A translate button has been added to widget conversation logs for messages in non-English languages **SIP** * SIP trunks are now available to all organizations. The previous entitlement requirement has been removed. Visit the [SIP dashboard](https://app.bland.ai/dashboard/sip-trunks) or read the [SIP integration docs](/enterprise-features/SIP-integration) to get started # April 6, 2026 Source: https://docs.bland.ai/changelog/04_06_2026 Code, Custom Tool, and Tool Chain support on pathway nodes ### More Tool Types on Pathway Nodes Three new tool types are now available directly on Default nodes, expanding on the [webhook tool support introduced on March 23](/changelog/03_23_2026). Each type runs inline with the node and follows the same pattern: the agent decides when to invoke based on your dialogue prompt. * **Code:** Write JavaScript directly in the node using the inline code editor. Code runs in a secure isolate and has access to conversation variables * **Custom Tool:** Attach any saved tool from your tool library directly to a node, with support for overriding individual fields using pathway variables * **Tool Chain:** Build a multi-step pipeline that sequences webhooks, code, and custom tools in order, passing variables between steps. Use Norm within the expanded view to help configure and test the chain without leaving the node drawer! The screenshots below show a customer support pathway that handles a full service interaction in three nodes: booking a service appointment, checking a product warranty, and creating a support ticket, each using a different tool type. Book Service Appointment node using the Cal.com Create Booking custom tool

The Book Service Appointment node uses a Custom Tool to call the Cal.com Create Booking integration directly from the node

Check Warranty node using a Code tool to calculate warranty status from purchase date

The Check Warranty node runs inline JavaScript to calculate whether the warranty is active, how many days remain, and the expiry date

Create Support Ticket node showing tool chain input variable configuration

The Create Support Ticket node uses a Tool Chain. Input variables collected earlier in the conversation are passed into the chain

Tool chain step 1: Code step that formats the ticket data and generates a ticket number

Step 1 is a Code step that generates a ticket number and formats the full ticket payload, setting priority based on warranty status

Tool chain step 2: Webhook step that POSTs the ticket payload and extracts the confirmed ticket number

Step 2 is a Webhook step that POSTs the formatted ticket and extracts the confirmed ticket number from the response

Expanded pipeline builder showing input variables, code editor, and AI chat panel side by side

The full pipeline builder with input variables, code editor, and Norm open side by side

The above pathway was entirely built by [Norm](/changelog/02_16_2026#norm-the-bland-console) *** ### Improvements **Call Logs** * Added Dialed At, Outcomes, and Transferred To as filterable fields in call logs. Dialed At and disposition logs are also now included in the call logs export **Languages** * Fluent is now available as the recommended multilingual language option. Supports improved language switching across English, Spanish, French, and German **Web Widget** * Quick replies, cards, and accordions now persist in the chat across page refreshes * The active widget thread ID is now reflected in the URL for direct linking **Integrations** * Calendly tools now support dynamic resource routing. Set `resource_id` using a pathway variable (e.g. `{{advisor_resource_id}}`) to route bookings to different calendars at call time **Settings** * Admins and owners can now set a default role for new members joining the organization # April 13, 2026 Source: https://docs.bland.ai/changelog/04_13_2026 Agent-to-agent testing, persona authentication, and multiplayer pathways ### Agent-to-Agent Testing Automatically test your voice agents with an AI caller that simulates real end-to-end conversations, helping you catch issues before your users do. [Learn more](/tutorials/scenarios) or explore the [API reference](/api-v1/post/agent-testing-scenarios) * Create scenarios from pre-built templates or from scratch, each defining a caller persona with specific instructions (for example, a voicemail system) and clear success criteria for evaluation * Run individual tests or execute all scenarios in a batch, then review full conversation transcripts to see exactly how each interaction played out Edit Scenario panel showing a voicemail scenario with caller persona instructions and evaluation criteria

Configure a test scenario with a caller persona, call start prompt, and evaluation criteria to define what a successful outcome looks like

Test results showing a full conversation transcript between the agent and a voicemail system

Review the full transcript of the agent interacting with the test caller, including the evaluation result

*** ### Persona Authentication Secure your voice agents by verifying caller identity mid-conversation, ensuring only authenticated users can access sensitive information or actions * Enable authentication with built-in methods (SMS codes, identity questions, API-based verification, or custom code), and gate specific tools and pathways so they are only accessible after verification. * Configure identity questions with flexible validation modes and custom voice prompts, and define failure behavior including retry attempts, cooldowns, and what happens when all attempts are exhausted Security tab showing authentication toggle, available methods, and verification trigger options

Toggle authentication on, and decide on how strict your agent acts to authenticate the caller (flexible vs sequential)

SMS code configuration with code length, expiry, and custom message alongside a custom code editor

Configure methods like SMS code, which automatically send users an OTP over text messsage, or write custom validation logic with custom JS code

Access control section gating specific tools and pathways behind different verification methods

Decide when persona authentication takes place, and gate specific tools and pathways behind different verification methods

Identity question configuration with field key, expected format, validation mode selector, and persona voice prompts

Include optional prompting guides for how your persona authentication handles opening, succuess, and failure scenarios

Failure handling settings with retry attempts, cooldown, and end call, transfer, or continue options

Configure what happens when verification fails: retry limits, cooldown periods, and whether to end the call, transfer, or continue

*** ### Multiplayer Pathways Collaborate on pathways with your team in real time, so multiple people can build and edit together without stepping on each other's work * Collaborator avatars appear in your pathway, on individual nodes, and along edges so you can see who is working where * Live cursors from other editors are visible as they move across the pathway * When another collaborator makes changes, a banner appears with a diff view to review what changed before syncing Pathway canvas with multiple collaborator avatars, colored cursors, and real-time presence indicators

Multiple editors on the same pathway with live cursors and collaborator avatars visible on nodes and edges

Updated by a collaborator banner with View diff and Refresh buttons while editing a node

When a collaborator makes changes, a banner lets you view the diff or refresh to sync

*** ### Improvements **Inbound Calling** * Inbound numbers can now be configured with a voice pool. A random voice is selected from the pool on each call **Citations** * \[Enterprise] Citation regression tests can now be configured and run from the citation schema playground **SMS** * \[Enterprise] SMS webhooks now include conversation variables, citations, and channel information in the payload # April 30, 2026 Source: https://docs.bland.ai/changelog/04_30_2026 Triage, GitHub integration for pathway versions, Alerts, and a major analytics overhaul ### Triage A new monitoring product for capturing issues from your calls and resolving them inside the console with Norm. Flag a problem from the call logs, write a description, and let Norm reproduce, diagnose, and fix it across your pathways. Available at the [Triage dashboard](https://app.bland.ai/dashboard/monitor/triage). * Flag any call for triage from the call detail view to create an issue with severity, owner, assignee, and a description. Existing related issues automatically surface so you can link the call instead of duplicating * Each issue auto-attaches the originating calls and the pathways involved, giving Norm the full evidence profile it needs to work * Hit 'Norm Fix' to have Norm investigate the evidence, identify the root cause, apply the fix to the relevant pathway, and verify it by running testbed simulations against the patched version * Test the fixed pathway directly in chat from the issue, or open the pathway to review every change Norm made and read its full triage summary