Amazon Q Q Retrievers API

openapi: 3.2.0
info:
  title: QBusiness Retrievers API
  version: '2023-11-27'
  description: Generated from AWS's published Smithy model for QBusiness. 5 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://qbusiness.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Retrievers
paths:
  /applications/{applicationId}/retrievers:
    post:
      operationId: CreateRetriever
      summary: Create Retriever
      description: Adds a retriever to your Amazon Q Business application.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateRetrieverResponse'
        '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'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '402':
          description: ServiceQuotaExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQuotaExceededException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRetrieverRequest'
      tags:
      - Retrievers
    get:
      operationId: ListRetrievers
      summary: List Retrievers
      description: Lists the retriever used by an Amazon Q Business application.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRetrieversResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListRetrieversRequest'
      tags:
      - Retrievers
  /applications/{applicationId}/retrievers/{retrieverId}:
    get:
      operationId: GetRetriever
      summary: Get Retriever
      description: Gets information about an existing retriever used by an Amazon Q Business application.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRetrieverResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetRetrieverRequest'
      tags:
      - Retrievers
    put:
      operationId: UpdateRetriever
      summary: Update Retriever
      description: Updates the retriever used for your Amazon Q Business application.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateRetrieverResponse'
        '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'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '402':
          description: ServiceQuotaExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQuotaExceededException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRetrieverRequest'
      tags:
      - Retrievers
    delete:
      operationId: DeleteRetriever
      summary: Delete Retriever
      description: Deletes the retriever used by an Amazon Q Business application.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteRetrieverResponse'
        '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'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteRetrieverRequest'
      tags:
      - Retrievers
