Amazon Q Conversations API

openapi: 3.2.0
info:
  title: Amazon Q Conversations API
  version: '1.0'
  description: 'Operations tagged Conversations across 2 of this provider''s published API definitions: amazon-q-openapi.yml, amazon-q-conversations-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://qbusiness.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
      description: AWS region
security:
- sigv4: []
tags:
- name: Conversations
paths:
  /applications/{applicationId}/conversations:
    get:
      operationId: ListConversations
      summary: List Conversations
      description: Lists one or more Amazon Q Business conversations.
      tags:
      - Conversations
      parameters:
      - name: applicationId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
    post:
      operationId: ChatSync
      summary: Chat Sync
      description: Starts or continues a synchronous Amazon Q Business conversation.
      tags:
      - Conversations
      parameters:
      - name: applicationId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userMessage:
                  type: string
                conversationId:
                  type: string
      responses:
        '200':
          description: Success
    servers:
    - url: https://qbusiness.{region}.amazonaws.com
      variables:
        region:
          default: us-east-1
          description: AWS region
  /applications/{applicationId}/conversations?sync:
    post:
      operationId: postApplicationsByApplicationIdConversations?sync
      summary: Chat Sync
      description: Starts or continues a non-streaming Amazon Q Business conversation.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSyncOutput'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '424':
          description: ExternalResourceException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalResourceException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '400':
          description: LicenseNotFoundException; ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseNotFoundException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatSyncInput'
      tags:
      - Conversations
      x-operation-id-source: normalized
      x-operation-id-original: ChatSync
    servers:
    - url: https://qbusiness.{region}.amazonaws.com
      variables:
        region:
          default: us-east-1
  /applications/{applicationId}/conversations/{conversationId}:
    delete:
      operationId: DeleteConversation
      summary: Delete Conversation
      description: Deletes an Amazon Q Business web experience conversation.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteConversationResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '400':
          description: LicenseNotFoundException; ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseNotFoundException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteConversationRequest'
      tags:
      - Conversations
    get:
      operationId: ListMessages
      summary: List Messages
      description: Gets a list of messages associated with an Amazon Q Business web experience.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMessagesResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '400':
          description: LicenseNotFoundException; ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseNotFoundException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListMessagesRequest'
      tags:
      - Conversations
    servers:
    - url: https://qbusiness.{region}.amazonaws.com
      variables:
        region:
          default: us-east-1
