Skip to navigation
Traffic Allocations

Create traffic allocation

Beta

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.

Authentication

AuthorizationBearer

Authenticate server-side requests with a private Vapi API key. Create or copy a key from the Vapi Dashboard and send it in the Authorization header as Bearer <token>. Keep private API keys out of client-side code and public repositories.

Request

This endpoint expects an object.
assistantIdstringRequired
The assistant whose calls this allocation splits.
allocationIntentenumOptional

‘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:
targetslist of objectsOptional

The versions to split calls across. Omit to stop splitting (with allocationIntent ‘follow-latest’). Order in this array is the selection order (position).

expectedCurrentAllocationIdstringOptionalformat: "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.

descriptionstringOptional<=1000 characters
An optional note explaining why you made this change.

Response

idstring
Unique identifier. The most recently created allocation for an assistant is the one in effect.
orgIdstring
allocationIntentenum

‘explicit’ splits calls across this allocation’s targets. ‘follow-latest’ sends every call to the newest published version.

Allowed values:
createdAtdatetime
When this allocation was created, which is also when it took effect.
actorTypeenum

Who created this allocation. ‘system’ means Vapi created it automatically, for example when a publish advances a follow-latest allocation.

Allowed values:
targetslist of objects

The versions this allocation splits calls across, in position order. Empty for follow-latest allocations.

assistantIdstringOptional
The assistant this allocation splits calls for.
actorIdstringOptional
The user id or API key id that created this allocation. Absent for system rows.
actorEmailstringOptional
Email of the user who created this allocation, as of that time.
descriptionstringOptional
The note given when this allocation was created, if any.

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error