components:
  schemas:
    NumberAttributeBoostingConfiguration:
      type: object
      properties:
        boostingLevel:
          type: string
          enum:
          - NONE
          - LOW
          - MEDIUM
          - HIGH
          - VERY_HIGH
          - ONE
          - TWO
          description: Specifies the priority of boosted document attributes in relation to other boosted attributes. This parameter determines how strongly the attribute influences document ranking in search results. NUMBER attributes can serve as additional boosting factors when needed, but are not supported when using NativeIndexConfiguration version 2.
        boostingType:
          type: string
          enum:
          - PRIORITIZE_LARGER_VALUES
          - PRIORITIZE_SMALLER_VALUES
          description: Specifies whether higher or lower numeric values should be prioritized when boosting. Valid values are ASCENDING (higher numbers are more important) and DESCENDING (lower numbers are more important).
      required:
      - boostingLevel
    Tag:
      type: object
      properties:
        key:
          type: string
          description: The key for the tag. Keys are not case sensitive and must be unique for the Amazon Q Business application or data source.
        value:
          type: string
          description: The value associated with the tag. The value may be an empty string but it can't be null.
      required:
      - key
      - value
    ListRetrieversRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the Amazon Q Business application using the retriever.
        nextToken:
          type: string
          description: If the number of retrievers returned exceeds maxResults, Amazon Q Business returns a next token as a pagination token to retrieve the next set of retrievers.
        maxResults:
          type: integer
          description: The maximum number of retrievers returned.
      required:
      - applicationId
    NativeIndexConfiguration:
      type: object
      properties:
        indexId:
          type: string
          description: The identifier for the Amazon Q Business index.
        version:
          type: integer
          description: 'A read-only field that specifies the version of the NativeIndexConfiguration. Amazon Q Business introduces enhanced document retrieval capabilities in version 2 of NativeIndexConfiguration, focusing on streamlined metadata boosting that prioritizes recency and source relevance to deliver more accurate responses to your queries. Version 2 has the following differences from version 1: Version 2 supports a single Date field (created_at OR last_updated_at) for recency boosting Version 2 supports a single String field with an ordered list of up to 5 values Version 2 introduces number-based boost le'
        boostingOverride:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DocumentAttributeBoostingConfiguration'
          description: Overrides the default boosts applied by Amazon Q Business to supported document attribute data types.
      required:
      - indexId
    DateAttributeBoostingConfiguration:
      type: object
      properties:
        boostingLevel:
          type: string
          enum:
          - NONE
          - LOW
          - MEDIUM
          - HIGH
          - VERY_HIGH
          - ONE
          - TWO
          description: Specifies the priority tier ranking of boosting applied to document attributes. For version 2, this parameter indicates the relative ranking between boosted fields (ONE being highest priority, TWO being second highest, etc.) and determines the order in which attributes influence document ranking in search results. For version 1, this parameter specifies the boosting intensity. For version 2, boosting intensity (VERY HIGH, HIGH, MEDIUM, LOW, NONE) are not supported. Note that in version 2, you are not allowed to boost on only one field and make this value TWO.
        boostingDurationInSeconds:
          type: integer
          description: Specifies the duration, in seconds, of a boost applies to a DATE type document attribute.
      required:
      - boostingLevel
    GetRetrieverRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the Amazon Q Business application using the retriever.
        retrieverId:
          type: string
          description: The identifier of the retriever.
      required:
      - applicationId
      - retrieverId
    CreateRetrieverRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of your Amazon Q Business application.
        type:
          type: string
          enum:
          - NATIVE_INDEX
          - KENDRA_INDEX
          description: The type of retriever you are using.
        displayName:
          type: string
          description: The name of your retriever.
        configuration:
          $ref: '#/components/schemas/RetrieverConfiguration'
        roleArn:
          type: string
          description: The ARN of an IAM role used by Amazon Q Business to access the basic authentication credentials stored in a Secrets Manager secret.
        clientToken:
          type: string
          description: A token that you provide to identify the request to create your Amazon Q Business application retriever.
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: 'A list of key-value pairs that identify or categorize the retriever. You can also use tags to help control access to the retriever. Tag keys and values can consist of Unicode letters, digits, white space, and any of the following symbols: _ . : / = + - @.'
      required:
      - applicationId
      - type
      - displayName
      - configuration
    DeleteRetrieverRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the Amazon Q Business application using the retriever.
        retrieverId:
          type: string
          description: The identifier of the retriever being deleted.
      required:
      - applicationId
      - retrieverId
    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
    DocumentAttributeBoostingConfiguration:
      type: object
      properties:
        numberConfiguration:
          $ref: '#/components/schemas/NumberAttributeBoostingConfiguration'
        stringConfiguration:
          $ref: '#/components/schemas/StringAttributeBoostingConfiguration'
        dateConfiguration:
          $ref: '#/components/schemas/DateAttributeBoostingConfiguration'
        stringListConfiguration:
          $ref: '#/components/schemas/StringListAttributeBoostingConfiguration'
      description: Exactly one member is set.
    StringListAttributeBoostingConfiguration:
      type: object
      properties:
        boostingLevel:
          type: string
          enum:
          - NONE
          - LOW
          - MEDIUM
          - HIGH
          - VERY_HIGH
          - ONE
          - TWO
          description: Specifies the priority of boosted document attributes in relation to other boosted attributes. This parameter determines how strongly the attribute influences document ranking in search results. STRING_LIST attributes can serve as additional boosting factors when needed, but are not supported when using NativeIndexConfiguration version 2.
      required:
      - boostingLevel
    Retriever:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the Amazon Q Business application using the retriever.
        retrieverId:
          type: string
          description: The identifier of the retriever used by your Amazon Q Business application.
        type:
          type: string
          enum:
          - NATIVE_INDEX
          - KENDRA_INDEX
          description: The type of your retriever.
        status:
          type: string
          enum:
          - CREATING
          - ACTIVE
          - FAILED
          description: The status of your retriever.
        displayName:
          type: string
          description: The name of your retriever.
    CreateRetrieverResponse:
      type: object
      properties:
        retrieverId:
          type: string
          description: The identifier of the retriever you are using.
        retrieverArn:
          type: string
          description: The Amazon Resource Name (ARN) of an IAM role associated with a retriever.
    ServiceQuotaExceededException:
      type: object
      properties:
        message:
          type: string
          description: The message describing a ServiceQuotaExceededException.
        resourceId:
          type: string
          description: The identifier of the resource affected.
        resourceType:
          type: string
          description: The type of the resource affected.
      required:
      - message
      - resourceId
      - resourceType
    UpdateRetrieverRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of your Amazon Q Business application.
        retrieverId:
          type: string
          description: The identifier of your retriever.
        configuration:
          $ref: '#/components/schemas/RetrieverConfiguration'
        displayName:
          type: string
          description: The name of your retriever.
        roleArn:
          type: string
          description: The Amazon Resource Name (ARN) of an IAM role with permission to access the retriever and required resources.
      required:
      - applicationId
      - retrieverId
    ThrottlingException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    ValidationExceptionField:
      type: object
      properties:
        name:
          type: string
          description: The field name where the invalid entry was detected.
        message:
          type: string
          description: A message about the validation exception.
      required:
      - name
      - message
    GetRetrieverResponse:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the Amazon Q Business application using the retriever.
        retrieverId:
          type: string
          description: The identifier of the retriever.
        retrieverArn:
          type: string
          description: The Amazon Resource Name (ARN) of the IAM role associated with the retriever.
        type:
          type: string
          enum:
          - NATIVE_INDEX
          - KENDRA_INDEX
          description: The type of the retriever.
        status:
          type: string
          enum:
          - CREATING
          - ACTIVE
          - FAILED
          description: The status of the retriever.
        displayName:
          type: string
          description: The name of the retriever.
        configuration:
          $ref: '#/components/schemas/RetrieverConfiguration'
        roleArn:
          type: string
          description: The Amazon Resource Name (ARN) of the role with the permission to access the retriever and required resources.
        createdAt:
          type: string
          format: date-time
          description: The Unix timestamp when the retriever was created.
        updatedAt:
          type: string
          format: date-time
          description: The Unix timestamp when the retriever was last updated.
    RetrieverConfiguration:
      type: object
      properties:
        nativeIndexConfiguration:
          $ref: '#/components/schemas/NativeIndexConfiguration'
        kendraIndexConfiguration:
          $ref: '#/components/schemas/KendraIndexConfiguration'
      description: Exactly one member is set.
    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
    ValidationException:
      type: object
      properties:
        message:
          type: string
          description: The message describing the ValidationException.
        reason:
          type: string
          enum:
          - CANNOT_PARSE
          - FIELD_VALIDATION_FAILED
          - UNKNOWN_OPERATION
          description: The reason for the ValidationException.
        fields:
          type: array
          items:
            $ref: '#/components/schemas/ValidationExceptionField'
          description: The input field(s) that failed validation.
      required:
      - message
      - reason
    UpdateRetrieverResponse:
      type: object
      properties: {}
    DeleteRetrieverResponse:
      type: object
      properties: {}
    StringAttributeBoostingConfiguration:
      type: object
      properties:
        boostingLevel:
          type: string
          enum:
          - NONE
          - LOW
          - MEDIUM
          - HIGH
          - VERY_HIGH
          - ONE
          - TWO
          description: Specifies the priority tier ranking of boosting applied to document attributes. For version 2, this parameter indicates the relative ranking between boosted fields (ONE being highest priority, TWO being second highest, etc.) and determines the order in which attributes influence document ranking in search results. For version 1, this parameter specifies the boosting intensity. For version 2, boosting intensity (VERY HIGH, HIGH, MEDIUM, LOW, NONE) are not supported. Note that in version 2, you are not allowed to boost on only one field and make this value TWO.
        attributeValueBoosting:
          type: object
          additionalProperties:
            type: string
            enum:
            - LOW
            - MEDIUM
            - HIGH
            - VERY_HIGH
            - ONE
            - TWO
            - THREE
            - FOUR
            - FIVE
          description: Specifies specific values of a STRING type document attribute being boosted. When using NativeIndexConfiguration version 2, you can specify up to five values in order of priority.
      required:
      - boostingLevel
    ListRetrieversResponse:
      type: object
      properties:
        retrievers:
          type: array
          items:
            $ref: '#/components/schemas/Retriever'
          description: An array of summary information for one or more retrievers.
        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 retrievers.
    KendraIndexConfiguration:
      type: object
      properties:
        indexId:
          type: string
          description: The identifier of the Amazon Kendra index.
      required:
      - indexId
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: qbusiness
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/qbusiness/service/2023-11-27/qbusiness-2023-11-27.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)