components:
  schemas:
    DeleteConversationResponse:
      type: object
      properties: {}
    ErrorDetail:
      type: object
      properties:
        errorMessage:
          type: string
          description: The message explaining the Amazon Q Business request error.
        errorCode:
          type: string
          enum:
          - InternalError
          - InvalidRequest
          - ResourceInactive
          - ResourceNotFound
          description: The code associated with the Amazon Q Business request error.
    AuthChallengeResponse:
      type: object
      properties:
        responseMap:
          type: object
          additionalProperties:
            type: string
          description: The mapping of key-value pairs in an authentication challenge response.
      required:
      - responseMap
    ConversationSource:
      type: object
      properties:
        conversationId:
          type: string
          description: The unique identifier of the Amazon Q Business conversation.
        attachmentId:
          type: string
          description: The unique identifier of the Amazon Q Business attachment.
      required:
      - conversationId
      - attachmentId
    ListMessagesRequest:
      type: object
      properties:
        conversationId:
          type: string
          description: The identifier of the Amazon Q Business web experience conversation.
        applicationId:
          type: string
          description: The identifier for the Amazon Q Business application.
        userId:
          type: string
          description: The identifier of the user involved in the Amazon Q Business web experience conversation.
        nextToken:
          type: string
          description: If the number of messages returned exceeds maxResults, Amazon Q Business returns a next token as a pagination token to retrieve the next set of messages.
        maxResults:
          type: integer
          description: The maximum number of messages to return.
      required:
      - conversationId
      - applicationId
    TextSegment:
      type: object
      properties:
        beginOffset:
          type: integer
          description: The zero-based location in the response string where the source attribution starts.
        endOffset:
          type: integer
          description: The zero-based location in the response string where the source attribution ends.
        snippetExcerpt:
          $ref: '#/components/schemas/SnippetExcerpt'
        mediaId:
          type: string
          description: The identifier of the media object associated with the text segment in the source attribution.
        mediaMimeType:
          type: string
          description: The MIME type (image/png) of the media object associated with the text segment in the source attribution.
        sourceDetails:
          $ref: '#/components/schemas/SourceDetails'
    PluginConfiguration:
      type: object
      properties:
        pluginId:
          type: string
          description: The identifier of the plugin you want to use.
      required:
      - pluginId
    SourceDetails:
      type: object
      properties:
        imageSourceDetails:
          $ref: '#/components/schemas/ImageSourceDetails'
        audioSourceDetails:
          $ref: '#/components/schemas/AudioSourceDetails'
        videoSourceDetails:
          $ref: '#/components/schemas/VideoSourceDetails'
      description: Exactly one member is set.
    DocumentAttribute:
      type: object
      properties:
        name:
          type: string
          description: The identifier for the attribute.
        value:
          $ref: '#/components/schemas/DocumentAttributeValue'
      required:
      - name
      - value
    VideoSourceDetails:
      type: object
      properties:
        mediaId:
          type: string
          description: Unique identifier for the video media file.
        mediaMimeType:
          type: string
          description: The MIME type of the video file (e.g., video/mp4, video/avi).
        startTimeMilliseconds:
          type: integer
          description: The starting timestamp in milliseconds for the relevant video segment.
        endTimeMilliseconds:
          type: integer
          description: The ending timestamp in milliseconds for the relevant video segment.
        videoExtractionType:
          type: string
          enum:
          - TRANSCRIPT
          - SUMMARY
          description: The type of video extraction performed on the content.
    SnippetExcerpt:
      type: object
      properties:
        text:
          type: string
          description: The relevant text excerpt from a source that was used to generate a citation text segment in an Amazon Q chat response.
    ActionExecution:
      type: object
      properties:
        pluginId:
          type: string
          description: The identifier of the plugin the action is attached to.
        payload:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ActionExecutionPayloadField'
          description: A mapping of field names to the field values in input that an end user provides to Amazon Q Business requests to perform their plugin action.
        payloadFieldNameSeparator:
          type: string
          description: A string used to retain information about the hierarchical contexts within an action execution event payload.
      required:
      - pluginId
      - payload
      - payloadFieldNameSeparator
    ActionReviewPayloadFieldAllowedValue:
      type: object
      properties:
        value:
          type: object
          description: The field value.
        displayValue:
          type: object
          description: The name of the field.
    ListMessagesResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          description: An array of information on one or more messages.
        nextToken:
          type: string
          description: If the response is truncated, Amazon Q Business returns this token, which you can use in a later request to list the next set of messages.
    LicenseNotFoundException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    ResourceNotFoundException:
      type: object
      properties:
        message:
          type: string
          description: The message describing a ResourceNotFoundException.
        resourceId:
          type: string
          description: The identifier of the resource affected.
        resourceType:
          type: string
          description: The type of the resource affected.
      required:
      - message
      - resourceId
      - resourceType
    AccessDeniedException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    InternalServerException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    AttachmentOutput:
      type: object
      properties:
        name:
          type: string
          description: The name of a file uploaded during chat.
        status:
          type: string
          enum:
          - FAILED
          - SUCCESS
          description: The status of a file uploaded during chat.
        error:
          $ref: '#/components/schemas/ErrorDetail'
        attachmentId:
          type: string
          description: The unique identifier of the Amazon Q Business attachment.
        conversationId:
          type: string
          description: The unique identifier of the Amazon Q Business conversation.
    AuthChallengeRequest:
      type: object
      properties:
        authorizationUrl:
          type: string
          description: The URL sent by Amazon Q Business to the third party authentication server to authenticate a custom plugin user through an OAuth protocol.
      required:
      - authorizationUrl
    ChatSyncOutput:
      type: object
      properties:
        conversationId:
          type: string
          description: The identifier of the Amazon Q Business conversation.
        systemMessage:
          type: string
          description: An AI-generated message in a conversation.
        systemMessageId:
          type: string
          description: The identifier of an Amazon Q Business AI generated message within the conversation.
        userMessageId:
          type: string
          description: The identifier of an Amazon Q Business end user text input message within the conversation.
        actionReview:
          $ref: '#/components/schemas/ActionReview'
        authChallengeRequest:
          $ref: '#/components/schemas/AuthChallengeRequest'
        sourceAttributions:
          type: array
          items:
            $ref: '#/components/schemas/SourceAttribution'
          description: The source documents used to generate the conversation response.
        failedAttachments:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentOutput'
          description: A list of files which failed to upload during chat.
    ExternalResourceException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    DocumentAttributeValue:
      type: object
      properties:
        stringValue:
          type: string
          description: A string.
        stringListValue:
          type: array
          items:
            type: string
          description: A list of strings.
        longValue:
          type: integer
          description: A long integer value.
        dateValue:
          type: string
          format: date-time
          description: A date expressed as an ISO 8601 string. It's important for the time zone to be included in the ISO 8601 date-time format. For example, 2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25th 2012 at 12:30PM (plus 10 seconds) in Central European Time.
      description: Exactly one member is set.
    AttributeFilter:
      type: object
      properties:
        andAllFilters:
          type: array
          items:
            $ref: '#/components/schemas/AttributeFilter'
          description: Performs a logical AND operation on all supplied filters.
        orAllFilters:
          type: array
          items:
            $ref: '#/components/schemas/AttributeFilter'
          description: Performs a logical OR operation on all supplied filters.
        notFilter:
          $ref: '#/components/schemas/AttributeFilter'
        equalsTo:
          $ref: '#/components/schemas/DocumentAttribute'
        containsAll:
          $ref: '#/components/schemas/DocumentAttribute'
        containsAny:
          $ref: '#/components/schemas/DocumentAttribute'
        greaterThan:
          $ref: '#/components/schemas/DocumentAttribute'
        greaterThanOrEquals:
          $ref: '#/components/schemas/DocumentAttribute'
        lessThan:
          $ref: '#/components/schemas/DocumentAttribute'
        lessThanOrEquals:
          $ref: '#/components/schemas/DocumentAttribute'
    AudioSourceDetails:
      type: object
      properties:
        mediaId:
          type: string
          description: Unique identifier for the audio media file.
        mediaMimeType:
          type: string
          description: The MIME type of the audio file (e.g., audio/mp3, audio/wav).
        startTimeMilliseconds:
          type: integer
          description: The starting timestamp in milliseconds for the relevant audio segment.
        endTimeMilliseconds:
          type: integer
          description: The ending timestamp in milliseconds for the relevant audio segment.
        audioExtractionType:
          type: string
          enum:
          - TRANSCRIPT
          - SUMMARY
          description: The type of audio extraction performed on the content.
    SourceAttribution:
      type: object
      properties:
        title:
          type: string
          description: The title of the document which is the source for the Amazon Q Business generated response.
        snippet:
          type: string
          description: The content extract from the document on which the generated response is based.
        url:
          type: string
          description: The URL of the document which is the source for the Amazon Q Business generated response.
        citationNumber:
          type: integer
          description: The number attached to a citation in an Amazon Q Business generated response.
        updatedAt:
          type: string
          format: date-time
          description: The Unix timestamp when the Amazon Q Business application was last updated.
        textMessageSegments:
          type: array
          items:
            $ref: '#/components/schemas/TextSegment'
          description: A text extract from a source document that is used for source attribution.
        documentId:
          type: string
          description: The unique identifier of the source document used in the citation, obtained from the Amazon Q Business index during chat response generation. This ID is used as input to the GetDocumentContent API to retrieve the actual document content for user verification.
        indexId:
          type: string
          description: The identifier of the index containing the source document's metadata and access control information. This links the citation back to the specific Amazon Q Business index where the document's searchable content and permissions are stored.
        datasourceId:
          type: string
          description: The identifier of the data source from which the document was ingested. This field is not present if the document is ingested by directly calling the BatchPutDocument API (similar to checkDocumentAccess). If the document is from a file-upload data source, the datasource will be "uploaded-docs-file-stat-datasourceid".
    ThrottlingException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    ConflictException:
      type: object
      properties:
        message:
          type: string
          description: The message describing a ConflictException.
        resourceId:
          type: string
          description: The identifier of the resource affected.
        resourceType:
          type: string
          description: The type of the resource affected.
      required:
      - message
      - resourceId
      - resourceType
    ActionExecutionPayloadField:
      type: object
      properties:
        value:
          type: object
          description: The content of a user input field in an plugin action execution payload.
      required:
      - value
    ActionReview:
      type: object
      properties:
        pluginId:
          type: string
          description: The identifier of the plugin associated with the action review.
        pluginType:
          type: string
          enum:
          - SERVICE_NOW
          - SALESFORCE
          - JIRA
          - ZENDESK
          - CUSTOM
          - QUICKSIGHT
          - SERVICENOW_NOW_PLATFORM
          - JIRA_CLOUD
          - SALESFORCE_CRM
          - ZENDESK_SUITE
          - ATLASSIAN_CONFLUENCE
          - GOOGLE_CALENDAR
          - MICROSOFT_TEAMS
          - MICROSOFT_EXCHANGE
          - PAGERDUTY_ADVANCE
          - SMARTSHEET
          - ASANA
          description: The type of plugin.
        payload:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ActionReviewPayloadField'
          description: Field values that an end user needs to provide to Amazon Q Business for Amazon Q Business to perform the requested plugin action.
        payloadFieldNameSeparator:
          type: string
          description: A string used to retain information about the hierarchical contexts within an action review payload.
    ActionReviewPayloadField:
      type: object
      properties:
        displayName:
          type: string
          description: The name of the field.
        displayOrder:
          type: integer
          description: The display order of fields in a payload.
        displayDescription:
          type: string
          description: The field level description of each action review input field. This could be an explanation of the field. In the Amazon Q Business web experience, these descriptions could be used to display as tool tips to help users understand the field.
        type:
          type: string
          enum:
          - STRING
          - NUMBER
          - ARRAY
          - BOOLEAN
          description: The type of field.
        value:
          type: object
          description: The field value.
        allowedValues:
          type: array
          items:
            $ref: '#/components/schemas/ActionReviewPayloadFieldAllowedValue'
          description: Information about the field values that an end user can use to provide to Amazon Q Business for Amazon Q Business to perform the requested plugin action.
        allowedFormat:
          type: string
          description: The expected data format for the action review input field value. For example, in PTO request, from and to would be of datetime allowed format.
        arrayItemJsonSchema:
          type: object
          description: Use to create a custom form with array fields (fields with nested objects inside an array).
        required:
          type: boolean
          description: Information about whether the field is required.
    Message:
      type: object
      properties:
        messageId:
          type: string
          description: The identifier of the Amazon Q Business web experience message.
        body:
          type: string
          description: The content of the Amazon Q Business web experience message.
        time:
          type: string
          format: date-time
          description: The timestamp of the first Amazon Q Business web experience message.
        type:
          type: string
          enum:
          - USER
          - SYSTEM
          description: The type of Amazon Q Business message, whether HUMAN or AI generated.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentOutput'
          description: A file directly uploaded into an Amazon Q Business web experience chat.
        sourceAttribution:
          type: array
          items:
            $ref: '#/components/schemas/SourceAttribution'
          description: The source documents used to generate Amazon Q Business web experience message.
        actionReview:
          $ref: '#/components/schemas/ActionReview'
        actionExecution:
          $ref: '#/components/schemas/ActionExecution'
    ChatSyncInput:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the Amazon Q Business application linked to the Amazon Q Business conversation.
        userId:
          type: string
          description: The identifier of the user attached to the chat input.
        userGroups:
          type: array
          items:
            type: string
          description: The group names that a user associated with the chat input belongs to.
        userMessage:
          type: string
          description: A end user message in a conversation.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentInput'
          description: A list of files uploaded directly during chat. You can upload a maximum of 5 files of upto 10 MB each.
        actionExecution:
          $ref: '#/components/schemas/ActionExecution'
        authChallengeResponse:
          $ref: '#/components/schemas/AuthChallengeResponse'
        conversationId:
          type: string
          description: The identifier of the Amazon Q Business conversation.
        parentMessageId:
          type: string
          description: The identifier of the previous system message in a conversation.
        attributeFilter:
          $ref: '#/components/schemas/AttributeFilter'
        chatMode:
          type: string
          enum:
          - RETRIEVAL_MODE
          - CREATOR_MODE
          - PLUGIN_MODE
          description: 'The chatMode parameter determines the chat modes available to Amazon Q Business users: RETRIEVAL_MODE - If you choose this mode, Amazon Q generates responses solely from the data sources connected and indexed by the application. If an answer is not found in the data sources or there are no data sources available, Amazon Q will respond with a "No Answer Found" message, unless LLM knowledge has been enabled. In that case, Amazon Q will generate a response from the LLM knowledge CREATOR_MODE - By selecting this mode, you can choose to generate responses only from the LLM knowledge. You can also a'
        chatModeConfiguration:
          $ref: '#/components/schemas/ChatModeConfiguration'
        clientToken:
          type: string
          description: A token that you provide to identify a chat request.
      required:
      - applicationId
    CopyFromSource:
      type: object
      properties:
        conversation:
          $ref: '#/components/schemas/ConversationSource'
      description: Exactly one member is set.
    DeleteConversationRequest:
      type: object
      properties:
        conversationId:
          type: string
          description: The identifier of the Amazon Q Business web experience conversation being deleted.
        applicationId:
          type: string
          description: The identifier of the Amazon Q Business application associated with the conversation.
        userId:
          type: string
          description: The identifier of the user who is deleting the conversation.
      required:
      - conversationId
      - applicationId
    AttachmentInput:
      type: object
      properties:
        data:
          type: string
          format: byte
          description: The contents of the attachment.
        name:
          type: string
          description: The filename of the attachment.
        copyFrom:
          $ref: '#/components/schemas/CopyFromSource'
    ChatModeConfiguration:
      type: object
      properties:
        pluginConfiguration:
          $ref: '#/components/schemas/PluginConfiguration'
      description: Exactly one member is set.
    ImageSourceDetails:
      type: object
      properties:
        mediaId:
          type: string
          description: Unique identifier for the image file.
        mediaMimeType:
          type: string
          description: The MIME type of the image file.
  securitySchemes:
    sigv4:
      type: apiKey
      name: Authorization
      in: header
      description: AWS Signature Version 4
x-refined-from:
- amazon-q-openapi.yml
- amazon-q-conversations-api-openapi.yml