Skip to main content
PUT
Set Migration Split
Creates or replaces the migration split on a V1 pathway. A split sends v2_percentage percent of the pathway’s traffic to a V2 agent, which runs its production version. The rest runs on the pathway exactly as before. Your requests and phone numbers keep naming the pathway. A pathway has at most one split, so a PUT to a pathway that already has one replaces its agent and share. Changes apply from the next call. Set v2_percentage to 0 to roll back. A rollback skips every agent check below and is accepted while a rollout is running. To remove the split entirely, use Delete Migration Split. For a walkthrough, see Migrate an API integration without changing its request. Requires an admin, owner, or operator role. This endpoint doesn’t require an enterprise plan. Staged rollouts with ramps and guardrails, which the dashboard runs on top of a split, do.

What the split routes

The split applies to this traffic on the pathway:
  • Inbound calls to numbers bound directly to the pathway. A number that reaches the pathway through a persona is not split.
  • Send Call requests made with an organization API key that set pathway_id and set neither persona_id nor agent_id.
  • New text conversations started with Send SMS Message and an organization API key, on the request’s pathway_id or, without one, the number’s pathway. A request or number with a persona is not split, and a conversation that is already active stays where it is. Conversations that start with an inbound text are not split.
Each call is decided independently, unless a rollout assigns each caller a fixed side. A contact who texts again gets the same side as before while the percentage is unchanged. Traffic stays on the pathway when:
  • The agent’s calls channel (or messages channel, for texts) is turned off.
  • Bland can’t prepare the agent for that call. Under agent_owned, the request’s removed fields are put back first, so the call runs on the pathway as the request was sent.
  • Under honor, a Send Call request sets pathway_version in the body or query, or a Send SMS Message request sets pathway_version or start_node_id.
V1 citation schemas and disposition_ids don’t run on a call that the split sends to the agent. Send Call requests the split sends to the agent can enter the agent’s experiments only while the split is at 100% and no rollout drives it. Inbound calls the split sends to the agent never do. While a pathway has a split, at any percentage, its directly bound numbers can’t be attached to an agent or a persona: Attach Numbers to Agent and Attach Phone Numbers to Persona return 409 MIGRATION_EXPERIMENT_NUMBER. A number attached to an agent no longer belongs to the pathway, so the split never routes its calls.
Deleting the pathway or the agent deletes the split. If your integration keeps sending the pathway’s ID, keep the pathway.

Headers

string
required
Your API key for authentication.
string
required
Must be application/json.

Path Parameters

string
required
The V1 pathway to split. Must be a UUID of a pathway in your organization. Returns 400 BAD_REQUEST for an invalid UUID, 404 NOT_FOUND for a pathway outside your organization, and 400 BAD_REQUEST for a pathway that Bland compiled from a V2 agent.

Body Parameters

string
required
The V2 agent that receives the split traffic. Must be a UUID. When v2_percentage is above 0, the request also checks the following:
  • 404 NOT_FOUND if the agent isn’t in your organization.
  • 409 FLEET_NOT_ELIGIBLE if your organization runs on dedicated infrastructure that can’t run V2 agents yet. Organizations on Bland’s shared infrastructure always pass this check.
  • 400 BAD_REQUEST if the agent can’t serve calls on its production version. The message names the cause, such as AGENT_ENV_UNPINNED when nothing is promoted to production.
integer
required
Percentage of the pathway’s traffic sent to the agent, 0 to 100. Returns 400 BAD_REQUEST for any other value.While a rollout is moving this pathway’s share (rollout_id is set on Get Migration Split), a value above 0 returns 409 ROLLOUT_IN_PROGRESS. Change the share from the rollout, or set 0 to roll back, which ends the rollout. A 409 CONFLICT means a rollout change to the agent was in progress and nothing was written. Retry it.
string
Which values win on a Send Call request that the split sends to the agent: honor or agent_owned. Omit it to keep an existing split’s policy. A new split without it starts on honor. Any other value returns 400 BAD_REQUEST. The policy also decides whether a Send SMS Message request that sets pathway_version or start_node_id can be routed (only under agent_owned). Inbound calls aren’t affected by this setting.
  • honor: The request’s values win. The agent fills in only the settings that the request leaves out. A request with pathway_version stays on the pathway.
  • agent_owned: Bland removes these request fields so the agent’s settings apply: voice, interruption_threshold, language, keywords, pronunciation_guide, agent_backchannel_level, agent_backchannel_config, wait_for_greeting, max_duration, noise_cancellation, ignore_button_press, record, background_track, interruptibility, block_interruptions, voicemail, voicemail_action, voicemail_message, voicemail_sms, sensitive_voicemail_detection, amd, ivr_mode, pathway_version, start_node_id, citation_schema_id, citation_schema_ids, and disposition_ids. Fields such as phone_number, from, timezone, webhook, metadata, and request_data still come from the request.
To change only the policy, use Update Migration Split Request Policy.

Response

object
The split as saved.
null | array
null on success, or a list of error objects if the request failed. Returns 409 SOURCE_CHANGED and writes nothing if a number bound to the pathway changed while the request ran, for example because another request attached it to an agent. Retry it.
Docs for agents: llms.txt