How squad versioning works with assistant versions

How squad versioning works

Squad versioning saves a numbered version of a squad 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.

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.
Everything you configure for a member in the squad builder, such as its model, voice, tools, and handoffs
Transient assistants defined inside the squad
Overrides that apply to all members

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	Yes
You change a member’s tools, handoffs, or other settings in the squad builder and save	Yes
You pin a member to an assistant version, change the pin, or set it back to Latest, and save	Yes
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
You edit an assistant’s draft	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.

Create a version

Edit the squad

Open the Dashboard, select Squads, and change the squad.

Save

Select Save. Vapi creates the next version and makes it current.

Through the API, each create squad or update squad request that changes the configuration creates a version.

View version history

Open the full history

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

Review or export a version

Select a version to see its details, or select the download icon to export it as JSON.

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.

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.

To pin a member in the Dashboard:

Select the member

Open the squad in the Dashboard and select the member.

Choose the version

Choose Latest or a numbered version from the menu next to the member’s name.

Save the squad

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.

{
  "members": [
    { "assistantId": "triage-assistant-id", "assistantVersion": "v3" },
    { "assistantId": "billing-assistant-id" }
  ]
}

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.

A call that uses an earlier squad version runs that version’s members and pins. Members set to Latest use each assistant’s current version.

Next steps

Versioning with assistants

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

Squads

Build multi-assistant conversations with handoffs.