From 1c191e551f9ba4e7694d4a9bc5e450f11b59f9cb Mon Sep 17 00:00:00 2001 From: Stephen Smith Date: Fri, 9 Oct 2026 11:59:06 -0700 Subject: [PATCH 1/2] Updated the directions and added links --- .../versioning/versioning-assistants.mdx | 4 +- .../versioning-with-squads-and-assistants.mdx | 241 ++++++++++++++---- fern/squads-example.mdx | 2 + fern/squads.mdx | 2 + fern/squads/handoff/destinations.mdx | 2 +- 5 files changed, 197 insertions(+), 54 deletions(-) diff --git a/fern/assistants/versioning/versioning-assistants.mdx b/fern/assistants/versioning/versioning-assistants.mdx index 21515d427..600b684ab 100644 --- a/fern/assistants/versioning/versioning-assistants.mdx +++ b/fern/assistants/versioning/versioning-assistants.mdx @@ -37,7 +37,7 @@ Publishing turns your current draft into a new version and makes it the **curren - Make changes to the assistant. Vapi saves your edits automatically as a draft. The changes do not affect live calls. + In the [Dashboard](https://dashboard.vapi.ai), select **Assistants** in the sidebar and open the assistant. Make changes in the editor. Vapi saves your edits automatically as a draft. The changes do not affect live calls. Select **Publish** to compare the draft with the current published version. In the diff, you can copy individual lines, wrap long lines, move between changes, or copy the complete diff. @@ -66,7 +66,7 @@ Publishing turns your current draft into a new version and makes it the **curren ## View version history -Open the version menu in the assistant header to see recent versions. Select **View Full History** to see all versions. The current published version is marked **Current**. Each version includes its version number, name, description, and publication time. +In the [Dashboard](https://dashboard.vapi.ai), select **Assistants** in the sidebar and open the assistant. Select the version number below its name to see recent versions, then **View Full History** to see all versions. The current published version is marked **Current**. Each version includes its version number, name, description, and publication time. - - Open the [Dashboard](https://dashboard.vapi.ai), select **Squads**, and change the squad. - - - Select **Save**. Vapi creates the next version and makes it current. - - - -Through the API, each [create squad](/api-reference/squads/create) or [update squad](/api-reference/squads/update) request that changes the configuration creates a version. +Create a squad to make `v1`. Later changes to its configuration create the next version when you save them. + + + + + + In the [Dashboard](https://dashboard.vapi.ai), select **Squads** in the sidebar, then **New Squad**. In **Build your Squad**, enter a name, choose a published assistant under **Add your first member**, and select **New Squad**. This creates `v1`. + + + Open the squad from **Squads**, change its configuration in the builder, and select **Save** in the upper-right corner. This creates the next version and makes it current. + + + + + + + + ```bash + export VAPI_API_KEY="YOUR_VAPI_PRIVATE_KEY" + ``` + + + Replace the assistant IDs with IDs of saved assistants. The [create squad request](/api-reference/squads/create) creates `v1`. + + ```bash + curl --request POST \ + --url https://api.vapi.ai/squad \ + --header "Authorization: Bearer $VAPI_API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "Support squad", + "members": [ + { "assistantId": "YOUR_TRIAGE_ASSISTANT_ID" }, + { "assistantId": "YOUR_BILLING_ASSISTANT_ID" } + ] + }' + ``` + + Save the returned `id` as `SQUAD_ID` for the next request. + + + This [update squad request](/api-reference/squads/update) changes the name of the squad you just created. Include its complete `members` array. The change creates `v2` and makes it current. + + ```bash + export SQUAD_ID="ID_FROM_CREATE_RESPONSE" + + curl --request PATCH \ + --url "https://api.vapi.ai/squad/$SQUAD_ID" \ + --header "Authorization: Bearer $VAPI_API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "Customer support squad", + "members": [ + { "assistantId": "YOUR_TRIAGE_ASSISTANT_ID" }, + { "assistantId": "YOUR_BILLING_ASSISTANT_ID" } + ] + }' + ``` + + + + ## View version history - - - Select the version number in the squad header to see recent versions. The current version is marked **Current**. - - - Select **View full history** to see every version and when it was saved. - - - Select a version to see its details, or select the download icon to export it as JSON. - - +Review the saved configuration of a squad version in the Dashboard or through the API. The Dashboard shows which version is **Current**, but does not offer a control to make an earlier version current. + + + + + + In the [Dashboard](https://dashboard.vapi.ai), select **Squads** in the sidebar and open the squad. Select the version chip below the squad name to see recent versions. The newest version is marked **Current**. + + + Select **View full history** to see every version and when it was saved. + + + In the history panel, select a version row to see its details. To download that version's JSON, hover over the row and select the download icon (**Export JSON**). The file contains that version's label, creation time, and saved squad configuration. + + + + + + + + ```bash + export VAPI_API_KEY="YOUR_VAPI_PRIVATE_KEY" + export SQUAD_ID="YOUR_SQUAD_ID" + ``` + + + ```bash + curl --request GET \ + --url "https://api.vapi.ai/squad/$SQUAD_ID/versions" \ + --header "Authorization: Bearer $VAPI_API_KEY" + ``` + + The response contains `results` and pagination `metadata`. Use `metadata.nextCursor` to request the next page when `metadata.hasNextPage` is `true`. + + + Replace `v2` with the version you want to inspect. + + ```bash + curl --request GET \ + --url "https://api.vapi.ai/squad/$SQUAD_ID/versions/v2" \ + --header "Authorization: Bearer $VAPI_API_KEY" + ``` + + The response includes the saved `members`, version label, and creation time. It also includes `membersOverrides` when the squad has them. To save the response as JSON, add `--output squad-version-v2.json` to the command. + + + + ## Pin a member's assistant version @@ -70,6 +159,8 @@ Each member that uses a saved assistant has one of two settings: - **Latest**: The member uses the assistant's current published version when each call starts. This is the default. - **Pinned version**, such as **v3**: The member always uses that assistant version. +To publish or review an assistant version before pinning it, see [Versioning with assistants](/assistants/versioning/versioning-assistants). + A squad version saves each member's setting, not the assistant's configuration. When an assistant publishes a new version, the squad version stays the same: - Members set to **Latest** use the new assistant version on the next call. @@ -85,30 +176,61 @@ For example, squad **v1** has assistant A pinned to **v5** and assistant B set t Squads pin assistant versions. Each assistant version keeps its own [tool version selections](/assistants/versioning/versioning-with-assistants-and-tools), so a pinned member uses the tool versions saved with that assistant version. -To pin a member in the Dashboard: - - - - Open the squad in the [Dashboard](https://dashboard.vapi.ai) and select the member. - - - Choose **Latest** or a numbered version from the menu next to the member's name. - - - Select **Save** to create a new squad version with the selection. - - - -Through the API, set `assistantVersion` next to `assistantId` on the member. Omit `assistantVersion` to use **Latest**. - -```json -{ - "members": [ - { "assistantId": "triage-assistant-id", "assistantVersion": "v3" }, - { "assistantId": "billing-assistant-id" } - ] -} -``` +Set `assistantVersion` on a saved assistant member to pin it. Omit the field to use **Latest**. + + + + + + In the [Dashboard](https://dashboard.vapi.ai), select **Squads** in the sidebar and open the squad. Select the assistant member on the builder canvas to open its settings panel. + + + In the panel header, select the **Latest** or numbered version menu next to the member's name. Choose **Use latest version** or the published version you want to pin. + + + Select **Save** in the upper-right corner to create a new squad version with the selection. + + + + + + + + ```bash + export VAPI_API_KEY="YOUR_VAPI_PRIVATE_KEY" + export SQUAD_ID="YOUR_SQUAD_ID" + ``` + + + ```bash + curl --request GET \ + --url "https://api.vapi.ai/squad/$SQUAD_ID" \ + --header "Authorization: Bearer $VAPI_API_KEY" + ``` + + Copy the complete `members` array from the response. Keep the current order and any `assistantOverrides` for each member. + + + Include every current member in the [update squad request](/api-reference/squads/update). Set `assistantVersion` to a published version for the member you want to pin. Omit it for a member that should use **Latest**. + + ```bash + curl --request PATCH \ + --url "https://api.vapi.ai/squad/$SQUAD_ID" \ + --header "Authorization: Bearer $VAPI_API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "members": [ + { "assistantId": "YOUR_TRIAGE_ASSISTANT_ID", "assistantVersion": "v3" }, + { "assistantId": "YOUR_BILLING_ASSISTANT_ID" } + ] + }' + ``` + + Replace the example `members` array with your complete current roster before sending the request. The changed pin creates a new squad version. + + + + To make a squad version run the same configuration every time, pin each member, and pin the tools inside each of those assistant versions. A tool set to **Latest** in an assistant version uses the tool's newest published version. @@ -119,7 +241,24 @@ To make a squad version run the same configuration every time, pin each member, - **Inbound calls** use the squad's current version. - **Outbound calls** use the current version by default. To use a specific version, pass `squadVersion` with `squadId` in the [create call request](/api-reference/calls/create). -When a call uses an earlier squad version, it runs the squad as it was saved in that version: the same members, member overrides, and pinned assistant versions. Members set to **Latest** are the exception. They use each assistant's current published version, not the version that was current when you saved the squad version. +When a call uses an earlier squad version, it runs the squad as it was saved in that version: the same members, member overrides, and pinned assistant versions. Members set to **Latest** are the exception. They use each assistant's [current published version](/assistants/versioning/versioning-assistants), not the version that was current when you saved the squad version. + +To select a squad version for an outbound call, pass its version label with the saved squad's ID. Replace the phone number and IDs with your own values. + +```bash +export VAPI_API_KEY="YOUR_VAPI_PRIVATE_KEY" + +curl --request POST \ + --url https://api.vapi.ai/call \ + --header "Authorization: Bearer $VAPI_API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "squadId": "YOUR_SQUAD_ID", + "squadVersion": "v2", + "phoneNumberId": "YOUR_PHONE_NUMBER_ID", + "customer": { "number": "+14155550100" } + }' +``` ## Next steps diff --git a/fern/squads-example.mdx b/fern/squads-example.mdx index afe87c12f..c0ed5e44e 100644 --- a/fern/squads-example.mdx +++ b/fern/squads-example.mdx @@ -97,3 +97,5 @@ To initiate an outbound call, send a POST request to the API endpoint /call/phon * `customer.number` is the phone number to call. * `phoneNumberId` is a unique identifier for the phone number (obtain this from your provider). + +To create versions of a saved squad, pin its members to assistant versions, or select a squad version for an outbound call, see [Squad versioning](/assistants/versioning/versioning-with-squads). diff --git a/fern/squads.mdx b/fern/squads.mdx index fa58b63af..6a3fb06ca 100644 --- a/fern/squads.mdx +++ b/fern/squads.mdx @@ -7,6 +7,8 @@ description: Break complex workflows into multiple specialized Vapi assistants t Squads let you break complex workflows into multiple specialized assistants that hand off to each other during a conversation. Each assistant in a Squad handles a specific part of your workflow; for example, one assistant for lead qualification that transfers to another for appointment booking. +For saved squads, [squad versioning](/assistants/versioning/versioning-with-squads) tracks configuration changes and explains how to pin members to assistant versions or select a squad version for an outbound call. + If you're designing a Squad with an AI coding assistant, the [create-squad skill](/agent-skills#create-squad) helps you plan members and handoffs, then create and verify the configuration. **Why use Squads?** Large, all-in-one assistants with lengthy prompts and extensive context lead to: diff --git a/fern/squads/handoff/destinations.mdx b/fern/squads/handoff/destinations.mdx index 056b93522..e75cb6c2d 100644 --- a/fern/squads/handoff/destinations.mdx +++ b/fern/squads/handoff/destinations.mdx @@ -271,7 +271,7 @@ In addition to assistant and dynamic destinations, you can hand off a call to an ### Using squad ID -Reference a saved squad by its ID: +Reference a saved squad by its ID. To save changes to that squad or review its versions, see [squad versioning](/assistants/versioning/versioning-with-squads). ```json { From 2cc9cdeab95aeb9d496a1d0ec581c5088d681795 Mon Sep 17 00:00:00 2001 From: Stephen Smith Date: Fri, 9 Oct 2026 12:04:02 -0700 Subject: [PATCH 2/2] Made some edits --- .../versioning/versioning-with-squads-and-assistants.mdx | 4 +++- fern/squads-example.mdx | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/fern/assistants/versioning/versioning-with-squads-and-assistants.mdx b/fern/assistants/versioning/versioning-with-squads-and-assistants.mdx index aa7ca9db9..954356b00 100644 --- a/fern/assistants/versioning/versioning-with-squads-and-assistants.mdx +++ b/fern/assistants/versioning/versioning-with-squads-and-assistants.mdx @@ -7,7 +7,9 @@ slug: assistants/versioning/versioning-with-squads ## How squad versioning works -When you save a changed [squad](/squads) configuration, Vapi creates the next numbered version and marks it **Current**. Saving without a configuration change does not create another version. Versions are numbered `v1`, `v2`, and so on. Calls use the current version by default, and outbound calls can specify an earlier version without changing which version is current. +When you save a changed [squad](/squads) configuration, Vapi creates the next numbered version and marks it **Current**. Saving without a configuration change does not create another version. Versions are numbered `v1`, `v2`, and so on. + +Calls use the current version by default. An outbound call can specify an earlier version without changing which version is current. A squad version saves the squad's configuration: diff --git a/fern/squads-example.mdx b/fern/squads-example.mdx index c0ed5e44e..49259b222 100644 --- a/fern/squads-example.mdx +++ b/fern/squads-example.mdx @@ -98,4 +98,4 @@ To initiate an outbound call, send a POST request to the API endpoint /call/phon * `customer.number` is the phone number to call. * `phoneNumberId` is a unique identifier for the phone number (obtain this from your provider). -To create versions of a saved squad, pin its members to assistant versions, or select a squad version for an outbound call, see [Squad versioning](/assistants/versioning/versioning-with-squads). +The examples above define a squad inline for each call. To create versions of a saved squad, pin its members to assistant versions, or select a squad version for an outbound call, see [Squad versioning](/assistants/versioning/versioning-with-squads).