Vapi Sessions API

openapi: 3.2.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:
    FallbackCartesiaVoice:
      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:
          - cartesia
        voiceId:
          type: string
          description: The ID of the particular voice you want to use.
        model:
          type: string
          description: This is the model that will be used. This is optional and will default to the correct model for the voiceId.
          enum:
          - sonic-3
          - sonic-3-2026-01-12
          - sonic-3-2025-10-27
          - sonic-2
          - sonic-2-2025-06-11
          - sonic-english
          - sonic-multilingual
          - sonic-preview
          - sonic
          example: sonic-english
        language:
          type: string
          description: This is the language that will be used. This is optional and will default to the correct language for the voiceId.
          enum:
          - ar
          - bg
          - bn
          - cs
          - da
          - de
          - el
          - en
          - es
          - fi
          - fr
          - gu
          - he
          - hi
          - hr
          - hu
          - id
          - it
          - ja
          - ka
          - kn
          - ko
          - ml
          - mr
          - ms
          - nl
          - 'no'
          - pa
          - pl
          - pt
          - ro
          - ru
          - sk
          - sv
          - ta
          - te
          - th
          - tl
          - tr
          - uk
          - vi
          - zh
          example: en
        experimentalControls:
          description: Experimental controls for Cartesia voice generation
          allOf:
          - $ref: '#/components/schemas/CartesiaExperimentalControls'
        generationConfig:
          description: Generation config for fine-grained control of sonic-3 voice output (speed, volume, and experimental controls). Only available for sonic-3 model.
          allOf:
          - $ref: '#/components/schemas/CartesiaGenerationConfig'
        pronunciationDictId:
          type: string
          description: Pronunciation dictionary ID for sonic-3. Allows custom pronunciations for specific words. Only available for sonic-3 model.
          example: dict_abc123
        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
    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
    ImportTwilioPhoneNumberDTO:
      type: object
      properties:
        fallbackDestination:
          description: 'This is the fallback destination an inbound call will be transferred to if:

            1. `assistantId` is not set

            2. `squadId` is not set

            3. and, `assistant-request` message to the `serverUrl` fails


            If this is not set and above conditions are met, the inbound call is hung up with an error message.'
          oneOf:
          - $ref: '#/components/schemas/TransferDestinationNumber'
            title: NumberTransferDestination
          - $ref: '#/components/schemas/TransferDestinationSip'
            title: SipTransferDestination
        hooks:
          type: array
          description: This is the hooks that will be used for incoming calls to this phone number.
          items:
            oneOf:
            - $ref: '#/components/schemas/PhoneNumberHookCallRinging'
              title: PhoneNumberHookCallRinging
            - $ref: '#/components/schemas/PhoneNumberHookCallEnding'
              title: PhoneNumberHookCallEnding
        smsEnabled:
          type: boolean
          description: 'Controls whether Vapi sets the messaging webhook URL on the Twilio number during import.


            If set to `false`, Vapi will not update the Twilio messaging URL, leaving it as is.

            If `true` or omitted (default), Vapi will configure both the voice and messaging URLs.


            @default true'
          default: true
        twilioPhoneNumber:
          type: string
          description: These are the digits of the phone number you own on your Twilio.
          deprecated: true
        twilioAccountSid:
          type: string
          description: This is your Twilio Account SID that will be used to handle this phone number.
        twilioAuthToken:
          type: string
          description: This is the Twilio Auth Token that will be used to handle this phone number.
        twilioApiKey:
          type: string
          description: This is the Twilio API Key that will be used to handle this phone number. If AuthToken is provided, this will be ignored.
        twilioApiSecret:
          type: string
          description: This is the Twilio API Secret that will be used to handle this phone number. If AuthToken is provided, this will be ignored.
        name:
          type: string
          description: This is the name of the phone number. This is just for your own reference.
          maxLength: 40
        assistantId:
          type: string
          description: 'This is the assistant that will be used for incoming calls to this phone number.


            If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.'
        workflowId:
          type: string
          description: 'This is the workflow that will be used for incoming calls to this phone number.


            If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.'
        squadId:
          type: string
          description: 'This is the squad that will be used for incoming calls to this phone number.


            If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.'
        server:
          description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema.


            The order of precedence is:


            1. assistant.server

            2. phoneNumber.server

            3. org.server'
          allOf:
          - $ref: '#/components/schemas/Server'
      required:
      - twilioPhoneNumber
      - twilioAccountSid
    ArtifactPlan:
      type: object
      properties:
        recordingEnabled:
          type: boolean
          description: 'This determines whether assistant''s calls are recorded. Defaults to true.


            Usage:

            - If you don''t want to record the calls, set this to false.

            - If you want to record the calls when `assistant.hipaaEnabled` (deprecated) or `assistant.compliancePlan.hipaaEnabled` explicity set this to true and make sure to provide S3 or GCP credentials on the Provider Credentials page in the Dashboard.


            You can find the recording at `call.artifact.recordingUrl` and `call.artifact.stereoRecordingUrl` after the call is ended.


            @default true'
          example: true
        recordingFormat:
          type: string
          description: 'This determines the format of the recording. Defaults to `wav;l16`.


            @default ''wav;l16'''
          enum:
          - wav;l16
          - mp3
        recordingUseCustomStorageEnabled:
          type: boolean
          description: 'This determines whether to use custom storage (S3 or GCP) for call recordings when storage credentials are configured.


            When set to false, recordings will be stored on Vapi''s storage instead of your custom storage, even if you have custom storage credentials configured.


            Usage:

            - Set to false if you have custom storage configured but want to store recordings on Vapi''s storage for this assistant.

            - Set to true (or leave unset) to use your custom storage for recordings when available.


            @default true'
          example: true
        videoRecordingEnabled:
          type: boolean
          description: 'This determines whether the video is recorded during the call. Defaults to false. Only relevant for `webCall` type.


            You can find the video recording at `call.artifact.videoRecordingUrl` after the call is ended.


            @default false'
          example: false
        fullMessageHistoryEnabled:
          type: boolean
          description: This determines whether the artifact contains the full message history, even after handoff context engineering. Defaults to false.
          example: false
        pcapEnabled:
          type: boolean
          description: 'This determines whether the SIP packet capture is enabled. Defaults to true. Only relevant for `phone` type calls where phone number''s provider is `vapi` or `byo-phone-number`.


            You can find the packet capture at `call.artifact.pcapUrl` after the call is ended.


            @default true'
          example: true
        pcapS3PathPrefix:
          type: string
          description: 'This is the path where the SIP packet capture will be uploaded. This is only used if you have provided S3 or GCP credentials on the Provider Credentials page in the Dashboard.


            If credential.s3PathPrefix or credential.bucketPlan.path is set, this will append to it.


            Usage:

            - If you want to upload the packet capture to a specific path, set this to the path. Example: `/my-assistant-captures`.

            - If you want to upload the packet capture to the root of the bucket, set this to `/`.


            @default ''/'''
          example: /pcaps
        pcapUseCustomStorageEnabled:
          type: boolean
          description: 'This determines whether to use custom storage (S3 or GCP) for SIP packet captures when storage credentials are configured.


            When set to false, packet captures will be stored on Vapi''s storage instead of your custom storage, even if you have custom storage credentials configured.


            Usage:

            - Set to false if you have custom storage configured but want to store packet captures on Vapi''s storage for this assistant.

            - Set to true (or leave unset) to use your custom storage for packet captures when available.


            @default true'
          example: true
        loggingEnabled:
          type: boolean
          description: 'This determines whether the call logs are enabled. Defaults to true.


            @default true'
          example: true
        loggingUseCustomStorageEnabled:
          type: boolean
          description: 'This determines whether to use custom storage (S3 or GCP) for call logs when storage credentials are configured.


            When set to false, logs will be stored on Vapi''s storage instead of your custom storage, even if you have custom storage credentials configured.


            Usage:

            - Set to false if you have custom storage configured but want to store logs on Vapi''s storage for this assistant.

            - Set to true (or leave unset) to use your custom storage for logs when available.


            @default true'
          example: true
        transcriptPlan:
          description: This is the plan for `call.artifact.transcript`. To disable, set `transcriptPlan.enabled` to false.
          allOf:
          - $ref: '#/components/schemas/TranscriptPlan'
        recordingPath:
          type: string
          description: 'This is the path where the recording will be uploaded. This is only used if you have provided S3 or GCP credentials on the Provider Credentials page in the Dashboard.


            If credential.s3PathPrefix or credential.bucketPlan.path is set, this will append to it.


            Usage:

            - If you want to upload the recording to a specific path, set this to the path. Example: `/my-assistant-recordings`.

            - If you want to upload the recording to the root of the bucket, set this to `/`.


            @default ''/'''
        structuredOutputIds:
          description: 'This is an array of structured output IDs to be calculated during the call.

            The outputs will be extracted and stored in `call.artifact.structuredOutputs` after the call is ended.'
          type: array
          items:
            type: string
        structuredOutputs:
          description: 'This is an array of transient structured outputs to be calculated during the call.

            The outputs will be extracted and stored in `call.artifact.structuredOutputs` after the call is ended.

            Use this to provide inline structured output configurations instead of referencing existing ones via structuredOutputIds.'
          type: array
          items:
            $ref: '#/components/schemas/CreateStructuredOutputDTO'
        scorecardIds:
          description: 'This is an array of scorecard IDs that will be evaluated based on the structured outputs extracted during the call.

            The scorecards will be evaluated and the results will be stored in `call.artifact.scorecards` after the call has ended.'
          type: array
          items:
            type: string
        scorecards:
          description: 'This is the array of scorecards that will be evaluated based on the structured outputs extracted during the call.

            The scorecards will be evaluated and the results will be stored in `call.artifact.scorecards` after the call has ended.'
          type: array
          items:
            $ref: '#/components/schemas/CreateScorecardDTO'
        loggingPath:
          type: string
          description: 'This is the path where the call logs will be uploaded. This is only used if you have provided S3 or GCP credentials on the Provider Credentials page in the Dashboard.


            If credential.s3PathPrefix or credential.bucketPlan.path is set, this will append to it.


            Usage:

            - If you want to upload the call logs to a specific path, set this to the path. Example: `/my-assistant-logs`.

            - If you want to upload the call logs to the root of the bucket, set this to `/`.


            @default ''/'''
    SessionCreatedHook:
      type: object
      properties:
        'on':
          type: string
          description: This is the event that triggers this hook
          enum:
          - session.created
          maxLength: 1000
        do:
          type: array
          description: This is the set of actions to perform when the hook triggers.
          items:
            oneOf:
            - $ref: '#/components/schemas/ToolCallHookAction'
              title: ToolCallHookAction
        name:
          type: string
          description: 'Optional name for this hook instance.

            If no name is provided, the hook will be auto generated as UUID.


            @default UUID'
          maxLength: 1000
      required:
      - 'on'
      - do
    TurnLatency:
      type: object
      properties:
        modelLatency:
          type: number
          description: This is the model latency for the first token.
        voiceLatency:
          type: number
          description: This is the voice latency from the model output.
        transcriberLatency:
          type: number
          description: This is the transcriber latency from the user speech.
        endpointingLatency:
          type: number
          description: This is the endpointing latency.
        turnLatency:
          type: number
          description: This is the latency for the whole turn.
    FallbackWellSaidVoice:
      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'
      required:
      - provider
      - voiceId
    ToolRejectionPlan:
      type: object
      properties:
        conditions:
          type: array
          description: 'This is the list of conditions that must be evaluated.


            Usage:

            - If all conditions match (AND logic), the tool call is rejected.

            - For OR logic at the top level, use a single ''group'' condition with operator: ''OR''.


            @default [] - Empty array means tool always executes'
          examples:
          - '[{ type: "regex", regex: "(?i)\\b(cancel|stop)\\b", target: { role: "user" } }]'
          - '[{ type: "group", operator: "OR", conditions: [...] }]'
          items:
            oneOf:
            - $ref: '#/components/schemas/RegexCondition'
              title: RegexCondition
            - $ref: '#/components/schemas/LiquidCondition'
              title: LiquidCondition
            - $ref: '#/components/schemas/GroupCondition'
              title: GroupCondition
              description: This is the GroupCondition object but Swagger does not display nested schemas correctly.
    CreateCustomerDTO:
      type: object
      properties:
        numberE164CheckEnabled:
          type: boolean
          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)'
          default: true
        extension:
          type: string
          description: This is the extension that will be dialed after the call is answered.
          maxLength: 10
          example: null
        assistantOverrides:
          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'
        number:
          type: string
          description: This is the number of the customer.
          minLength: 3
          maxLength: 40
        sipUri:
          type: string
          description: This is the SIP URI of the customer.
        name:
          type: string
          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>`.'
          maxLength: 40
        email:
          type: string
          description: This is the email of the customer.
          maxLength: 40
        externalId:
          type: string
          description: This is the external ID of the customer.
          maxLength: 40
    SayHookAction:
      type: object
      properties:
        type:
          type: string
          description: This is the type of action - must be "say"
          enum:
          - say
        prompt:
          description: 'This is the prompt for the assistant to generate a response based on existing conversation.

            Can be a string or an array of chat messages.'
          oneOf:
          - type: string
            title: String
          - type: array
            items:
              oneOf:
              - $ref: '#/components/schemas/SystemMessage'
                title: SystemMessage
              - $ref: '#/components/schemas/UserMessage'
                title: UserMessage
              - $ref: '#/components/schemas/AssistantMessage'
                title: AssistantMessage
              - $ref: '#/components/schemas/ToolMessage'
                title: ToolMessage
              - $ref: '#/components/schemas/DeveloperMessage'
                title: DeveloperMessage
            title: MessageArray
          examples:
          - Ask the user if they're still in the call
          - - role: system
              content: You are a helpful assistant, and would like to know if the user is still in the call based on the conversation history in {{transcript}}
        exact:
          type: object
          description: This is the message to say
      required:
      - type
    CreateHumeCredentialDTO:
      type: object
      properties:
        provider:
          type: string
          enum:
          - hume
        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
    TransferFallbackPlan:
      type: object
      properties:
        message:
          description: This is the message the ass

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