Vapi Assistants API
The Assistants API from Vapi — 2 operation(s) for assistants.
OpenAPI Specification
openapi: 3.0.0
info:
title: Vapi Analytics Assistants API
description: Voice AI for developers.
version: '1.0'
contact: {}
servers:
- url: https://api.vapi.ai
tags:
- name: Assistants
paths:
/assistant:
post:
operationId: AssistantController_create
summary: Create Assistant
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAssistantDTO'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Assistant'
tags:
- Assistants
security:
- bearer: []
get:
operationId: AssistantController_findAll
summary: List Assistants
parameters:
- name: limit
required: false
in: query
description: This is the maximum number of items to return. Defaults to 100.
schema:
minimum: 0
maximum: 1000
type: number
- name: createdAtGt
required: false
in: query
description: This will return items where the createdAt is greater than the specified value.
schema:
format: date-time
type: string
- name: createdAtLt
required: false
in: query
description: This will return items where the createdAt is less than the specified value.
schema:
format: date-time
type: string
- name: createdAtGe
required: false
in: query
description: This will return items where the createdAt is greater than or equal to the specified value.
schema:
format: date-time
type: string
- name: createdAtLe
required: false
in: query
description: This will return items where the createdAt is less than or equal to the specified value.
schema:
format: date-time
type: string
- name: updatedAtGt
required: false
in: query
description: This will return items where the updatedAt is greater than the specified value.
schema:
format: date-time
type: string
- name: updatedAtLt
required: false
in: query
description: This will return items where the updatedAt is less than the specified value.
schema:
format: date-time
type: string
- name: updatedAtGe
required: false
in: query
description: This will return items where the updatedAt is greater than or equal to the specified value.
schema:
format: date-time
type: string
- name: updatedAtLe
required: false
in: query
description: This will return items where the updatedAt is less than or equal to the specified value.
schema:
format: date-time
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Assistant'
tags:
- Assistants
security:
- bearer: []
/assistant/{id}:
get:
operationId: AssistantController_findOne
summary: Get Assistant
parameters:
- name: id
required: true
in: path
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Assistant'
tags:
- Assistants
security:
- bearer: []
patch:
operationId: AssistantController_update
summary: Update Assistant
parameters:
- name: id
required: true
in: path
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAssistantDTO'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Assistant'
tags:
- Assistants
security:
- bearer: []
delete:
operationId: AssistantController_remove
summary: Delete Assistant
parameters:
- name: id
required: true
in: path
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Assistant'
tags:
- Assistants
security:
- bearer: []
components:
schemas:
CreateGoogleSheetsRowAppendToolDTO:
type: object
properties:
messages:
type: array
description: 'These are the messages that will be spoken to the user as the tool is running.
For some tools, this is auto-filled based on special fields like `tool.destinations`. For others like the function tool, these can be custom configured.'
items:
oneOf:
- $ref: '#/components/schemas/ToolMessageStart'
title: ToolMessageStart
- $ref: '#/components/schemas/ToolMessageComplete'
title: ToolMessageComplete
- $ref: '#/components/schemas/ToolMessageFailed'
title: ToolMessageFailed
- $ref: '#/components/schemas/ToolMessageDelayed'
title: ToolMessageDelayed
type:
type: string
enum:
- google.sheets.row.append
description: The type of tool. "google.sheets.row.append" for Google Sheets Row Append tool.
rejectionPlan:
description: "This is the plan to reject a tool call based on the conversation state.\n\n// Example 1: Reject endCall if user didn't say goodbye\n```json\n{\n conditions: [{\n type: 'regex',\n regex: '(?i)\\\\b(bye|goodbye|farewell|see you later|take care)\\\\b',\n target: { position: -1, role: 'user' },\n negate: true // Reject if pattern does NOT match\n }]\n}\n```\n\n// Example 2: Reject transfer if user is actually asking a question\n```json\n{\n conditions: [{\n type: 'regex',\n regex: '\\\\?',\n target: { position: -1, role: 'user' }\n }]\n}\n```\n\n// Example 3: Reject transfer if user didn't mention transfer recently\n```json\n{\n conditions: [{\n type: 'liquid',\n liquid: `{% assign recentMessages = messages | last: 5 %}\n{% assign userMessages = recentMessages | where: 'role', 'user' %}\n{% assign mentioned = false %}\n{% for msg in userMessages %}\n {% if msg.content contains 'transfer' or msg.content contains 'connect' or msg.content contains 'speak to' %}\n {% assign mentioned = true %}\n {% break %}\n {% endif %}\n{% endfor %}\n{% if mentioned %}\n false\n{% else %}\n true\n{% endif %}`\n }]\n}\n```\n\n// Example 4: Reject endCall if the bot is looping and trying to exit\n```json\n{\n conditions: [{\n type: 'liquid',\n liquid: `{% assign recentMessages = messages | last: 6 %}\n{% assign userMessages = recentMessages | where: 'role', 'user' | reverse %}\n{% if userMessages.size < 3 %}\n false\n{% else %}\n {% assign msg1 = userMessages[0].content | downcase %}\n {% assign msg2 = userMessages[1].content | downcase %}\n {% assign msg3 = userMessages[2].content | downcase %}\n {% comment %} Check for repetitive messages {% endcomment %}\n {% if msg1 == msg2 or msg1 == msg3 or msg2 == msg3 %}\n true\n {% comment %} Check for common loop phrases {% endcomment %}\n {% elsif msg1 contains 'cool thanks' or msg2 contains 'cool thanks' or msg3 contains 'cool thanks' %}\n true\n {% elsif msg1 contains 'okay thanks' or msg2 contains 'okay thanks' or msg3 contains 'okay thanks' %}\n true\n {% elsif msg1 contains 'got it' or msg2 contains 'got it' or msg3 contains 'got it' %}\n true\n {% else %}\n false\n {% endif %}\n{% endif %}`\n }]\n}\n```"
allOf:
- $ref: '#/components/schemas/ToolRejectionPlan'
required:
- type
FallbackTavusVoice:
type: object
properties:
cachingEnabled:
type: boolean
description: This is the flag to toggle voice caching for the assistant.
example: true
default: true
provider:
type: string
description: This is the voice provider that will be used.
enum:
- tavus
voiceId:
description: This is the provider-specific ID that will be used.
oneOf:
- type: string
enum:
- r52da2535a
title: Preset Voice Options
- type: string
title: Tavus Voice ID
personaId:
type: string
description: This is the unique identifier for the persona that the replica will use in the conversation.
callbackUrl:
type: string
description: This is the url that will receive webhooks with updates regarding the conversation state.
conversationName:
type: string
description: This is the name for the conversation.
conversationalContext:
type: string
description: This is the context that will be appended to any context provided in the persona, if one is provided.
customGreeting:
type: string
description: This is the custom greeting that the replica will give once a participant joines the conversation.
properties:
description: These are optional properties used to customize the conversation.
allOf:
- $ref: '#/components/schemas/TavusConversationProperties'
chunkPlan:
description: This is the plan for chunking the model output before it is sent to the voice provider.
allOf:
- $ref: '#/components/schemas/ChunkPlan'
required:
- provider
- voiceId
FallbackNeuphonicVoice:
type: object
properties:
cachingEnabled:
type: boolean
description: This is the flag to toggle voice caching for the assistant.
example: true
default: true
provider:
type: string
description: This is the voice provider that will be used.
enum:
- neuphonic
voiceId:
description: This is the provider-specific ID that will be used.
oneOf:
- type: string
enum: []
title: Preset Voice Options
- type: string
title: Neuphonic Voice ID
model:
type: string
description: This is the model that will be used. Defaults to 'neu_fast' if not specified.
enum:
- neu_hq
- neu_fast
example: neu_fast
language:
type: object
description: This is the language (ISO 639-1) that is enforced for the model.
example: en
speed:
type: number
description: This is the speed multiplier that will be used.
minimum: 0.25
maximum: 2
example: null
chunkPlan:
description: This is the plan for chunking the model output before it is sent to the voice provider.
allOf:
- $ref: '#/components/schemas/ChunkPlan'
required:
- provider
- voiceId
- language
FallbackVapiVoice:
type: object
properties:
cachingEnabled:
type: boolean
description: This is the flag to toggle voice caching for the assistant.
example: true
default: true
provider:
type: string
description: This is the voice provider that will be used.
enum:
- vapi
voiceId:
type: string
description: The voices provided by Vapi
enum:
- Clara
- Godfrey
- Layla
- Sid
- Gustavo
- Elliot
- Kylie
- Rohan
- Lily
- Savannah
- Hana
- Neha
- Cole
- Harry
- Paige
- Spencer
- Nico
- Kai
- Emma
- Sagar
- Neil
- Naina
- Leah
- Tara
- Jess
- Leo
- Dan
- Mia
- Zac
- Zoe
speed:
type: number
description: 'This is the speed multiplier that will be used.
@default 1'
minimum: 0.25
maximum: 2
default: 1
pronunciationDictionary:
description: List of pronunciation dictionary locators for custom word pronunciations.
type: array
items:
$ref: '#/components/schemas/VapiPronunciationDictionaryLocator'
chunkPlan:
description: This is the plan for chunking the model output before it is sent to the voice provider.
allOf:
- $ref: '#/components/schemas/ChunkPlan'
required:
- provider
- voiceId
WellSaidVoice:
type: object
properties:
cachingEnabled:
type: boolean
description: This is the flag to toggle voice caching for the assistant.
example: true
default: true
provider:
type: string
description: This is the voice provider that will be used.
enum:
- wellsaid
voiceId:
type: string
description: The WellSaid speaker ID to synthesize.
model:
type: string
description: This is the model that will be used.
enum:
- caruso
- legacy
enableSsml:
type: boolean
description: Enables limited SSML translation for input text.
libraryIds:
description: Array of library IDs to use for voice synthesis.
type: array
items:
type: string
chunkPlan:
description: This is the plan for chunking the model output before it is sent to the voice provider.
allOf:
- $ref: '#/components/schemas/ChunkPlan'
fallbackPlan:
description: This is the plan for voice provider fallbacks in the event that the primary voice provider fails.
allOf:
- $ref: '#/components/schemas/FallbackPlan'
required:
- provider
- voiceId
CustomerSpeechTimeoutOptions:
type: object
properties:
timeoutSeconds:
type: number
description: 'This is the timeout in seconds before action is triggered.
The clock starts when the assistant finishes speaking and remains active until the user speaks.
@default 7.5
@minimum 2
@maximum 1000'
minimum: 1
maximum: 1000
triggerMaxCount:
type: number
description: 'This is the maximum number of times the hook will trigger in a call.
@default 3'
minimum: 1
maximum: 10
triggerResetMode:
type: object
description: 'This is whether the counter for hook trigger resets the user speaks.
@default never'
required:
- timeoutSeconds
CreateInflectionAICredentialDTO:
type: object
properties:
provider:
type: string
description: 'This is the api key for Pi in InflectionAI''s console. Get it from here: https://developers.inflection.ai/keys, billing will need to be setup'
enum:
- inflection-ai
apiKey:
type: string
maxLength: 10000
description: This is not returned in the API.
name:
type: string
description: This is the name of credential. This is just for your reference.
minLength: 1
maxLength: 40
required:
- provider
- apiKey
CreateGoogleSheetsOAuth2AuthorizationCredentialDTO:
type: object
properties:
provider:
type: string
enum:
- google.sheets.oauth2-authorization
authorizationId:
type: string
description: The authorization ID for the OAuth2 authorization
name:
type: string
description: This is the name of credential. This is just for your reference.
minLength: 1
maxLength: 40
required:
- provider
- authorizationId
TwilioVoicemailDetectionPlan:
type: object
properties:
provider:
type: string
description: This is the provider to use for voicemail detection.
enum:
- twilio
voicemailDetectionTypes:
type: array
description: 'These are the AMD messages from Twilio that are considered as voicemail. Default is [''machine_end_beep'', ''machine_end_silence''].
@default {Array} [''machine_end_beep'', ''machine_end_silence'']'
enum:
- machine_start
- human
- fax
- unknown
- machine_end_beep
- machine_end_silence
- machine_end_other
example:
- machine_end_beep
- machine_end_silence
items:
type: string
enum:
- machine_start
- human
- fax
- unknown
- machine_end_beep
- machine_end_silence
- machine_end_other
enabled:
type: boolean
description: 'This sets whether the assistant should detect voicemail. Defaults to true.
@default true'
machineDetectionTimeout:
type: number
description: 'The number of seconds that Twilio should attempt to perform answering machine detection before timing out and returning AnsweredBy as unknown. Default is 30 seconds.
Increasing this value will provide the engine more time to make a determination. This can be useful when DetectMessageEnd is provided in the MachineDetection parameter and there is an expectation of long answering machine greetings that can exceed 30 seconds.
Decreasing this value will reduce the amount of time the engine has to make a determination. This can be particularly useful when the Enable option is provided in the MachineDetection parameter and you want to limit the time for initial detection.
Check the [Twilio docs](https://www.twilio.com/docs/voice/answering-machine-detection#optional-api-tuning-parameters) for more info.
@default 30'
minimum: 3
maximum: 59
machineDetectionSpeechThreshold:
type: number
description: 'The number of milliseconds that is used as the measuring stick for the length of the speech activity. Durations lower than this value will be interpreted as a human, longer as a machine. Default is 2400 milliseconds.
Increasing this value will reduce the chance of a False Machine (detected machine, actually human) for a long human greeting (e.g., a business greeting) but increase the time it takes to detect a machine.
Decreasing this value will reduce the chances of a False Human (detected human, actually machine) for short voicemail greetings. The value of this parameter may need to be reduced by more than 1000ms to detect very short voicemail greetings. A reduction of that significance can result in increased False Machine detections. Adjusting the MachineDetectionSpeechEndThreshold is likely the better approach for short voicemails. Decreasing MachineDetectionSpeechThreshold will also reduce the time it takes to detect a machine.
Check the [Twilio docs](https://www.twilio.com/docs/voice/answering-machine-detection#optional-api-tuning-parameters) for more info.
@default 2400'
minimum: 1000
maximum: 6000
machineDetectionSpeechEndThreshold:
type: number
description: 'The number of milliseconds of silence after speech activity at which point the speech activity is considered complete. Default is 1200 milliseconds.
Increasing this value will typically be used to better address the short voicemail greeting scenarios. For short voicemails, there is typically 1000-2000ms of audio followed by 1200-2400ms of silence and then additional audio before the beep. Increasing the MachineDetectionSpeechEndThreshold to ~2500ms will treat the 1200-2400ms of silence as a gap in the greeting but not the end of the greeting and will result in a machine detection. The downsides of such a change include:
- Increasing the delay for human detection by the amount you increase this parameter, e.g., a change of 1200ms to 2500ms increases human detection delay by 1300ms.
- Cases where a human has two utterances separated by a period of silence (e.g. a "Hello", then 2000ms of silence, and another "Hello") may be interpreted as a machine.
Decreasing this value will result in faster human detection. The consequence is that it can lead to increased False Human (detected human, actually machine) detections because a silence gap in a voicemail greeting (not necessarily just in short voicemail scenarios) can be incorrectly interpreted as the end of speech.
Check the [Twilio docs](https://www.twilio.com/docs/voice/answering-machine-detection#optional-api-tuning-parameters) for more info.
@default 1200'
minimum: 500
maximum: 5000
machineDetectionSilenceTimeout:
type: number
description: 'The number of milliseconds of initial silence after which an unknown AnsweredBy result will be returned. Default is 5000 milliseconds.
Increasing this value will result in waiting for a longer period of initial silence before returning an ''unknown'' AMD result.
Decreasing this value will result in waiting for a shorter period of initial silence before returning an ''unknown'' AMD result.
Check the [Twilio docs](https://www.twilio.com/docs/voice/answering-machine-detection#optional-api-tuning-parameters) for more info.
@default 5000'
minimum: 2000
maximum: 10000
required:
- provider
CreatePlayHTCredentialDTO:
type: object
properties:
provider:
type: string
enum:
- playht
apiKey:
type: string
description: This is not returned in the API.
userId:
type: string
name:
type: string
description: This is the name of credential. This is just for your reference.
minLength: 1
maxLength: 40
required:
- provider
- apiKey
- userId
CreateEmailCredentialDTO:
type: object
properties:
provider:
type: string
enum:
- email
email:
type: string
description: The recipient email address for alerts
name:
type: string
description: This is the name of credential. This is just for your reference.
minLength: 1
maxLength: 40
required:
- provider
- email
FallbackElevenLabsTranscriber:
type: object
properties:
provider:
type: string
description: This is the transcription provider that will be used.
enum:
- 11labs
model:
description: This is the model that will be used for the transcription.
oneOf:
- enum:
- scribe_v1
- scribe_v2
- scribe_v2_realtime
language:
type: string
description: This is the language that will be used for the transcription.
enum:
- aa
- ab
- ae
- af
- ak
- am
- an
- ar
- as
- av
- ay
- az
- ba
- be
- bg
- bh
- bi
- bm
- bn
- bo
- br
- bs
- ca
- ce
- ch
- co
- cr
- cs
- cu
- cv
- cy
- da
- de
- dv
- dz
- ee
- el
- en
- eo
- es
- et
- eu
- fa
- ff
- fi
- fj
- fo
- fr
- fy
- ga
- gd
- gl
- gn
- gu
- gv
- ha
- he
- hi
- ho
- hr
- ht
- hu
- hy
- hz
- ia
- id
- ie
- ig
- ii
- ik
- io
- is
- it
- iu
- ja
- jv
- ka
- kg
- ki
- kj
- kk
- kl
- km
- kn
- ko
- kr
- ks
- ku
- kv
- kw
- ky
- la
- lb
- lg
- li
- ln
- lo
- lt
- lu
- lv
- mg
- mh
- mi
- mk
- ml
- mn
- mr
- ms
- mt
- my
- na
- nb
- nd
- ne
- ng
- nl
- nn
- 'no'
- nr
- nv
- ny
- oc
- oj
- om
- or
- os
- pa
- pi
- pl
- ps
- pt
- qu
- rm
- rn
- ro
- ru
- rw
- sa
- sc
- sd
- se
- sg
- si
- sk
- sl
- sm
- sn
- so
- sq
- sr
- ss
- st
- su
- sv
- sw
- ta
- te
- tg
- th
- ti
- tk
- tl
- tn
- to
- tr
- ts
- tt
- tw
- ty
- ug
- uk
- ur
- uz
- ve
- vi
- vo
- wa
- wo
- xh
- yi
- yue
- yo
- za
- zh
- zu
silenceThresholdSeconds:
type: number
description: This is the number of seconds of silence before VAD commits (0.3-3.0).
minimum: 0.3
maximum: 3
example: 1.5
confidenceThreshold:
type: number
description: This is the VAD sensitivity (0.1-0.9, lower indicates more sensitive).
minimum: 0.1
maximum: 0.9
example: 0.4
minSpeechDurationMs:
type: number
description: This is the minimum speech duration for VAD (50-2000ms).
minimum: 50
maximum: 2000
example: 100
minSilenceDurationMs:
type: number
description: This is the minimum silence duration for VAD (50-2000ms).
minimum: 50
maximum: 2000
example: 100
required:
- provider
RegexReplacement:
type: object
properties:
type:
type: string
description: 'This is the regex replacement type. You can use this to replace a word or phrase that matches a pattern.
Usage:
- Replace all numbers with "some number": { type: ''regex'', regex: ''\\d+'', value: ''some number'' }
- Replace email addresses with "[EMAIL]": { type: ''regex'', regex: ''\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b'', value: ''[EMAIL]'' }
- Replace phone numbers with a formatted version: { type: ''regex'', regex: ''(\\d{3})(\\d{3})(\\d{4})'', value: ''($1) $2-$3'' }
- Replace all instances of "color" or "colour" with "hue": { type: ''regex'', regex: ''colou?r'', value: ''hue'' }
- Capitalize the first letter of every sentence: { type: ''regex'', regex: ''(?<=\\. |^)[a-z]'', value: (match) => match.toUpperCase() }'
enum:
- regex
regex:
type: string
description: 'This is the regex pattern to replace.
Note:
- This works by using the `string.replace` method in Node.JS. Eg. `"hello there".replace(/hello/g, "hi")` will return `"hi there"`.
Hot tip:
- In JavaScript, escape `\` when sending the regex pattern. Eg. `"hello\sthere"` will be sent over the wire as `"hellosthere"`. Send `"hello\\sthere"` instead.'
options:
description: 'These are the options for the regex replacement. Defaults to all disabled.
@default []'
type: array
items:
$ref: '#/components/schemas/RegexOption'
value:
type: string
description: This is the value that will replace the match.
maxLength: 1000
required:
- type
- regex
- value
AssistantOverrides:
type: object
properties:
transcriber:
description: These are the options for the assistant's transcriber.
oneOf:
- $ref: '#/components/schemas/AssemblyAITranscriber'
title: AssemblyAITranscriber
- $ref: '#/components/schemas/AzureSpeechTranscriber'
title: AzureSpeechTranscriber
- $ref: '#/components/schemas/CustomTranscriber'
title: CustomTranscriber
- $ref: '#/components/schemas/DeepgramTranscriber'
title: DeepgramTranscriber
- $ref: '#/components/schemas/ElevenLabsTranscriber'
title: ElevenLabsTranscriber
- $ref: '#/components/schemas/GladiaTranscriber'
title: GladiaTranscriber
- $ref: '#/components/schemas/GoogleTranscriber'
title: GoogleTranscriber
- $ref: '#/components/schemas/SpeechmaticsTranscriber'
title: SpeechmaticsTranscriber
- $ref: '#/components/schemas/TalkscriberTranscriber'
title: TalkscriberTranscriber
- $ref: '#/components/schemas/OpenAITranscriber'
title: OpenAITranscriber
- $ref: '#/components/schemas/CartesiaTranscriber'
title: CartesiaTranscriber
- $ref: '#/components/schemas/SonioxTranscriber'
title: SonioxTranscriber
model:
description: These are the options for the assistant's LLM.
oneOf:
- $ref: '#/components/schemas/AnthropicModel'
title: Anthropic
- $ref: '#/components/schemas/AnthropicBedrockModel'
title: AnthropicBedrock
- $ref: '#/components/schemas/AnyscaleModel'
title: Anyscale
- $ref: '#/components/schemas/CerebrasModel'
title: Cerebras
- $ref: '#/components/schemas/CustomLLMModel'
title: CustomLLM
- $ref: '#/components/schemas/DeepInfraModel'
title: DeepInfra
- $ref: '#/components/schemas/DeepSeekModel'
title: DeepSeek
- $ref: '#/components/schemas/GoogleModel'
title: Google
- $ref: '#/components/schemas/GroqModel'
title: Groq
- $ref: '#/components/schemas/InflectionAIModel'
title: InflectionAI
- $ref: '#/components/schemas/MinimaxLLMModel'
title: MiniMaxLLM
- $ref: '#/components/schemas/OpenAIModel'
title: OpenAI
- $ref: '#/components/schemas/OpenRouterModel'
title: OpenRouter
- $ref: '#/components/schemas/PerplexityAIModel'
title: PerplexityAI
- $ref: '#/components/schemas/TogetherAIModel'
title: Together
- $ref: '#/components/schemas/XaiModel'
title: XAI
voice:
description: These are the options for the assistant's voice.
oneOf:
- $ref: '#/components/schemas/AzureVoice'
title: AzureVoice
# --- truncated at 32 KB (753 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vapi/refs/heads/main/openapi/vapi-assistants-api-openapi.yml