Skip to content

Versioning with squads follow up #1305

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
amanda-vapi merged 2 commits into from
Oct 9, 2026
+199 −54
Merged

Versioning with squads follow up #1305

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1c191e5
Updated the directions and added links
stephenvapiai Oct 9, 2026
2cc9cde
Made some edits
stephenvapiai Oct 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions fern/assistants/versioning/versioning-assistants.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Publishing turns your current draft into a new version and makes it the **curren

<Steps>
<Step title="Edit your draft">
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.
</Step>
<Step title="Review the changes">
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.
Expand Down Expand Up @@ -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.

<Frame caption="View the assistant's published versions in the version history.">
<img
Expand Down
243 changes: 192 additions & 51 deletions fern/assistants/versioning/versioning-with-squads-and-assistants.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,9 @@ slug: assistants/versioning/versioning-with-squads

## How squad versioning works

Squad versioning saves a numbered version of a [squad](/squads) each time you change it, so you can review how the squad evolved as you build it and use a specific version on a call. Versions are numbered `v1`, `v2`, and so on. The newest version is **current**, and new calls use it.
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:

Expand All @@ -27,41 +29,130 @@ The assistant's own configuration, including its tools, belongs to the [assistan
| Change | Creates a squad version? |
| --- | --- |
| You create a squad | Yes, `v1` |
| You add or remove a member and save | Yes |
| You pin a member to an assistant version, change the pin, or set it back to **Latest**, and save | Yes |
| You create member overrides by changing a member's tools, model, handoffs, or other settings in the squad builder and save | Yes |
| You add or remove a member and save the squad | Yes |
| You pin a member to an assistant version, change the pin, or set it back to **Latest**, and save the squad | Yes |
| You create member overrides by changing a member's tools, model, handoffs, or other settings in the squad builder and save the squad | Yes |
| You edit an assistant's draft, such as its tools, prompt, or model, in the assistant editor | No |
| An assistant in the squad publishes or restores a version, including changes to its tools | No |
| A tool used by an assistant in the squad publishes a version | No |

A squad that existed before squad versioning was enabled for your organization gets its first versions the next time you save it: the existing configuration becomes `v1` and your changes become `v2`.
A squad that existed before squad versioning was enabled for your organization gets its first versions the next time you save a change: the existing configuration becomes `v1` and your changes become `v2`.

## Create a version

<Steps>
<Step title="Edit the squad">
Open the [Dashboard](https://dashboard.vapi.ai), select **Squads**, and change the squad.
</Step>
<Step title="Save">
Select **Save**. Vapi creates the next version and makes it current.
</Step>
</Steps>

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.

<Tabs>
<Tab title="Dashboard">
<Steps>
<Step title="Create a squad">
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`.
</Step>
<Step title="Save another version">
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.
</Step>
</Steps>
</Tab>

<Tab title="cURL">
<Steps>
<Step title="Set your private API key">
```bash
export VAPI_API_KEY="YOUR_VAPI_PRIVATE_KEY"
```
</Step>
<Step title="Create a squad">
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.
</Step>
<Step title="Update the squad">
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" }
]
}'
```
</Step>
</Steps>
</Tab>
</Tabs>

## View version history

<Steps>
<Step title="Open the version menu">
Select the version number in the squad header to see recent versions. The current version is marked **Current**.
</Step>
<Step title="Open the full history">
Select **View full history** to see every version and when it was saved.
</Step>
<Step title="Review or export a version">
Select a version to see its details, or select the download icon to export it as JSON.
</Step>
</Steps>
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.

<Tabs>
<Tab title="Dashboard">
<Steps>
<Step title="Open the version menu">
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**.
</Step>
<Step title="Open the full history">
Select **View full history** to see every version and when it was saved.
</Step>
<Step title="Review or export a version">
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.
</Step>
</Steps>
</Tab>

<Tab title="cURL">
<Steps>
<Step title="Set your private API key and squad ID">
```bash
export VAPI_API_KEY="YOUR_VAPI_PRIVATE_KEY"
export SQUAD_ID="YOUR_SQUAD_ID"
```
</Step>
<Step title="List the versions">
```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`.
</Step>
<Step title="Get a version's configuration">
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.
</Step>
</Steps>
</Tab>
</Tabs>

## Pin a member's assistant version

Expand All @@ -70,6 +161,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.
Expand All @@ -85,30 +178,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:

<Steps>
<Step title="Select the member">
Open the squad in the [Dashboard](https://dashboard.vapi.ai) and select the member.
</Step>
<Step title="Choose the version">
Choose **Latest** or a numbered version from the menu next to the member's name.
</Step>
<Step title="Save the squad">
Select **Save** to create a new squad version with the selection.
</Step>
</Steps>

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**.

<Tabs>
<Tab title="Dashboard">
<Steps>
<Step title="Select the member">
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.
</Step>
<Step title="Choose the version">
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.
</Step>
<Step title="Save the squad">
Select **Save** in the upper-right corner to create a new squad version with the selection.
</Step>
</Steps>
</Tab>

<Tab title="cURL">
<Steps>
<Step title="Set your private API key and squad ID">
```bash
export VAPI_API_KEY="YOUR_VAPI_PRIVATE_KEY"
export SQUAD_ID="YOUR_SQUAD_ID"
```
</Step>
<Step title="Get the current squad">
```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.
</Step>
<Step title="Update the member's version">
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.
</Step>
</Steps>
</Tab>
</Tabs>

<Tip>
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.
Expand All @@ -119,7 +243,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

Expand Down
2 changes: 2 additions & 0 deletions fern/squads-example.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

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).
2 changes: 2 additions & 0 deletions fern/squads.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion fern/squads/handoff/destinations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand Down
Loading