Start Pathway Translation
curl --request POST \
--url https://api.bland.ai/v2/agents/migrate/translations \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"pathways": [
{
"pathway_id": "<string>",
"version": 123,
"mode": "<string>"
}
],
"name": "<string>",
"create": true,
"persona_id": "<string>",
"pathway_modes": [
{}
]
}
'import requests
url = "https://api.bland.ai/v2/agents/migrate/translations"
payload = {
"pathways": [
{
"pathway_id": "<string>",
"version": 123,
"mode": "<string>"
}
],
"name": "<string>",
"create": True,
"persona_id": "<string>",
"pathway_modes": [{}]
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
pathways: [{pathway_id: '<string>', version: 123, mode: '<string>'}],
name: '<string>',
create: true,
persona_id: '<string>',
pathway_modes: [{}]
})
};
fetch('https://api.bland.ai/v2/agents/migrate/translations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bland.ai/v2/agents/migrate/translations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'pathways' => [
[
'pathway_id' => '<string>',
'version' => 123,
'mode' => '<string>'
]
],
'name' => '<string>',
'create' => true,
'persona_id' => '<string>',
'pathway_modes' => [
[
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v2/agents/migrate/translations"
payload := strings.NewReader("{\n \"pathways\": [\n {\n \"pathway_id\": \"<string>\",\n \"version\": 123,\n \"mode\": \"<string>\"\n }\n ],\n \"name\": \"<string>\",\n \"create\": true,\n \"persona_id\": \"<string>\",\n \"pathway_modes\": [\n {}\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.bland.ai/v2/agents/migrate/translations")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"pathways\": [\n {\n \"pathway_id\": \"<string>\",\n \"version\": 123,\n \"mode\": \"<string>\"\n }\n ],\n \"name\": \"<string>\",\n \"create\": true,\n \"persona_id\": \"<string>\",\n \"pathway_modes\": [\n {}\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/migrate/translations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"pathways\": [\n {\n \"pathway_id\": \"<string>\",\n \"version\": 123,\n \"mode\": \"<string>\"\n }\n ],\n \"name\": \"<string>\",\n \"create\": true,\n \"persona_id\": \"<string>\",\n \"pathway_modes\": [\n {}\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"run": {
"id": "eb732a2a-94a9-45ae-9def-ecbc56c4a5bf",
"status": "PENDING",
"total_pathways": 2,
"completed_pathways": 0,
"result": null,
"error_code": null,
"error_message": null,
"created_at": "2026-09-10T20:01:12.530Z",
"completed_at": null
}
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "TOO_MANY_TRANSLATIONS",
"message": "at most 5 pathways can be AI-translated in one job — split the selection or switch some to 1:1"
}
]
}
{
"data": null,
"errors": [
{
"error": "TOO_MANY_ACTIVE_TRANSLATIONS",
"message": "at most 3 translation jobs can run at once — wait for one to finish or cancel it"
}
]
}
{
"data": null,
"errors": [
{
"error": "TOO_MANY_REQUESTS",
"message": "Too many pathway migrations started for this organization — please wait before starting another."
}
]
}
Migration
Start Pathway Translation
Start an async job translating pathways into scenarios.
POST
/
v2
/
agents
/
migrate
/
translations
Start Pathway Translation
curl --request POST \
--url https://api.bland.ai/v2/agents/migrate/translations \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"pathways": [
{
"pathway_id": "<string>",
"version": 123,
"mode": "<string>"
}
],
"name": "<string>",
"create": true,
"persona_id": "<string>",
"pathway_modes": [
{}
]
}
'import requests
url = "https://api.bland.ai/v2/agents/migrate/translations"
payload = {
"pathways": [
{
"pathway_id": "<string>",
"version": 123,
"mode": "<string>"
}
],
"name": "<string>",
"create": True,
"persona_id": "<string>",
"pathway_modes": [{}]
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
pathways: [{pathway_id: '<string>', version: 123, mode: '<string>'}],
name: '<string>',
create: true,
persona_id: '<string>',
pathway_modes: [{}]
})
};
fetch('https://api.bland.ai/v2/agents/migrate/translations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bland.ai/v2/agents/migrate/translations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'pathways' => [
[
'pathway_id' => '<string>',
'version' => 123,
'mode' => '<string>'
]
],
'name' => '<string>',
'create' => true,
'persona_id' => '<string>',
'pathway_modes' => [
[
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v2/agents/migrate/translations"
payload := strings.NewReader("{\n \"pathways\": [\n {\n \"pathway_id\": \"<string>\",\n \"version\": 123,\n \"mode\": \"<string>\"\n }\n ],\n \"name\": \"<string>\",\n \"create\": true,\n \"persona_id\": \"<string>\",\n \"pathway_modes\": [\n {}\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.bland.ai/v2/agents/migrate/translations")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"pathways\": [\n {\n \"pathway_id\": \"<string>\",\n \"version\": 123,\n \"mode\": \"<string>\"\n }\n ],\n \"name\": \"<string>\",\n \"create\": true,\n \"persona_id\": \"<string>\",\n \"pathway_modes\": [\n {}\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/migrate/translations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"pathways\": [\n {\n \"pathway_id\": \"<string>\",\n \"version\": 123,\n \"mode\": \"<string>\"\n }\n ],\n \"name\": \"<string>\",\n \"create\": true,\n \"persona_id\": \"<string>\",\n \"pathway_modes\": [\n {}\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"run": {
"id": "eb732a2a-94a9-45ae-9def-ecbc56c4a5bf",
"status": "PENDING",
"total_pathways": 2,
"completed_pathways": 0,
"result": null,
"error_code": null,
"error_message": null,
"created_at": "2026-09-10T20:01:12.530Z",
"completed_at": null
}
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "TOO_MANY_TRANSLATIONS",
"message": "at most 5 pathways can be AI-translated in one job — split the selection or switch some to 1:1"
}
]
}
{
"data": null,
"errors": [
{
"error": "TOO_MANY_ACTIVE_TRANSLATIONS",
"message": "at most 3 translation jobs can run at once — wait for one to finish or cancel it"
}
]
}
{
"data": null,
"errors": [
{
"error": "TOO_MANY_REQUESTS",
"message": "Too many pathway migrations started for this organization — please wait before starting another."
}
]
}
Overview
Starts a background job that converts pathways into agent scenarios, using Bland’s migration planner for entries intranslate mode and the deterministic one-to-one conversion for the rest. The body takes either the pathway-selection shape of Migrate Pathways (stored pathways only) or the persona shape of Migrate Persona; a body containing persona_id is treated as a persona run. The response is 202 with a run record. Poll it with Get Pathway Translation Run and stop it with Cancel Pathway Translation Run.
Limited to 10 starts per hour per organization, counted together with Migrate Pathway and Stream Pathway Migration. At most 5 pathways per job may be in translate mode, and at most 3 jobs per organization may be active at once. Requires an admin, owner, operator, or prompter role.
Headers
string
required
Your API key for authentication.
Body Parameters
Send one of the two shapes below. Ifpersona_id is present the persona shape is used and pathways is ignored.
Pathway selection
array
required
One to 20 entries, each referencing a stored pathway. Returns
400 INVALID_PATHWAYS for an empty array or a malformed entry, 400 TOO_MANY_PATHWAYS beyond 20, 400 INLINE_PATHWAY_NOT_SUPPORTED if any entry carries an inline pathway graph, and 400 TOO_MANY_TRANSLATIONS if more than 5 entries are in translate mode.Show entry fields
Show entry fields
string
required
UUID of a pathway your organization owns.
integer
Pin a specific version number (a positive integer). Defaults to the pathway’s published production version, or its live graph when nothing is published.
string
default:"one_to_one"
translate to have the planner re-architect the pathway into scenarios, or one_to_one for the deterministic conversion. Any mix is accepted within one job.string
Display name for the new agent when
create is true. Whitespace is trimmed. Defaults to the pathway’s name when exactly one pathway is given, otherwise Migrated pathways.boolean
default:"true"
When
false, the job produces scenario nodes only (returned in the run’s result.scenarios) instead of creating an agent.string
required
UUID of a persona in your organization. Its attached pathways become the job’s items and its prompts and settings become the agent shell, so a persona run always creates an agent. Returns
400 INVALID_PERSONA_ID if not a UUID, 404 PERSONA_NOT_FOUND if no such persona exists in your organization, 422 PERSONA_HAS_NO_VERSION if it has neither a published nor a draft version, 400 NO_PATHWAY_CONDITIONS if it has no attached pathways (use Migrate Persona instead), and 400 TOO_MANY_PATHWAYS if it has more than 20.string
Display name for the new agent. Defaults to the persona’s name.
array
One entry per attached pathway, in the persona’s order, each
one_to_one or translate. The length must match the persona’s pathway count or the request returns 400 INVALID_PATHWAY_MODES. Defaults to translate for every pathway. More than 5 translate entries returns 400 TOO_MANY_TRANSLATIONS.Response
Returns202 on success. Returns 429 TOO_MANY_ACTIVE_TRANSLATIONS when 3 jobs are already active for your organization.
object
The new run, always in
PENDING status.Show run object
Show run object
string
Unique identifier for the run. Pass it as
{run_id} when polling or cancelling.string
PENDING on creation. Later one of RUNNING, FINALIZING, COMPLETE, FAILED, CANCELLED.integer
Number of pathways in the job.
integer
Pathways processed so far.
0 on creation.null
Always
null until the run reaches a terminal state.string | null
null on creation.string | null
null on creation.string
ISO 8601 timestamp of when the run was created.
null
Always
null until the run reaches a terminal state.null | array
null on success, or a list of error objects if the request failed.{
"data": {
"run": {
"id": "eb732a2a-94a9-45ae-9def-ecbc56c4a5bf",
"status": "PENDING",
"total_pathways": 2,
"completed_pathways": 0,
"result": null,
"error_code": null,
"error_message": null,
"created_at": "2026-09-10T20:01:12.530Z",
"completed_at": null
}
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "TOO_MANY_TRANSLATIONS",
"message": "at most 5 pathways can be AI-translated in one job — split the selection or switch some to 1:1"
}
]
}
{
"data": null,
"errors": [
{
"error": "TOO_MANY_ACTIVE_TRANSLATIONS",
"message": "at most 3 translation jobs can run at once — wait for one to finish or cancel it"
}
]
}
{
"data": null,
"errors": [
{
"error": "TOO_MANY_REQUESTS",
"message": "Too many pathway migrations started for this organization — please wait before starting another."
}
]
}
Docs for agents: llms.txt
Was this page helpful?