---
title: "Create traffic allocation"
method: POST
path: "/traffic-allocations"
tags: ["Traffic Allocations"]
---

# Create traffic allocation

`POST /traffic-allocations`

## Request

- Base URL: `https://api.vapi.ai`
- URL: `https://api.vapi.ai/traffic-allocations`
- Auth: HTTP bearer

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.

## Request body

- CreateTrafficAllocationDTO
  - `assistantId` string, required: The assistant whose calls this allocation splits.
  - `allocationIntent` 'follow-latest' | 'explicit': '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.
  - `targets` CreateTrafficAllocationTargetDTO[]: The versions to split calls across. Omit to stop splitting (with allocationIntent 'follow-latest'). Order in this array is the selection order (position).
    - `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` number, 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.
  - `expectedCurrentAllocationId` string, uuid: 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: An optional note explaining why you made this change.

## Response `201`

- TrafficAllocation
  - `id` string, required: Unique identifier. The most recently created allocation for an assistant is the one in effect.
  - `orgId` string, required
  - `assistantId` string: The assistant this allocation splits calls for.
  - `allocationIntent` 'follow-latest' | 'explicit', required: 'explicit' splits calls across this allocation's targets. 'follow-latest' sends every call to the newest published version.
  - `createdAt` string, date-time, required: When this allocation was created, which is also when it took effect.
  - `actorType` 'user' | 'api-key' | 'system', required: Who created this allocation. 'system' means Vapi created it automatically, for example when a publish advances a follow-latest allocation.
  - `actorId` string: The user id or API key id that created this allocation. Absent for system rows.
  - `actorEmail` string: Email of the user who created this allocation, as of that time.
  - `description` string: The note given when this allocation was created, if any.
  - `targets` TrafficAllocationTarget[], required: The versions this allocation splits calls across, in position order. Empty for follow-latest allocations.
    - `assistantVersion` string, required: The assistant version this target sends calls to, such as "v7".
    - `position` number, required: The target's place in the split, starting at 0. Set from the order of the targets array.
    - `percentage` number, 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.

## Other responses

- `400`: 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.
- `403`: Traffic splitting is not enabled for your organization. The feature is in beta, rolling out to select organizations.
- `404`: The source assistant does not exist.
- `409`: The provided expectedCurrentAllocationId no longer matches the allocation currently in effect (see TrafficAllocationStaleConflictResponseDTO; omitting the field never conflicts), or Vapi for CX manages the assistant (see AssistantManagedConflictResponseDTO).

## Changes

> 164 revisions in range; 15 not diffed, 8 could not be searched.

- **2026-10-14** `7c28def60c4f`: 4 breaking, 1 warning, 1 info
  - added `#/components/schemas/TrafficAllocationStaleConflictResponseDTO, #/components/schemas/AssistantManagedConflictResponseDTO` to the response body `oneOf` list for the response status `409`
  - the response's body type changed from `object` to no type for status `409`
  - removed the required property `error` from the response with the `409` status
  - removed the required property `message` from the response with the `409` status
  - …2 more
- **2026-10-01** `e32916789bb1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vapiai/apis/vapi-api/changes/traffic-allocations/post.md)

---

[API](https://skmtc.dev/vapiai/apis/vapi-api.md) - [All operations](https://skmtc.dev/vapiai/apis/vapi-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vapiai/apis/vapi-api/revisions/d73a715574fb?raw)