Vapi Sessions API
The Sessions API from Vapi — 2 operation(s) for sessions.
The Sessions API from Vapi — 2 operation(s) for sessions.
openapi: 3.0.0
info:
title: Vapi Analytics Sessions API
description: Voice AI for developers.
version: '1.0'
contact: {}
servers:
- url: https://api.vapi.ai
tags:
- name: Sessions
paths:
/session:
post:
operationId: SessionController_create
summary: Create Session
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSessionDTO'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
tags:
- Sessions
security:
- bearer: []
get:
operationId: SessionController_findAllPaginated
summary: List Sessions
parameters:
- name: id
required: false
in: query
description: This is the unique identifier for the session to filter by.
schema:
type: string
- name: name
required: false
in: query
description: This is the name of the session to filter by.
schema:
type: string
- name: assistantId
required: false
in: query
description: This is the ID of the assistant to filter sessions by.
schema:
type: string
- name: assistantIdAny
required: false
in: query
description: Filter by multiple assistant IDs. Provide as comma-separated values.
schema:
example: assistant-1,assistant-2,assistant-3
type: string
- name: squadId
required: false
in: query
description: This is the ID of the squad to filter sessions by.
schema:
type: string
- name: workflowId
required: false
in: query
description: This is the ID of the workflow to filter sessions by.
schema:
type: string
- required: false
description: 'This is the flag to toggle the E164 check for the `number` field. This is an advanced property which should be used if you know your use case requires it.
Use cases:
- `false`: To allow non-E164 numbers like `+001234567890`, `1234`, or `abc`. This is useful for dialing out to non-E164 numbers on your SIP trunks.
- `true` (default): To allow only E164 numbers like `+14155551234`. This is standard for PSTN calls.
If `false`, the `number` is still required to only contain alphanumeric characters (regex: `/^\+?[a-zA-Z0-9]+$/`).
@default true (E164 check is enabled)'
name: numberE164CheckEnabled
in: query
schema:
default: true
type: boolean
- required: false
description: This is the extension that will be dialed after the call is answered.
name: extension
in: query
schema:
maxLength: 10
example: null
type: string
- name: assistantOverrides
required: false
description: 'These are the overrides for the assistant''s settings and template variables specific to this customer.
This allows customization of the assistant''s behavior for individual customers in batch calls.'
allOf:
- $ref: '#/components/schemas/AssistantOverrides'
in: query
schema: {}
- required: false
description: This is the number of the customer.
name: number
in: query
schema:
minLength: 3
maxLength: 40
type: string
- required: false
description: This is the SIP URI of the customer.
name: sipUri
in: query
schema:
type: string
- required: false
description: 'This is the name of the customer. This is just for your own reference.
For SIP inbound calls, this is extracted from the `From` SIP header with format `"Display Name" <sip:username@domain>`.'
name: name
in: query
schema:
maxLength: 40
type: string
- required: false
description: This is the email of the customer.
name: email
in: query
schema:
maxLength: 40
type: string
- required: false
description: This is the external ID of the customer.
name: externalId
in: query
schema:
maxLength: 40
type: string
- name: customerNumberAny
required: false
in: query
description: Filter by any of the specified customer phone numbers (comma-separated).
schema:
example: +1234567890,+0987654321
type: string
- name: phoneNumberId
required: false
in: query
description: This will return sessions with the specified phoneNumberId.
schema:
type: string
- name: phoneNumberIdAny
required: false
in: query
description: This will return sessions with any of the specified phoneNumberIds.
schema:
type: array
items:
type: string
- name: page
required: false
in: query
description: This is the page number to return. Defaults to 1.
schema:
minimum: 1
type: number
- name: sortOrder
required: false
in: query
description: This is the sort order for pagination. Defaults to 'DESC'.
schema:
enum:
- ASC
- DESC
type: string
- name: sortBy
required: false
in: query
description: This is the column to sort by. Defaults to 'createdAt'.
schema:
enum:
- createdAt
- duration
- cost
type: string
- 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:
$ref: '#/components/schemas/SessionPaginatedResponse'
tags:
- Sessions
security:
- bearer: []
/session/{id}:
get:
operationId: SessionController_findOne
summary: Get Session
parameters:
- name: id
required: true
in: path
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
tags:
- Sessions
security:
- bearer: []
patch:
operationId: SessionController_update
summary: Update Session
parameters:
- name: id
required: true
in: path
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSessionDTO'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
tags:
- Sessions
security:
- bearer: []
delete:
operationId: SessionController_remove
summary: Delete Session
parameters:
- name: id
required: true
in: path
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
tags:
- Sessions
security:
- bearer: []
components:
schemas:
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
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
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
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
- $ref: '#/components/schemas/CartesiaVoice'
title: CartesiaVoice
- $ref: '#/components/schemas/CustomVoice'
title: CustomVoice
- $ref: '#/components/schemas/DeepgramVoice'
title: DeepgramVoice
- $ref: '#/components/schemas/ElevenLabsVoice'
title: ElevenLabsVoice
- $ref: '#/components/schemas/HumeVoice'
title: HumeVoice
- $ref: '#/components/schemas/LMNTVoice'
title: LMNTVoice
- $ref: '#/components/schemas/NeuphonicVoice'
title: NeuphonicVoice
- $ref: '#/components/schemas/OpenAIVoice'
title: OpenAIVoice
- $ref: '#/components/schemas/PlayHTVoice'
title: PlayHTVoice
- $ref: '#/components/schemas/WellSaidVoice'
title: WellSaidVoice
- $ref: '#/components/schemas/RimeAIVoice'
title: RimeAIVoice
- $ref: '#/components/schemas/SmallestAIVoice'
title: SmallestAIVoice
- $ref: '#/components/schemas/TavusVoice'
title: TavusVoice
- $ref: '#/components/schemas/VapiVoice'
title: VapiVoice
- $ref: '#/components/schemas/SesameVoice'
title: SesameVoice
- $ref: '#/components/schemas/InworldVoice'
title: InworldVoice
- $ref: '#/components/schemas/MinimaxVoice'
title: MinimaxVoice
firstMessage:
type: string
description: 'This is the first message that the assistant will say. This can also be a URL to a containerized audio file (mp3, wav, etc.).
If unspecified, assistant will wait for user to speak and use the model to respond once they speak.'
example: Hello! How can I help you today?
firstMessageInterruptionsEnabled:
type: boolean
default: false
firstMessageMode:
type: string
description: 'This is the mode for the first message. Default is ''assistant-speaks-first''.
Use:
- ''assistant-speaks-first'' to have the assistant speak first.
- ''assistant-waits-for-user'' to have the assistant wait for the user to speak first.
- ''assistant-speaks-first-with-model-generated-message'' to have the assistant speak first with a message generated by the model based on the conversation state. (`assistant.model.messages` at call start, `call.messages` at squad transfer points).
@default ''assistant-speaks-first'''
enum:
- assistant-speaks-first
- assistant-speaks-first-with-model-generated-message
- assistant-waits-for-user
example: assistant-speaks-first
voicemailDetection:
description: 'These are the settings to configure or disable voicemail detection. Alternatively, voicemail detection can be configured using the model.tools=[VoicemailTool].
By default, voicemail detection is disabled.'
oneOf:
- type: string
enum:
- 'off'
- $ref: '#/components/schemas/GoogleVoicemailDetectionPlan'
title: Google
- $ref: '#/components/schemas/OpenAIVoicemailDetectionPlan'
title: OpenAI
- $ref: '#/components/schemas/TwilioVoicemailDetectionPlan'
title: Twilio
- $ref: '#/components/schemas/VapiVoicemailDetectionPlan'
title: Vapi
clientMessages:
type: array
enum:
- conversation-update
- assistant.speechStarted
- function-call
- function-call-result
- hang
- language-changed
- metadata
- model-output
- speech-update
- status-update
- transcript
- tool-calls
- tool-calls-result
- tool.completed
- transfer-update
- user-interrupted
- voice-input
- workflow.node.started
- assistant.started
example:
- conversation-update
- function-call
- hang
- model-output
- speech-update
- status-update
- transfer-update
- transcript
- tool-calls
- user-interrupted
- voice-input
- workflow.node.started
- assistant.started
description: These are the messages that will be sent to your Client SDKs. Default is conversation-update,function-call,hang,model-output,speech-update,status-update,transfer-update,transcript,tool-calls,user-interrupted,voice-input,workflow.node.started,assistant.started. You can check the shape of the messages in ClientMessage schema.
items:
type: string
enum:
- conversation-update
- assistant.speechStarted
- function-call
- function-call-result
- hang
- language-changed
- metadata
- model-output
- speech-update
- status-update
- transcript
- tool-calls
- tool-calls-result
- tool.completed
- transfer-update
- user-interrupted
- voice-input
- workflow.node.started
- assistant.started
serverMessages:
type: array
enum:
- assistant.started
- assistant.speechStarted
- conversation-update
- end-of-call-report
- function-call
- hang
- language-changed
- language-change-detected
- model-output
- phone-call-control
- speech-update
- status-update
- transcript
- transcript[transcriptType="final"]
- tool-calls
- transfer-destination-request
- handoff-destination-request
- transfer-update
- user-interrupted
- voice-input
- chat.created
- chat.deleted
- session.created
- session.updated
- session.deleted
- call.deleted
- call.delete.failed
example:
- conversation-update
- end-of-call-report
- function-call
- hang
- speech-update
- status-update
- tool-calls
- transfer-destination-request
- handoff-destination-request
- user-interrupted
- assistant.started
description: These are the messages that will be sent to your Server URL. Default is conversation-update,end-of-call-report,function-call,hang,speech-update,status-update,tool-calls,transfer-destination-request,handoff-destination-request,user-interrupted,assistant.started. You can check the shape of the messages in ServerMessage schema.
items:
type: string
enum:
- assistant.started
- assistant.speechStarted
- conversation-update
- end-of-call-report
- function-call
- hang
- language-changed
- language-change-detected
- model-output
- phone-call-control
- speech-update
- status-update
- transcript
- transcript[transcriptType="final"]
- tool-calls
- transfer-destination-request
- handoff-destination-request
- transfer-update
- user-interrupted
- voice-input
- chat.created
- chat.deleted
- session.created
- session.updated
- session.deleted
- call.deleted
- call.delete.failed
maxDurationSeconds:
type: number
description: 'This is the maximum number of seconds that the call will last. When the call reaches this duration, it will be ended.
@default 600 (10 minutes)'
minimum: 10
maximum: 43200
example: 600
backgroundSound:
description: 'This is the background sound in the call. Default for phone calls is ''office'' and default for web calls is ''off''.
You can also provide a custom sound by providing a URL to an audio file.'
oneOf:
- type: string
enum:
- 'off'
- office
example: office
- type: string
format: uri
example: https://www.soundjay.com/ambient/sounds/people-in-lounge-1.mp3
modelOutputInMessagesEnabled:
type: boolean
description: 'This determines whether the model''s output is used in conversation history rather than the transcription of assistant''s speech.
@default false'
example: false
transportConfigurations:
type: array
description: These are the configurations to be passed to the transport providers of assistant's calls, like Twilio. You can store multiple configurations for different transport providers. For a call, only the configuration matching the call transport provider is used.
items:
oneOf:
- $ref: '#/components/schemas/TransportConfigurationTwilio'
title: Twilio
observabilityPlan:
description: 'This is the plan for observability of assistant''s calls.
Currently, only Langfuse is supported.'
oneOf:
- $ref: '#/components/schemas/LangfuseObservabilityPlan'
title: Langfuse
allOf:
- $ref: '#/components/schemas/LangfuseObservabilityPlan'
credentials:
type: array
description: These are dynamic credentials that will be used for the assistant calls. By default, all the credentials are available for use in the call but you can supplement an additional credentials using this. Dynamic credentials override existing credentials.
items:
oneOf:
- $ref: '#/components/schemas/CreateAnthropicCredentialDTO'
title: AnthropicCredential
- $ref: '#/components/schemas/CreateAnthropicBedrockCredentialDTO'
title: AnthropicBedrockCredential
- $ref: '#/components/schemas/CreateAnyscaleCredentialDTO'
title: AnyscaleCredential
- $ref: '#/components/schemas/CreateAssemblyAICredentialDTO'
title: AssemblyAICredential
- $ref: '#/components/schemas/CreateAzureCredentialDTO'
title: AzureCredential
- $ref: '#/components/schemas/CreateAzureOpenAICredentialDTO'
title: AzureOpenAICredential
- $ref: '#/components/schemas/CreateByoSipTrunkCredentialDTO'
title: ByoSipTrunkCredential
- $ref: '#/components/schemas/CreateCartesiaCredentialDTO'
title: CartesiaCredential
- $ref: '#/components/schemas/CreateCerebrasCredentialDTO'
title: CerebrasCredential
- $ref: '#/components/schemas/CreateCloudflareCredentialDTO'
title: CloudflareCredential
- $ref: '#/components/schemas/CreateCustomLLMCredentialDTO'
title: CustomLLMCredential
- $ref: '#/components/schemas/CreateDeepgramCredentialDTO'
title: DeepgramCredential
- $ref: '#/components/schemas/CreateDeepInfraCredentialDTO'
title: DeepInfraCredential
- $ref: '#/components/schemas/CreateDeepSeekCredentialDTO'
title: DeepSeekCredential
- $ref: '#/components/schemas/CreateElevenLabsCredentialDTO'
title: ElevenLabsCredential
- $ref: '#/components/schemas/CreateGcpCredentialDTO'
title: GcpCredential
- $ref: '#/components/schemas/CreateGladiaCredentialDTO'
title: GladiaCredential
- $ref: '#/components/schemas/CreateGoHighLevelCredentialDTO'
title: GhlCredential
- $ref: '#/components/schemas/CreateGoogleCredentialDTO'
title: GoogleCredential
- $ref: '#/components/schemas/CreateGroqCredentialDTO'
title: GroqCredential
- $ref: '#/components/schemas/CreateHumeCredentialDTO'
title: HumeCredential
- $ref: '#/components/schemas/CreateInflectionAICredentialDTO'
title: InflectionAICredential
- $ref: '#/components/schemas/CreateLangfuseCredentialDTO'
title: LangfuseCredential
- $ref: '#/components/schemas/CreateLmntCredentialDTO'
title: LmntCredential
- $ref: '#/components/schemas/CreateMakeCredentialDTO'
title: MakeCredential
- $ref: '#/components/schemas/CreateMistralCredentialDTO'
title: MistralCredential
- $ref: '#/components/schemas/CreateNeuphonicCredentialDTO'
title: NeuphonicCredential
- $ref: '#/components/schemas/CreateOpenAICredentialDTO'
title: OpenAICredential
- $ref: '#/components/schemas/CreateOpenRouterCredentialDTO'
title: OpenRouterCredential
- $ref: '#/components/schemas/CreatePerplexityAICredentialDTO'
title: PerplexityAICredential
- $ref: '#/components/schemas/CreatePlayHTCredentialDTO'
title: PlayHTCredential
- $ref: '#/components/schemas/CreateRimeAICredentialDTO'
title: RimeAICredential
- $ref: '#/components/schemas/CreateRunpodCredentialDTO'
title: RunpodCredential
- $ref: '#/components/schemas/CreateS3CredentialDTO'
title: S3Credential
- $ref: '#/components/schemas/CreateSmallestAICredentialDTO'
title: SmallestAICredential
- $ref: '#/components/schemas/CreateSpeechmaticsCredentialDTO'
title: SpeechmaticsCredential
- $ref: '#/components/schemas/CreateSonioxCredentialDTO'
title: SonioxCredential
- $ref: '#/components/schemas/CreateSupabaseCredentialDTO'
title: SupabaseCredential
- $ref: '#/components/schemas/CreateTavusCredentialDTO'
title: TavusCredential
- $ref: '#/components/schemas/CreateTogetherAICredentialDTO'
title: TogetherAICredential
- $ref: '#/components/schemas/CreateTwilioCredentialDTO'
title: TwilioCredential
- $ref: '#/components/schemas/CreateVonageCredentialDTO'
title: VonageCredential
- $ref: '#/components/schemas/CreateWebhookCredentialDTO'
title: WebhookCredential
- $ref: '#/components/schemas/CreateCustomCredentialDTO'
title: CustomCredential
- $ref: '#/components/schemas/CreateXAiCredentialDTO'
title: XAiCredential
- $ref: '#/components/schemas/CreateGoogleCalendarOAuth2ClientCredentialDTO'
title: GoogleCalendarOAuth2ClientCredential
- $ref: '#/components/schemas/CreateGoogleCalendarOAuth2AuthorizationCredentialDTO'
title: GoogleCalendarOAuth2AuthorizationCredential
- $ref: '#/components/schemas/CreateGoogleSheetsOAuth2AuthorizationCredentialDTO'
title: GoogleSheetsOAuth2AuthorizationCredential
- $ref: '#/components/schemas/CreateSlackOAuth2AuthorizationCredentialDTO'
title: SlackOAuth2AuthorizationCredential
- $ref: '#/components/schemas/CreateGoHighLevelMCPCredentialDTO'
title: GoHighLevelMCPCredential
- $ref: '#/components/schemas/CreateInworldCredentialDTO'
title: InworldCredential
- $ref: '#/components/schemas/CreateMinimaxCredentialDTO'
title: MinimaxCredential
- $ref: '#/components/schemas/CreateWellSaidCredentialDTO'
title: WellSaidCredential
- $ref: '#/components/schemas/CreateEmailCredentialDTO'
title: EmailCredential
- $ref: '#/components/schemas/CreateSlackWebhookCredentialDTO'
title: SlackWebhookCredential
discriminator:
# --- truncated at 32 KB (737 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vapi/refs/heads/main/openapi/vapi-sessions-api-openapi.yml