> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# How squad versioning works with assistant versions

> Create and review squad versions, pin members to specific published assistant versions or use Latest, and choose a squad version for outbound calls.

## 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. 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](/assistants/versioning/versioning-assistants). 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

#### 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`.

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

#### cURL

#### Set your private API key

```bash
export VAPI_API_KEY="YOUR_VAPI_PRIVATE_KEY"
```

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

#### 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" }
    ]
  }'
```

## 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

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

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

#### cURL

#### Set your private API key and squad ID

```bash
export VAPI_API_KEY="YOUR_VAPI_PRIVATE_KEY"
export SQUAD_ID="YOUR_SQUAD_ID"
```

#### 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`.

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

## 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](/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.
* 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](/assistants/versioning/versioning-with-assistants-and-tools), 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

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

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

#### cURL

#### Set your private API key and squad ID

```bash
export VAPI_API_KEY="YOUR_VAPI_PRIVATE_KEY"
export SQUAD_ID="YOUR_SQUAD_ID"
```

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

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

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

## 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](/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](/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

#### [Versioning with assistants](/assistants/versioning/versioning-assistants)

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

#### [Squads](/squads)

Build multi-assistant conversations with handoffs.