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

# Create traffic allocation

POST https://api.vapi.ai/traffic-allocations
Content-Type: application/json

Creates a new traffic allocation for an assistant, replacing the one currently in effect. To start or adjust a split, send targets naming published versions (such as "v7") with percentages totaling 100; allocationIntent is inferred as 'explicit'. To stop splitting and send every call to the newest published version, send allocationIntent 'follow-latest' with no targets field; stopping always names its intent, so a dropped targets field can never end a split by accident. Traffic splitting is in beta, rolling out to select organizations; requests from organizations without access receive a 403.

Reference: https://docs.vapi.ai/api-reference/traffic-allocations/traffic-allocation-controller-create

## Authentication

- `Authorization` header (bearer token, required) — Authenticate server-side requests with a private Vapi API key. Create or copy a key from the [Vapi Dashboard](https://dashboard.vapi.ai) and send it in the `Authorization` header as `Bearer <token>`. Keep private API keys out of client-side code and public repositories.

## Request

### Body (application/json)

This endpoint expects a CreateTrafficAllocationDTO.

- `assistantId` (string, required) — The assistant whose calls this allocation splits.
- `allocationIntent` (enum, optional) — 'explicit' splits calls across targets, and is inferred when targets is sent. 'follow-latest' sends every call to the newest published version and is how you stop splitting; it must be sent explicitly.
  - Allowed values: `follow-latest`, `explicit`
- `targets` (list of CreateTrafficAllocationTargetDTO, optional) — The versions to split calls across. Omit to stop splitting (with allocationIntent 'follow-latest'). Order in this array is the selection order (position).
- `expectedCurrentAllocationId` (string, optional) — Optional concurrency guard. Omit it and the write applies unconditionally (last write wins, matching every other Vapi update surface). Provide the id of the allocation you last read and the write applies only while that allocation is still governing; any mismatch is a 409 carrying the actual current id.
- `description` (string, optional) — An optional note explaining why you made this change.

## Response

### 201

- `id` (string, required) — Unique identifier. The most recently created allocation for an assistant is the one in effect.
- `orgId` (string, required)
- `allocationIntent` (enum, required) — 'explicit' splits calls across this allocation's targets. 'follow-latest' sends every call to the newest published version.
  - Allowed values: `follow-latest`, `explicit`
- `createdAt` (datetime, required) — When this allocation was created, which is also when it took effect.
- `actorType` (enum, required) — Who created this allocation. 'system' means Vapi created it automatically, for example when a publish advances a follow-latest allocation.
  - Allowed values: `user`, `api-key`, `system`
- `targets` (list of TrafficAllocationTarget, required) — The versions this allocation splits calls across, in position order. Empty for follow-latest allocations.
- `assistantId` (string, optional) — The assistant this allocation splits calls for.
- `actorId` (string, optional) — The user id or API key id that created this allocation. Absent for system rows.
- `actorEmail` (string, optional) — Email of the user who created this allocation, as of that time.
- `description` (string, optional) — The note given when this allocation was created, if any.

## Errors

### 400 Bad Request Error

Create 400s when the request carries neither targets nor an allocationIntent, when the target set breaks a shape rule (targets combined with follow-latest, an explicit allocation with no targets, duplicate target versions, percentages not totaling 100, no positive percentage), or when a target names a version that does not exist on this assistant.

- `any`

### 403 Forbidden Error

Traffic splitting is not enabled for your organization. The feature is in beta, rolling out to select organizations.

- `any`

### 404 Not Found Error

The source assistant does not exist.

- `any`

### 409 Conflict Error

The provided expectedCurrentAllocationId no longer matches the allocation currently in effect (see TrafficAllocationStaleConflictResponseDTO; omitting the field never conflicts), or Vapi Agents manages the assistant (see AssistantManagedConflictResponseDTO).

- `TrafficAllocationController_createRequestConflictError`
  - `error`: `stale_allocation` (stale_allocation)
    - `message` (string, required) — Human-readable reason the create was rejected.
    - `currentAllocationId` (string, optional, nullable) — The allocation currently in effect. Null if none exists yet.
  - `error`: `assistant_managed_by_vapi_agents` (assistant_managed_by_vapi_agents)
    - `message` (string, required) — Why the write was rejected and how to make the change in Vapi Agents instead: the agent link, the Vapi Agents MCP URL with the steps to connect it, and which of its tools to call.
    - `vapiAgents` (AssistantManagedVapiAgentsDTO, required)

## Types

### CreateTrafficAllocationTargetDTO

- `assistantVersion` (string, required) — A published version of this assistant, such as "v7". To split onto a new version, publish it first, then create the allocation.
- `percentage` (double, required) — Share of calls sent to this version, from 0 to 100 with up to three decimal places. Finer values are rejected, not rounded. All targets together add up to exactly 100. Position is taken from array order.

### TrafficAllocationTarget

- `assistantVersion` (string, required) — The assistant version this target sends calls to, such as "v7".
- `position` (double, required) — The target's place in the split, starting at 0. Set from the order of the targets array.
- `percentage` (double, required) — Share of calls sent to this version, from 0 to 100 with up to three decimal places. Targets add up to exactly 100. A 0% target keeps the version in the split without sending it calls.

### AssistantManagedVapiAgentsDTO

- `agentId` (string, required) — The Vapi Agents agent that manages the assistant.
- `agentUrl` (string, required) — The agent's page in Vapi Agents.
- `mcpUrl` (string, required) — The Vapi Agents MCP server, where an AI client makes the change instead.

## Examples

**Request**

```json
{
  "assistantId": "string"
}
```

**Response**

```json
{
  "id": "string",
  "orgId": "string",
  "allocationIntent": "follow-latest",
  "createdAt": "2024-01-15T09:30:00Z",
  "actorType": "user",
  "targets": [
    {
      "assistantVersion": "string",
      "position": 1.1,
      "percentage": 1.1
    }
  ],
  "assistantId": "string",
  "actorId": "string",
  "actorEmail": "string",
  "description": "string"
}
```