How squad versioning works with assistant versions

Pin squad members to assistant versions or follow the latest, and view squad version history as you build

How squad versioning works

When you save a changed squad 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:

The squad name
The members, in order
Each member’s assistant version: a pinned version, such as v3, or Latest.
Member overrides that you configure in the squad builder, such as a member’s model, voice, tools, and handoffs
Squad-level overrides that apply to all members
Transient assistants defined inside the squad

Member overrides apply only when the assistant runs in this squad. They don’t change the assistant itself.

The assistant’s own configuration, including its tools, belongs to the assistant version. You change it in the assistant editor, and the squad uses it through the member’s pinned or Latest setting.

When a version is created

Change	Creates a squad version?
You create a squad	Yes, `v1`
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 a change: the existing configuration becomes v1 and your changes become v2.

Create a version

Create a squad to make v1. Later changes to its configuration create the next version when you save them.

Dashboard

cURL

Create a squad

In the Dashboard, 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.

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.

View version history

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.

Dashboard

cURL

Open the full history

Select View full history to see every version and when it was saved.

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.

Pin a member’s assistant version

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.

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.
Pinned members stay on their pinned version until you change the pin and save the squad.

For example, squad v1 has assistant A pinned to v5 and assistant B set to Latest:

What happens	A runs	B runs	Squad version
You save the squad, while B’s newest version is v2	v5	v2	v1
A publishes v6 and B publishes v3	v5	v3	v1
You pin A to v6 and save the squad	v6	v3	v2

Squads pin assistant versions. Each assistant version keeps its own tool version selections, so a pinned member uses the tool versions saved with that assistant version.

Set assistantVersion on a saved assistant member to pin it. Omit the field to use Latest.

Dashboard

cURL

Select the member

In the Dashboard, select Squads in the sidebar and open the squad. Select the assistant member on the builder canvas to open its settings panel.

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.

Save the squad

Select Save in the upper-right corner to create a new squad version with the selection.

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.

Which version a call uses

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.

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.

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.

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

Versioning with assistants

Publish, view history, and restore versions of an assistant.

Squads

Build multi-assistant conversations with handoffs.