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 +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.
@@ -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:
-
-
-
- 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 +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
diff --git a/fern/squads-example.mdx b/fern/squads-example.mdx
index afe87c12f..49259b222 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).
+
+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).
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
{