From 33e25f7218baf9274942542037130c8381029dbe Mon Sep 17 00:00:00 2001 From: Peter Gomez Date: Wed, 23 Sep 2026 16:49:21 -0700 Subject: [PATCH 1/8] Add traffic splitting docs page for assistant versioning - Introduce assistants/versioning/traffic-splitting.mdx covering the theory behind splitting live call traffic across published versions - Document canary releases, experiments, staged parking at 0%, and the follow-latest default so readers understand when explicit splits pin traffic versus reverting automatically - Walk through the three publish-flow choices (100%, split, 0%) and common rollout situations: finishing a canary, rolling back, urgent fixes mid-rollout, and fair comparisons - Include a POST /traffic-allocations API example and link to GET /traffic-allocations/latest for reading the governing split - Content is intentionally theory-oriented per DEPLOY-164; no step-by-step dashboard instructions are included - Register the new page in fern/docs.yml under the versioning section OpenCode session ID: ses_f39e30a81ffeNHfgqDyd9QqtbE --- .../versioning/traffic-splitting.mdx | 83 +++++++++++++++++++ fern/docs.yml | 2 + 2 files changed, 85 insertions(+) create mode 100644 fern/assistants/versioning/traffic-splitting.mdx diff --git a/fern/assistants/versioning/traffic-splitting.mdx b/fern/assistants/versioning/traffic-splitting.mdx new file mode 100644 index 000000000..c8bb3e4d8 --- /dev/null +++ b/fern/assistants/versioning/traffic-splitting.mdx @@ -0,0 +1,83 @@ +--- +title: Traffic splitting +subtitle: Roll out assistant versions gradually with canary releases and experiments +description: Split live call traffic between published assistant versions by percentage, so you can canary a new version, run experiments, and roll back instantly. +slug: assistants/versioning/traffic-splitting +--- + +Traffic splitting routes a percentage of an assistant's live calls to each published version you choose. Instead of every call moving to a new version the moment you publish, you decide how much traffic the new version takes, watch how it behaves, and finish or cancel the rollout on your own schedule. + +## Why split traffic + +Publishing an assistant changes what every caller hears. A prompt rewrite that reads well can still greet customers the wrong way, mishandle a transfer, or regress an edge case no review caught. Traffic splitting turns that all-or-nothing moment into a controlled rollout: + +- **Canary releases**: Send a small share, such as 10%, of calls to the new version. If its calls look healthy, raise the share until it takes 100%. If they do not, remove it and the previous version takes back the traffic immediately. +- **Experiments**: Run two versions side by side at 50/50 and compare their transcripts, call outcomes, and analysis before committing to either. +- **Staged parking**: Publish a version at 0% so it exists in history and is callable by version, without routing any live traffic to it until you are ready. + +## How routing works + +- Percentages apply to **new calls** as they start; calls already in progress never switch versions. +- Calls choose a version randomly, weighted by your percentages. Repeat callers are routed to the same version when possible, so one customer does not experience two different assistants across a conversation. +- Shares are precise to **0.001%**, and a split always totals exactly 100%. +- A split names up to **5 versions**. Below three versions taking traffic, a rollout stays easy to reason about; the dashboard will nudge you before a third version starts taking traffic. + +### Follow latest, the default + +An assistant without an explicit split **follows the latest published version**: 100% of calls go to whatever you published most recently. This is the behavior you already know, and it stays in effect until you save an explicit split. Removing every version from a split returns the assistant to follow-latest. + + +An **explicit split pins its versions.** While a split is saved, publishing a new version does not move traffic to it — the split keeps routing exactly as written until you change it. Publish at 100% to both publish and return to follow-latest in one step. + + +## Splitting from the publish flow + +When you publish an assistant, the publish dialog offers three choices: + +- **Publish at 100%**: The new version takes all traffic. This is the default, and it also clears any explicit split back to follow-latest. +- **Split traffic**: The editor opens with today's routing exactly as it is and the new version on top at 0%. Give each version the share you want before publishing. +- **Publish at 0%**: Today's routing is preserved exactly as it is, and the new version is published parked at 0%. Give it a share later from the traffic editor when you are ready to start the rollout. + +A first publish must take traffic, so **Publish at 0%** becomes available from your second version onward. + +## Editing a live split + +The traffic pill in the assistant header shows where calls route right now. Select it, or the edit affordance on any version in the version history, to open the traffic editor: + +- Each edit changes only the version you touched; no other share ever moves on its own. The editor shows the running total, and you can only save when it is exactly 100%. +- Add a version and it joins with an empty share. Whenever exactly one share is empty, it hints the remainder that lands the total on 100%, so finishing a split is one glance. Removing a version frees its share for you to reassign. +- Undo steps back through your changes; Cancel discards the draft entirely. Nothing routes differently until you save. + +## Navigating common situations + +**Finishing a canary.** Raise the new version's share step by step, lowering the older version's share to match, for example 10% to 50% to 100%. At 100% you can also simply publish at 100%, which returns the assistant to follow-latest so future publishes flow normally again. + +**Rolling back a bad canary.** Set the bad version to 0%, or remove it and give its share back to the versions you trust. The change applies to new calls immediately. + +**An urgent fix during a rollout.** Remember that an explicit split pins traffic: publishing the fix does not route calls to it until you update the split. Publish at 100% if the fix should take everything, or add the fix's version to the split at the share you want. + +**Comparing versions fairly.** Give the candidates equal shares and let repeat-caller affinity keep each customer's experience consistent while the experiment runs. + +## Splitting via the API + +Every dashboard action above is a single API call. Create a traffic allocation with explicit targets to set a split, or with the follow-latest intent to restore the default: + +```json +POST /traffic-allocations +{ + "assistantId": "9d5f9d3a-...", + "allocationIntent": "explicit", + "targets": [ + { "assistantVersionId": "b7e2c1d0-...", "percentage": 90 }, + { "assistantVersionId": "4a81f622-...", "percentage": 10 } + ], + "reason": "canary: tightened refund prompt" +} +``` + +The newest allocation for an assistant is the one that governs; read it back with `GET /traffic-allocations/latest?assistantId=...`. The optional `reason` appears in history, so future readers know why a split existed. + +## Next steps + +- **[Versioning overview](/assistants/versioning):** How drafts, publishing, and restore work. +- **[Versioning assistants](/assistants/versioning/versioning-assistants):** Publishing and version history in the dashboard. diff --git a/fern/docs.yml b/fern/docs.yml index 47c2f0a9c..c0623557c 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -192,6 +192,8 @@ navigation: path: assistants/versioning/versioning-tools.mdx - page: Versioning with assistants and tools path: assistants/versioning/versioning-with-assistants-and-tools.mdx + - page: Traffic splitting + path: assistants/versioning/traffic-splitting.mdx - section: Model Intelligence icon: fa-light fa-sliders contents: From 9d5bd052908568d839cd44491458f500fd7798f0 Mon Sep 17 00:00:00 2001 From: Peter Gomez Date: Mon, 28 Sep 2026 15:19:19 -0700 Subject: [PATCH 2/8] Mark traffic splitting docs as beta - Add a Note callout stating traffic splitting is in beta and requires Vapi to enable it for the org, with a support contact for access requests - Add availability: beta to the nav entry in docs.yml so the sidebar shows the beta badge, matching the GPT-Live pattern OpenCode session ID: ses_f976655e8ffeu5QUgO73DCP9iH --- fern/assistants/versioning/traffic-splitting.mdx | 4 ++++ fern/docs.yml | 1 + 2 files changed, 5 insertions(+) diff --git a/fern/assistants/versioning/traffic-splitting.mdx b/fern/assistants/versioning/traffic-splitting.mdx index c8bb3e4d8..50c6df117 100644 --- a/fern/assistants/versioning/traffic-splitting.mdx +++ b/fern/assistants/versioning/traffic-splitting.mdx @@ -5,6 +5,10 @@ description: Split live call traffic between published assistant versions by per slug: assistants/versioning/traffic-splitting --- + +**Beta.** Traffic splitting must be enabled for your Vapi organization. Contact [support](mailto:support@vapi.ai) to request access. + + Traffic splitting routes a percentage of an assistant's live calls to each published version you choose. Instead of every call moving to a new version the moment you publish, you decide how much traffic the new version takes, watch how it behaves, and finish or cancel the rollout on your own schedule. ## Why split traffic diff --git a/fern/docs.yml b/fern/docs.yml index c0623557c..01ed8b8ba 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -194,6 +194,7 @@ navigation: path: assistants/versioning/versioning-with-assistants-and-tools.mdx - page: Traffic splitting path: assistants/versioning/traffic-splitting.mdx + availability: beta - section: Model Intelligence icon: fa-light fa-sliders contents: From 603f5dd32f1ab1780640899dece0612f1e5448e7 Mon Sep 17 00:00:00 2001 From: Peter Gomez Date: Mon, 28 Sep 2026 17:28:29 -0700 Subject: [PATCH 3/8] Update traffic-splitting API examples to new contract - Reference published versions by label (e.g. "v7") instead of assistantVersionId, matching how version routes already work - Rename reason to description in the request body - Drop explicit allocationIntent for splits; it's inferred from the presence of targets, so posting targets alone starts or adjusts a canary while follow-latest stays the one explicit intent needed to stop a rollout - Add start/adjust/stop worked examples plus expectedCurrentAllocationId guidance for optimistic concurrency, and document GET history endpoint alongside the existing latest-allocation read OpenCode session ID: ses_f976655e8ffeu5QUgO73DCP9iH --- .../versioning/traffic-splitting.mdx | 38 ++++++++++++++++--- 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/fern/assistants/versioning/traffic-splitting.mdx b/fern/assistants/versioning/traffic-splitting.mdx index 50c6df117..a6f7912a9 100644 --- a/fern/assistants/versioning/traffic-splitting.mdx +++ b/fern/assistants/versioning/traffic-splitting.mdx @@ -64,22 +64,48 @@ The traffic pill in the assistant header shows where calls route right now. Sele ## Splitting via the API -Every dashboard action above is a single API call. Create a traffic allocation with explicit targets to set a split, or with the follow-latest intent to restore the default: +Every dashboard action above is a single API call. Versions are named by their label, such as `"v7"`, the same label the version routes use. Targets must be published versions of the assistant, so publish first, then allocate. + +**Start a canary** by posting the split you want. Sending `targets` is enough; the intent is understood to be an explicit split: ```json POST /traffic-allocations { "assistantId": "9d5f9d3a-...", - "allocationIntent": "explicit", "targets": [ - { "assistantVersionId": "b7e2c1d0-...", "percentage": 90 }, - { "assistantVersionId": "4a81f622-...", "percentage": 10 } + { "assistantVersion": "v6", "percentage": 90 }, + { "assistantVersion": "v7", "percentage": 10 } ], - "reason": "canary: tightened refund prompt" + "description": "canary: tightened refund prompt" +} +``` + +**Adjust it** the same way: post the whole new split. The most recently created allocation is the one in effect, so each post replaces the last: + +```json +POST /traffic-allocations +{ + "assistantId": "9d5f9d3a-...", + "targets": [ + { "assistantVersion": "v6", "percentage": 50 }, + { "assistantVersion": "v7", "percentage": 50 } + ] +} +``` + +If concurrent editors are a concern, include `"expectedCurrentAllocationId"` with the allocation id you last read; the write then applies only while that allocation is still in effect, and conflicts return a 409 instead of letting the last write win. + +**Stop splitting** by saying so. Ending a split is the one request that must name its intent, so a dropped `targets` field can never end a rollout by accident: + +```json +POST /traffic-allocations +{ + "assistantId": "9d5f9d3a-...", + "allocationIntent": "follow-latest" } ``` -The newest allocation for an assistant is the one that governs; read it back with `GET /traffic-allocations/latest?assistantId=...`. The optional `reason` appears in history, so future readers know why a split existed. +Read the split currently in effect with `GET /traffic-allocations/latest?assistantId=...`, and the full history with `GET /traffic-allocations?assistantId=...`. The optional `description` appears in history, so future readers know why a split existed. ## Next steps From 857e4cc856c0a508d4b5a62e4479331911d7ef6e Mon Sep 17 00:00:00 2001 From: Peter Gomez Date: Mon, 28 Sep 2026 17:59:30 -0700 Subject: [PATCH 4/8] Clarify traffic splitting beta scope in note Expand the beta callout on the traffic splitting doc to spell out what's included and excluded: - Included: percentage splits, sticky routing, dashboard editor, API with allocation change history - Excluded: per-version call metrics, side-by-side comparisons, and a dashboard view of past splits - Point users to the `assistantVersion` field on calls as the current workaround for comparing versions OpenCode session ID: ses_f976655e8ffeu5QUgO73DCP9iH --- fern/assistants/versioning/traffic-splitting.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/fern/assistants/versioning/traffic-splitting.mdx b/fern/assistants/versioning/traffic-splitting.mdx index a6f7912a9..cf5806aa2 100644 --- a/fern/assistants/versioning/traffic-splitting.mdx +++ b/fern/assistants/versioning/traffic-splitting.mdx @@ -7,6 +7,8 @@ slug: assistants/versioning/traffic-splitting **Beta.** Traffic splitting must be enabled for your Vapi organization. Contact [support](mailto:support@vapi.ai) to request access. + +The beta includes percentage splits across published versions, sticky routing for repeat callers, the dashboard traffic editor, and the API, which also returns the full history of allocation changes. It does not yet include per-version call metrics, side-by-side version comparisons, or a dashboard view of past splits. To compare versions today, use each call's `assistantVersion` field, which records the version that handled the call and is also a column in call exports. Traffic splitting routes a percentage of an assistant's live calls to each published version you choose. Instead of every call moving to a new version the moment you publish, you decide how much traffic the new version takes, watch how it behaves, and finish or cancel the rollout on your own schedule. From ec059f9f2d5c31f655a22372239ae121e0495969 Mon Sep 17 00:00:00 2001 From: Peter Gomez Date: Mon, 28 Sep 2026 18:11:15 -0700 Subject: [PATCH 5/8] Replace support email with beta access form link - Traffic splitting beta access now goes through a Google Form instead of emailing support@vapi.ai - Streamlines intake for the beta program OpenCode session ID: ses_f976655e8ffeu5QUgO73DCP9iH --- fern/assistants/versioning/traffic-splitting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/assistants/versioning/traffic-splitting.mdx b/fern/assistants/versioning/traffic-splitting.mdx index cf5806aa2..ba63475aa 100644 --- a/fern/assistants/versioning/traffic-splitting.mdx +++ b/fern/assistants/versioning/traffic-splitting.mdx @@ -6,7 +6,7 @@ slug: assistants/versioning/traffic-splitting --- -**Beta.** Traffic splitting must be enabled for your Vapi organization. Contact [support](mailto:support@vapi.ai) to request access. +**Beta.** Traffic splitting must be enabled for your Vapi organization. Request access through the [beta access form](https://docs.google.com/forms/d/e/1FAIpQLSdGTb3CMjYvEHoZR1cUq4_5YavRe9AT-gtKTKPKE8NWAxH-nA/viewform). The beta includes percentage splits across published versions, sticky routing for repeat callers, the dashboard traffic editor, and the API, which also returns the full history of allocation changes. It does not yet include per-version call metrics, side-by-side version comparisons, or a dashboard view of past splits. To compare versions today, use each call's `assistantVersion` field, which records the version that handled the call and is also a column in call exports. From 81c64c65857d9c28a9fd639755b1bd9da3aff5ed Mon Sep 17 00:00:00 2001 From: Peter Gomez Date: Mon, 28 Sep 2026 18:12:24 -0700 Subject: [PATCH 6/8] Update beta access form link for traffic splitting - Replaced the long Google Forms URL with the forms.gle short link - Keeps the docs link shorter and easier to read/maintain OpenCode session ID: ses_f976655e8ffeu5QUgO73DCP9iH --- fern/assistants/versioning/traffic-splitting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/assistants/versioning/traffic-splitting.mdx b/fern/assistants/versioning/traffic-splitting.mdx index ba63475aa..9f9b36f96 100644 --- a/fern/assistants/versioning/traffic-splitting.mdx +++ b/fern/assistants/versioning/traffic-splitting.mdx @@ -6,7 +6,7 @@ slug: assistants/versioning/traffic-splitting --- -**Beta.** Traffic splitting must be enabled for your Vapi organization. Request access through the [beta access form](https://docs.google.com/forms/d/e/1FAIpQLSdGTb3CMjYvEHoZR1cUq4_5YavRe9AT-gtKTKPKE8NWAxH-nA/viewform). +**Beta.** Traffic splitting must be enabled for your Vapi organization. Request access through the [beta access form](https://forms.gle/6EfEcCFxvxJTZHDs8). The beta includes percentage splits across published versions, sticky routing for repeat callers, the dashboard traffic editor, and the API, which also returns the full history of allocation changes. It does not yet include per-version call metrics, side-by-side version comparisons, or a dashboard view of past splits. To compare versions today, use each call's `assistantVersion` field, which records the version that handled the call and is also a column in call exports. From c54fd2236eb8e27f7287014e12a6668ec0907717 Mon Sep 17 00:00:00 2001 From: Peter Gomez Date: Mon, 28 Sep 2026 18:18:58 -0700 Subject: [PATCH 7/8] Document sticky routing caveats and split validation rules - Add a "Sticky routing is best effort" section explaining that stickiness is keyed on phone number or SIP username, so web calls, withheld caller IDs, and non-phone-number identifiers route independently each time. - Note that stickiness also depends on target order, so reordering versions in a split can move repeat callers to a different version. - Document the API validation rule: a split is only accepted when every version is listed once and percentages total exactly 100 with at least one above 0, otherwise the request returns a 400. OpenCode session ID: ses_f976655e8ffeu5QUgO73DCP9iH --- fern/assistants/versioning/traffic-splitting.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/fern/assistants/versioning/traffic-splitting.mdx b/fern/assistants/versioning/traffic-splitting.mdx index 9f9b36f96..791efd3d5 100644 --- a/fern/assistants/versioning/traffic-splitting.mdx +++ b/fern/assistants/versioning/traffic-splitting.mdx @@ -24,10 +24,16 @@ Publishing an assistant changes what every caller hears. A prompt rewrite that r ## How routing works - Percentages apply to **new calls** as they start; calls already in progress never switch versions. -- Calls choose a version randomly, weighted by your percentages. Repeat callers are routed to the same version when possible, so one customer does not experience two different assistants across a conversation. +- Calls choose a version randomly, weighted by your percentages. Repeat callers are routed to the same version when possible; see [sticky routing](#sticky-routing-is-best-effort). - Shares are precise to **0.001%**, and a split always totals exactly 100%. - A split names up to **5 versions**. Below three versions taking traffic, a rollout stays easy to reason about; the dashboard will nudge you before a third version starts taking traffic. +### Sticky routing is best effort + +A caller who calls back usually reaches the same version, because the choice is keyed on the caller's phone number, or on the SIP username for SIP calls. Calls without one of those are routed independently each time, so a repeat caller can reach a different version. This includes web calls, callers who withhold their number, and caller IDs that are not phone numbers. + +Stickiness also depends on target order. Keep listing versions in the same order across updates, and ramp by growing a later version's share at the expense of an earlier one; reordering targets can move repeat callers to a different version. + ### Follow latest, the default An assistant without an explicit split **follows the latest published version**: 100% of calls go to whatever you published most recently. This is the behavior you already know, and it stays in effect until you save an explicit split. Removing every version from a split returns the assistant to follow-latest. @@ -66,7 +72,7 @@ The traffic pill in the assistant header shows where calls route right now. Sele ## Splitting via the API -Every dashboard action above is a single API call. Versions are named by their label, such as `"v7"`, the same label the version routes use. Targets must be published versions of the assistant, so publish first, then allocate. +Every dashboard action above is a single API call. Versions are named by their label, such as `"v7"`, the same label the version routes use. Targets must be published versions of the assistant, so publish first, then allocate. A split is accepted when every version is listed once and the percentages total exactly 100, with at least one above 0; otherwise the request returns a 400. Keep targets in the same order from one request to the next so repeat callers stay on their version. **Start a canary** by posting the split you want. Sending `targets` is enough; the intent is understood to be an explicit split: From 06a986ae58f1c17adc9da634079d07c90aac05ff Mon Sep 17 00:00:00 2001 From: Peter Gomez Date: Tue, 29 Sep 2026 14:14:53 -0700 Subject: [PATCH 8/8] Tidy up wording on traffic splitting doc Apply six reviewer-suggested phrasing tweaks across the page: - Simplify the regression clause in the "why split traffic" intro - Plainer phrasing for the canary bullet's ramp/rollback language - Reword sticky routing explanation for readability - Clarify "traffic pill" description in the editing section - Streamline "finishing a canary" walkthrough - Simplify API section's version label sentence No behavior or meaning changes, just clearer wording per review feedback. OpenCode session ID: ses_f976655e8ffeu5QUgO73DCP9iH --- fern/assistants/versioning/traffic-splitting.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/fern/assistants/versioning/traffic-splitting.mdx b/fern/assistants/versioning/traffic-splitting.mdx index 791efd3d5..fa766b0fb 100644 --- a/fern/assistants/versioning/traffic-splitting.mdx +++ b/fern/assistants/versioning/traffic-splitting.mdx @@ -15,9 +15,9 @@ Traffic splitting routes a percentage of an assistant's live calls to each publi ## Why split traffic -Publishing an assistant changes what every caller hears. A prompt rewrite that reads well can still greet customers the wrong way, mishandle a transfer, or regress an edge case no review caught. Traffic splitting turns that all-or-nothing moment into a controlled rollout: +Publishing an assistant changes what every caller hears. A prompt rewrite that reads well can still greet customers the wrong way, mishandle a transfer, or cause regressions in edge cases that review missed. Traffic splitting turns that all-or-nothing moment into a controlled rollout: -- **Canary releases**: Send a small share, such as 10%, of calls to the new version. If its calls look healthy, raise the share until it takes 100%. If they do not, remove it and the previous version takes back the traffic immediately. +- **Canary releases**: Send a small share, such as 10%, of calls to the new version. If its calls look healthy, gradually raise the share to 100%. If they do not, remove it so the previous version immediately takes back the traffic. - **Experiments**: Run two versions side by side at 50/50 and compare their transcripts, call outcomes, and analysis before committing to either. - **Staged parking**: Publish a version at 0% so it exists in history and is callable by version, without routing any live traffic to it until you are ready. @@ -30,7 +30,7 @@ Publishing an assistant changes what every caller hears. A prompt rewrite that r ### Sticky routing is best effort -A caller who calls back usually reaches the same version, because the choice is keyed on the caller's phone number, or on the SIP username for SIP calls. Calls without one of those are routed independently each time, so a repeat caller can reach a different version. This includes web calls, callers who withhold their number, and caller IDs that are not phone numbers. +Repeat callers usually reach the same version because routing uses the caller's phone number or, for SIP calls, the SIP username. Calls without either identifier are routed independently each time, so a repeat caller might reach a different version. This includes web calls, calls from people who withhold their number, and calls with caller IDs that are not phone numbers. Stickiness also depends on target order. Keep listing versions in the same order across updates, and ramp by growing a later version's share at the expense of an earlier one; reordering targets can move repeat callers to a different version. @@ -54,7 +54,7 @@ A first publish must take traffic, so **Publish at 0%** becomes available from y ## Editing a live split -The traffic pill in the assistant header shows where calls route right now. Select it, or the edit affordance on any version in the version history, to open the traffic editor: +The traffic pill in the assistant header shows where calls route now. Select the pill or the edit control for a version in version history to open the traffic editor: - Each edit changes only the version you touched; no other share ever moves on its own. The editor shows the running total, and you can only save when it is exactly 100%. - Add a version and it joins with an empty share. Whenever exactly one share is empty, it hints the remainder that lands the total on 100%, so finishing a split is one glance. Removing a version frees its share for you to reassign. @@ -62,7 +62,7 @@ The traffic pill in the assistant header shows where calls route right now. Sele ## Navigating common situations -**Finishing a canary.** Raise the new version's share step by step, lowering the older version's share to match, for example 10% to 50% to 100%. At 100% you can also simply publish at 100%, which returns the assistant to follow-latest so future publishes flow normally again. +**Finishing a canary.** Raise the new version's share gradually and lower the older version's share to match. For example, increase it from 10% to 50%, then to 100%. You can also publish at 100% to return the assistant to follow-latest for future publishes. **Rolling back a bad canary.** Set the bad version to 0%, or remove it and give its share back to the versions you trust. The change applies to new calls immediately. @@ -72,7 +72,7 @@ The traffic pill in the assistant header shows where calls route right now. Sele ## Splitting via the API -Every dashboard action above is a single API call. Versions are named by their label, such as `"v7"`, the same label the version routes use. Targets must be published versions of the assistant, so publish first, then allocate. A split is accepted when every version is listed once and the percentages total exactly 100, with at least one above 0; otherwise the request returns a 400. Keep targets in the same order from one request to the next so repeat callers stay on their version. +Every dashboard action above is a single API call. Targets use the version label, such as `"v7"`, that the version routes use. Targets must be published versions of the assistant, so publish first, then allocate. A split is accepted when every version is listed once and the percentages total exactly 100, with at least one above 0; otherwise the request returns a 400. Keep targets in the same order from one request to the next so repeat callers stay on their version. **Start a canary** by posting the split you want. Sending `targets` is enough; the intent is understood to be an explicit split: