Amazon Lex Runtime V2 API

openapi: 3.1.0
info:
  title: Amazon Lex Runtime V2 API
  description: Amazon Lex V2 Runtime operations send user input to a built bot and manage the conversation
    session — RecognizeText, RecognizeUtterance, StartConversation, and session state. Derived mechanically
    from the AWS-published Smithy 2.0 service model (aws/api-models-aws, models/lex-runtime-v2/service/2020-08-07).
    Requests are signed with AWS Signature Version 4 using service name lex.
  version: '2020-08-07'
  contact:
    name: AWS Support
    url: https://aws.amazon.com/premiumsupport/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-generated-from: AWS Smithy 2.0 service model (https://github.com/aws/api-models-aws) — mechanical
    transform, no hand-authored operations
servers:
- url: https://runtime-v2-lex.us-east-1.amazonaws.com
  description: Amazon Lex V2 Runtime endpoint (us-east-1; one regional endpoint per AWS Region — see https://docs.aws.amazon.com/general/latest/gr/lex.html)
tags:
- name: bots
security:
- sigv4: []
paths:
  /bots/{botId}/botAliases/{botAliasId}/botLocales/{localeId}/sessions/{sessionId}:
    delete:
      operationId: DeleteSession
      summary: Removes session information for a specified bot, alias, and user ID.
      description: Removes session information for a specified bot, alias, and user ID. You can use this
        operation to restart a conversation with a bot. When you remove a session, the entire history
        of the session is removed so that you can start again. You don't need to delete a session. Sessions
        have a time limit and will expire. Set the session time limit when you create the bot. The default
        is 5 minutes, but you can specify anything between 1 minute and 24 hours. If you specify a bot
        or alias ID that doesn't exist, you receive a BadRequestException. If the locale doesn't exist
        in the bot, or if the locale hasn't been enables for the alias, you receive a BadRequestException.
      tags:
      - bots
      parameters:
      - name: botId
        in: path
        required: true
        description: The identifier of the bot that contains the session data.
        schema:
          type: string
          minLength: 10
          maxLength: 10
          pattern: ^[0-9a-zA-Z]+$
      - name: botAliasId
        in: path
        required: true
        description: The alias identifier in use for the bot that contains the session data.
        schema:
          type: string
      - name: localeId
        in: path
        required: true
        description: The locale where the session is in use.
        schema:
          type: string
          minLength: 1
      - name: sessionId
        in: path
        required: true
        description: The identifier of the session to delete.
        schema:
          type: string
          minLength: 2
          maxLength: 100
          pattern: ^[0-9a-zA-Z._:-]+$
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteSessionResponse'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
    get:
      operationId: GetSession
      summary: Returns session information for a specified bot, alias, and user.
      description: Returns session information for a specified bot, alias, and user. For example, you
        can use this operation to retrieve session information for a user that has left a long-running
        session in use. If the bot, alias, or session identifier doesn't exist, Amazon Lex V2 returns
        a BadRequestException. If the locale doesn't exist or is not enabled for the alias, you receive
        a BadRequestException.
      tags:
      - bots
      parameters:
      - name: botId
        in: path
        required: true
        description: The identifier of the bot that contains the session data.
        schema:
          type: string
          minLength: 10
          maxLength: 10
          pattern: ^[0-9a-zA-Z]+$
      - name: botAliasId
        in: path
        required: true
        description: The alias identifier in use for the bot that contains the session data.
        schema:
          type: string
      - name: localeId
        in: path
        required: true
        description: The locale where the session is in use.
        schema:
          type: string
          minLength: 1
      - name: sessionId
        in: path
        required: true
        description: The identifier of the session to return.
        schema:
          type: string
          minLength: 2
          maxLength: 100
          pattern: ^[0-9a-zA-Z._:-]+$
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSessionResponse'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
    post:
      operationId: PutSession
      summary: Creates a new session or modifies an existing session with an Amazon Lex V2 bot.
      description: Creates a new session or modifies an existing session with an Amazon Lex V2 bot. Use
        this operation to enable your application to set the state of the bot.
      tags:
      - bots
      parameters:
      - name: botId
        in: path
        required: true
        description: The identifier of the bot that receives the session data.
        schema:
          type: string
          minLength: 10
          maxLength: 10
          pattern: ^[0-9a-zA-Z]+$
      - name: botAliasId
        in: path
        required: true
        description: The alias identifier of the bot that receives the session data.
        schema:
          type: string
      - name: localeId
        in: path
        required: true
        description: The locale where the session is in use.
        schema:
          type: string
          minLength: 1
      - name: sessionId
        in: path
        required: true
        description: The identifier of the session that receives the session data.
        schema:
          type: string
          minLength: 2
          maxLength: 100
          pattern: ^[0-9a-zA-Z._:-]+$
      - name: ResponseContentType
        in: header
        required: false
        description: The message that Amazon Lex V2 returns in the response can be either text or speech
          depending on the value of this parameter. If the value is text/plain; charset=utf-8, Amazon
          Lex V2 returns text in the response.
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                messages:
                  type: array
                  items:
                    $ref: '#/components/schemas/Message'
                sessionState:
                  $ref: '#/components/schemas/SessionState'
                requestAttributes:
                  type: object
                  additionalProperties:
                    type: string
              required:
              - sessionState
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutSessionResponse'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '424':
          description: DependencyFailedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DependencyFailedException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '502':
          description: BadGatewayException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayException'
  /bots/{botId}/botAliases/{botAliasId}/botLocales/{localeId}/sessions/{sessionId}/conversation:
    post:
      operationId: StartConversation
      summary: Starts an HTTP/2 bidirectional event stream that enables you to send audio, text, or DTMF
        input in real time.
      description: 'Starts an HTTP/2 bidirectional event stream that enables you to send audio, text,
        or DTMF input in real time. After your application starts a conversation, users send input to
        Amazon Lex V2 as a stream of events. Amazon Lex V2 processes the incoming events and responds
        with streaming text or audio events. Audio input must be in the following format: audio/lpcm sample-rate=8000
        sample-size-bits=16 channel-count=1; is-big-endian=false. If the optional post-fulfillment response
        is specified, the messages are returned as follows. For more information, see PostFulfillmentStatusSpecification.
        Success message - Returned if the Lambda function completes successfully and the intent state
        is fulfilled or ready fulfillment if the message is present. Failed message - The failed message
        is returned if the Lambda function throws an exception or if the Lambda function returns a failed
        intent state without a message. Timeout message - If you don''t configure a timeout message and
        a timeout, and the Lambda function doesn''t return within 30 seconds, the timeout message is returned.
        If you configure a timeout, the timeout message is returned when the period times out. For more
        information, see Completion message. If the optional update message is configured, it is played
        at the specified frequency while the Lambda function is running and the update message state is
        active. If the fulfillment update message is not active, the Lambda function runs with a 30 second
        timeout. For more information, see Update message The StartConversation operation is supported
        only in the following SDKs: AWS SDK for C++ AWS SDK for Java V2 AWS SDK for Ruby V3'
      tags:
      - bots
      parameters:
      - name: botId
        in: path
        required: true
        description: The identifier of the bot to process the request.
        schema:
          type: string
          minLength: 10
          maxLength: 10
          pattern: ^[0-9a-zA-Z]+$
      - name: botAliasId
        in: path
        required: true
        description: The alias identifier in use for the bot that processes the request.
        schema:
          type: string
      - name: localeId
        in: path
        required: true
        description: The locale where the session is in use.
        schema:
          type: string
          minLength: 1
      - name: sessionId
        in: path
        required: true
        description: The identifier of the user session that is having the conversation.
        schema:
          type: string
          minLength: 2
          maxLength: 100
          pattern: ^[0-9a-zA-Z._:-]+$
      - name: x-amz-lex-conversation-mode
        in: header
        required: false
        description: The conversation type that you are using the Amazon Lex V2. If the conversation mode
          is AUDIO you can send both audio and DTMF information. If the mode is TEXT you can only send
          text.
        schema:
          type: string
          enum:
          - AUDIO
          - TEXT
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartConversationRequestEventStream'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartConversationResponse'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
  /bots/{botId}/botAliases/{botAliasId}/botLocales/{localeId}/sessions/{sessionId}/text:
    post:
      operationId: RecognizeText
      summary: Sends user input to Amazon Lex V2.
      description: Sends user input to Amazon Lex V2. Client applications use this API to send requests
        to Amazon Lex V2 at runtime. Amazon Lex V2 then interprets the user input using the machine learning
        model that it build for the bot. In response, Amazon Lex V2 returns the next message to convey
        to the user and an optional response card to display. If the optional post-fulfillment response
        is specified, the messages are returned as follows. For more information, see PostFulfillmentStatusSpecification.
        Success message - Returned if the Lambda function completes successfully and the intent state
        is fulfilled or ready fulfillment if the message is present. Failed message - The failed message
        is returned if the Lambda function throws an exception or if the Lambda function returns a failed
        intent state without a message. Timeout message - If you don't configure a timeout message and
        a timeout, and the Lambda function doesn't return within 30 seconds, the timeout message is returned.
        If you configure a timeout, the timeout message is returned when the period times out. For more
        information, see Completion message.
      tags:
      - bots
      parameters:
      - name: botId
        in: path
        required: true
        description: The identifier of the bot that processes the request.
        schema:
          type: string
          minLength: 10
          maxLength: 10
          pattern: ^[0-9a-zA-Z]+$
      - name: botAliasId
        in: path
        required: true
        description: The alias identifier in use for the bot that processes the request.
        schema:
          type: string
      - name: localeId
        in: path
        required: true
        description: The locale where the session is in use.
        schema:
          type: string
          minLength: 1
      - name: sessionId
        in: path
        required: true
        description: The identifier of the user session that is having the conversation.
        schema:
          type: string
          minLength: 2
          maxLength: 100
          pattern: ^[0-9a-zA-Z._:-]+$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  minLength: 1
                  maxLength: 1024
                  description: The text that the user entered. Amazon Lex V2 interprets this text.
                sessionState:
                  $ref: '#/components/schemas/SessionState'
                requestAttributes:
                  type: object
                  additionalProperties:
                    type: string
              required:
              - text
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecognizeTextResponse'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '424':
          description: DependencyFailedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DependencyFailedException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '502':
          description: BadGatewayException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayException'
  /bots/{botId}/botAliases/{botAliasId}/botLocales/{localeId}/sessions/{sessionId}/utterance:
    post:
      operationId: RecognizeUtterance
      summary: Sends user input to Amazon Lex V2.
      description: Sends user input to Amazon Lex V2. You can send text or speech. Clients use this API
        to send text and audio requests to Amazon Lex V2 at runtime. Amazon Lex V2 interprets the user
        input using the machine learning model built for the bot. The following request fields must be
        compressed with gzip and then base64 encoded before you send them to Amazon Lex V2. requestAttributes
        sessionState The following response fields are compressed using gzip and then base64 encoded by
        Amazon Lex V2. Before you can use these fields, you must decode and decompress them. inputTranscript
        interpretations messages requestAttributes sessionState The example contains a Java application
        that compresses and encodes a Java object to send to Amazon Lex V2, and a second that decodes
        and decompresses a response from Amazon Lex V2. If the optional post-fulfillment response is specified,
        the messages are returned as follows. For more information, see PostFulfillmentStatusSpecification.
        Success message - Returned if the Lambda function completes successfully and the intent state
        is fulfilled or ready fulfillment if the message is present. Failed message - The failed message
        is returned if the Lambda function throws an exception or if the Lambda function returns a failed
        intent state without a message. Timeout message - If you don't configure a timeout message and
        a timeout, and the Lambda function doesn't return within 30 seconds, the timeout message is returned.
        If you configure a timeout, the timeout message is returned when the period times out. For more
        information, see Completion message.
      tags:
      - bots
      parameters:
      - name: botId
        in: path
        required: true
        description: The identifier of the bot that should receive the request.
        schema:
          type: string
          minLength: 10
          maxLength: 10
          pattern: ^[0-9a-zA-Z]+$
      - name: botAliasId
        in: path
        required: true
        description: The alias identifier in use for the bot that should receive the request.
        schema:
          type: string
      - name: localeId
        in: path
        required: true
        description: The locale where the session is in use.
        schema:
          type: string
          minLength: 1
      - name: sessionId
        in: path
        required: true
        description: The identifier of the session in use.
        schema:
          type: string
          minLength: 2
          maxLength: 100
          pattern: ^[0-9a-zA-Z._:-]+$
      - name: x-amz-lex-session-state
        in: header
        required: false
        description: Sets the state of the session with the user. You can use this to set the current
          intent, attributes, context, and dialog action. Use the dialog action to determine the next
          step that Amazon Lex V2 should use in the conversation with the user. The sessionState field
          must be compressed using gzip and then base64 encoded before sending to Amazon Lex V2.
        schema:
          type: string
      - name: x-amz-lex-request-attributes
        in: header
        required: false
        description: 'Request-specific information passed between the client application and Amazon Lex
          V2 The namespace x-amz-lex: is reserved for special attributes. Don''t create any request attributes
          for prefix x-amz-lex:. The requestAttributes field must be compressed using gzip and then base64
          encoded before sending to Amazon Lex V2.'
        schema:
          type: string
      - name: Content-Type
        in: header
        required: true
        description: 'Indicates the format for audio input or that the content is text. The header must
          start with one of the following prefixes: PCM format, audio data must be in little-endian byte
          order. audio/l16; rate=16000; channels=1 audio/x-l16; sample-rate=16000; channel-count=1 audio/lpcm;
          sample-rate=8000; sample-size-bits=16; channel-count=1; is-big-endian=false Opus format audio/x-cbr-opus-with-preamble;preamble-size=0;bit-rate=256000;frame-size-milliseconds=4
          Text format text/plain; charset=utf-8'
        schema:
          type: string
          minLength: 1
      - name: Response-Content-Type
        in: header
        required: false
        description: 'The message that Amazon Lex V2 returns in the response can be either text or speech
          based on the responseContentType value. If the value is text/plain;charset=utf-8, Amazon Lex
          V2 returns text in the response. If the value begins with audio/, Amazon Lex V2 returns speech
          in the response. Amazon Lex V2 uses Amazon Polly to generate the speech using the configuration
          that you specified in the responseContentType parameter. For example, if you specify audio/mpeg
          as the value, Amazon Lex V2 returns speech in the MPEG format. If the value is audio/pcm, the
          speech returned is audio/pcm at 16 KHz in 16-bit, little-endian format. The following are the
          accepted values: audio/mpeg audio/ogg audio/pcm (16 KHz) audio/* (defaults to mpeg) text/plain;
          charset=utf-8'
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: string
              format: byte
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecognizeUtteranceResponse'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '424':
          description: DependencyFailedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DependencyFailedException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '502':
          description: BadGatewayException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayException'
components:
  securitySchemes:
    sigv4:
      type: apiKey
      name: Authorization
      in: header
      x-amazon-apigateway-authtype: awsSigv4
      description: AWS Signature Version 4. Sign requests with SigV4 using service name `lex` and the
        calling region.
  schemas:
    AccessDeniedException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    ActiveContext:
      type: object
      description: Contains information about the contexts that a user is using in a session. You can
        configure Amazon Lex V2 to set a context when an intent is fulfilled, or you can set a context
        using the , , or operations. Use a context to indicate to Amazon Lex V2 intents that should be
        used as follow-up intents. For example, if the active context is order-fulfilled, only intents
        that have order-fulfilled configured as a trigger are considered for follow up.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          pattern: ^([A-Za-z0-9]_?)+$
          description: The name of the context.
        timeToLive:
          $ref: '#/components/schemas/ActiveContextTimeToLive'
        contextAttributes:
          type: object
          additionalProperties:
            type: string
            minLength: 1
            maxLength: 1024
      required:
      - name
      - timeToLive
      - contextAttributes
    ActiveContextTimeToLive:
      type: object
      description: The time that a context is active. You can specify the time to live in seconds or in
        conversation turns.
      properties:
        timeToLiveInSeconds:
          type: integer
          minimum: 5
          maximum: 86400
          description: The number of seconds that the context is active. You can specify between 5 and
            86400 seconds (24 hours).
        turnsToLive:
          type: integer
          minimum: 1
          maximum: 20
          description: The number of turns that the context is active. You can specify up to 20 turns.
            Each request and response from the bot is a turn.
      required:
      - timeToLiveInSeconds
      - turnsToLive
    AudioInputEvent:
      type: object
      description: Represents a chunk of audio sent from the client application to Amazon Lex V2. The
        audio is all or part of an utterance from the user. Amazon Lex V2 accumulates audio chunks until
        it recognizes a natural pause in speech before processing the input.
      properties:
        audioChunk:
          type: string
          format: byte
          description: An encoded stream of audio.
        contentType:
          type: string
          minLength: 1
          description: 'The encoding used for the audio chunk. You must use 8 KHz PCM 16-bit mono-channel
            little-endian format. The value of the field should be: audio/lpcm; sample-rate=8000; sample-size-bits=16;
            channel-count=1; is-big-endian=false'
        eventId:
          type: string
          minLength: 2
          maxLength: 100
          pattern: ^[0-9a-zA-Z._:-]+$
          description: A unique identifier that your application assigns to the event. You can use this
            to identify events in logs.
        clientTimestampMillis:
          type: integer
          format: int64
          description: A timestamp set by the client of the date and time that the event was sent to Amazon
            Lex V2.
      required:
      - contentType
    AudioResponseEvent:
      type: object
      description: An event sent from Amazon Lex V2 to your client application containing audio to play
        to the user.
      properties:
        audioChunk:
          type: string
          format: byte
          description: A chunk of the audio to play.
        contentType:
          type: string
          minLength: 1
          description: The encoding of the audio chunk. This is the same as the encoding configure in
            the contentType field of the ConfigurationEvent.
        eventId:
          type: string
          minLength: 2
          maxLength: 100
          pattern: ^[0-9a-zA-Z._:-]+$
          description: A unique identifier of the event sent by Amazon Lex V2. The identifier is in the
            form RESPONSE-N, where N is a number starting with one and incremented for each event sent
            by Amazon Lex V2 in the current session.
    BadGatewayException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    Button:
      type: object
      description: A button that appears on a response card show to the user.
      properties:
        text:
          type: string
          minLength: 1
    

# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amazon-lex/refs/heads/main/openapi/amazon-lex-runtime-v2-openapi.yml