Amazon Q Q Documents API

openapi: 3.2.0
info:
  title: QBusiness Documents API
  version: '2023-11-27'
  description: Generated from AWS's published Smithy model for QBusiness. 3 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: Documents
paths:
  /applications/{applicationId}/indices/{indexId}/documents/delete:
    post:
      operationId: BatchDeleteDocument
      summary: Batch Delete Document
      description: Asynchronously deletes one or more documents added using the BatchPutDocument API from an Amazon Q Business index. You can see the progress of the deletion, and any error messages related to the process, by using CloudWatch.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchDeleteDocumentResponse'
        '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/BatchDeleteDocumentRequest'
      tags:
      - Documents
  /applications/{applicationId}/indices/{indexId}/documents:
    post:
      operationId: BatchPutDocument
      summary: Batch Put Document
      description: 'Adds one or more documents to an Amazon Q Business index. You use this API to: ingest your structured and unstructured documents and documents stored in an Amazon S3 bucket into an Amazon Q Business index. add custom attributes to documents in an Amazon Q Business index. attach an access control list to the documents added to an Amazon Q Business index. You can see the progress of the deletion, and any error messages related to the process, by using CloudWatch.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPutDocumentResponse'
        '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/BatchPutDocumentRequest'
      tags:
      - Documents
  /applications/{applicationId}/index/{indexId}/documents:
    get:
      operationId: ListDocuments
      summary: List Documents
      description: A list of documents attached to an index.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDocumentsResponse'
        '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/ListDocumentsRequest'
      tags:
      - Documents
components:
  schemas:
    PrincipalGroup:
      type: object
      properties:
        name:
          type: string
          description: The name of the group.
        access:
          type: string
          enum:
          - ALLOW
          - DENY
          description: Provides information about whether to allow or deny access to the principal.
        membershipType:
          type: string
          enum:
          - INDEX
          - DATASOURCE
          description: The type of group.
      required:
      - access
    ListDocumentsResponse:
      type: object
      properties:
        documentDetailList:
          type: array
          items:
            $ref: '#/components/schemas/DocumentDetails'
          description: A list of document details.
        nextToken:
          type: string
          description: If the maxResults response was incomplete because there is more data to retrieve, Amazon Q Business returns a pagination token in the response. You can use this pagination token to retrieve the next set of documents.
    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.
    FailedDocument:
      type: object
      properties:
        id:
          type: string
          description: The identifier of the document that couldn't be removed from the Amazon Q Business index.
        error:
          $ref: '#/components/schemas/ErrorDetail'
        dataSourceId:
          type: string
          description: The identifier of the Amazon Q Business data source connector that contains the failed document.
    BatchPutDocumentResponse:
      type: object
      properties:
        failedDocuments:
          type: array
          items:
            $ref: '#/components/schemas/FailedDocument'
          description: A list of documents that were not added to the Amazon Q Business index because the document failed a validation check. Each document contains an error message that indicates why the document couldn't be added to the index.
    AccessConfiguration:
      type: object
      properties:
        accessControls:
          type: array
          items:
            $ref: '#/components/schemas/AccessControl'
          description: A list of AccessControlList objects.
        memberRelation:
          type: string
          enum:
          - AND
          - OR
          description: Describes the member relation within the AccessControlList object.
      required:
      - accessControls
    InlineDocumentEnrichmentConfiguration:
      type: object
      properties:
        condition:
          $ref: '#/components/schemas/DocumentAttributeCondition'
        target:
          $ref: '#/components/schemas/DocumentAttributeTarget'
        documentContentOperator:
          type: string
          enum:
          - DELETE
          description: TRUE to delete content if the condition used for the target attribute is met.
    S3:
      type: object
      properties:
        bucket:
          type: string
          description: The name of the S3 bucket that contains the file.
        key:
          type: string
          description: The name of the file.
      required:
      - bucket
      - key
    DocumentAttribute:
      type: object
      properties:
        name:
          type: string
          description: The identifier for the attribute.
        value:
          $ref: '#/components/schemas/DocumentAttributeValue'
      required:
      - name
      - value
    BatchDeleteDocumentResponse:
      type: object
      properties:
        failedDocuments:
          type: array
          items:
            $ref: '#/components/schemas/FailedDocument'
          description: A list of documents that couldn't be removed from the Amazon Q Business index. Each entry contains an error message that indicates why the document couldn't be removed from the index.
    Principal:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/PrincipalUser'
        group:
          $ref: '#/components/schemas/PrincipalGroup'
      description: Exactly one member is set.
    Document:
      type: object
      properties:
        id:
          type: string
          description: The identifier of the document.
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/DocumentAttribute'
          description: Custom attributes to apply to the document for refining Amazon Q Business web experience responses.
        content:
          $ref: '#/components/schemas/DocumentContent'
        contentType:
          type: string
          enum:
          - PDF
          - HTML
          - MS_WORD
          - PLAIN_TEXT
          - PPT
          - RTF
          - XML
          - XSLT
          - MS_EXCEL
          - CSV
          - JSON
          - MD
          description: The file type of the document in the Blob field. If you want to index snippets or subsets of HTML documents instead of the entirety of the HTML documents, you add the HTML start and closing tags (<HTML>content</HTML>) around the content.
        title:
          type: string
          description: The title of the document.
        accessConfiguration:
          $ref: '#/components/schemas/AccessConfiguration'
        documentEnrichmentConfiguration:
          $ref: '#/components/schemas/DocumentEnrichmentConfiguration'
        mediaExtractionConfiguration:
          $ref: '#/components/schemas/MediaExtractionConfiguration'
      required:
      - id
    AccessControl:
      type: object
      properties:
        principals:
          type: array
          items:
            $ref: '#/components/schemas/Principal'
          description: 'Contains a list of principals, where a principal can be either a USER or a GROUP. Each principal can be have the following type of document access: ALLOW or DENY.'
        memberRelation:
          type: string
          enum:
          - AND
          - OR
          description: Describes the member relation within a principal list.
      required:
      - principals
    MediaExtractionConfiguration:
      type: object
      properties:
        imageExtractionConfiguration:
          $ref: '#/components/schemas/ImageExtractionConfiguration'
        audioExtractionConfiguration:
          $ref: '#/components/schemas/AudioExtractionConfiguration'
        videoExtractionConfiguration:
          $ref: '#/components/schemas/VideoExtractionConfiguration'
    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
    HookConfiguration:
      type: object
      properties:
        invocationCondition:
          $ref: '#/components/schemas/DocumentAttributeCondition'
        lambdaArn:
          type: string
          description: The Amazon Resource Name (ARN) of the Lambda function during ingestion. For more information, see Using Lambda functions for Amazon Q Business document enrichment.
        s3BucketName:
          type: string
          description: Stores the original, raw documents or the structured, parsed documents before and after altering them. For more information, see Data contracts for Lambda functions.
        roleArn:
          type: string
          description: The Amazon Resource Name (ARN) of a role with permission to run PreExtractionHookConfiguration and PostExtractionHookConfiguration for altering document metadata and content during the document ingestion process.
    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.
    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
    DocumentAttributeCondition:
      type: object
      properties:
        key:
          type: string
          description: The identifier of the document attribute used for the condition. For example, 'Source_URI' could be an identifier for the attribute or metadata field that contains source URIs associated with the documents. Amazon Q Business currently doesn't support _document_body as an attribute key used for the condition.
        operator:
          type: string
          enum:
          - GREATER_THAN
          - GREATER_THAN_OR_EQUALS
          - LESS_THAN
          - LESS_THAN_OR_EQUALS
          - EQUALS
          - NOT_EQUALS
          - CONTAINS
          - NOT_CONTAINS
          - EXISTS
          - NOT_EXISTS
          - BEGINS_WITH
          description: The identifier of the document attribute used for the condition. For example, 'Source_URI' could be an identifier for the attribute or metadata field that contains source URIs associated with the documents. Amazon Q Business currently does not support _document_body as an attribute key used for the condition.
        value:
          $ref: '#/components/schemas/DocumentAttributeValue'
      required:
      - key
      - operator
    ListDocumentsRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the application id the documents are attached to.
        indexId:
          type: string
          description: The identifier of the index the documents are attached to.
        dataSourceIds:
          type: array
          items:
            type: string
          description: The identifier of the data sources the documents are attached to.
        nextToken:
          type: string
          description: If the maxResults response was incomplete because there is more data to retrieve, Amazon Q Business returns a pagination token in the response. You can use this pagination token to retrieve the next set of documents.
        maxResults:
          type: integer
          description: The maximum number of documents to return.
      required:
      - applicationId
      - indexId
    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
    ThrottlingException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    DocumentDetails:
      type: object
      properties:
        documentId:
          type: string
          description: The identifier of the document.
        status:
          type: string
          enum:
          - RECEIVED
          - PROCESSING
          - INDEXED
          - UPDATED
          - FAILED
          - DELETING
          - DELETED
          - DOCUMENT_FAILED_TO_INDEX
          description: The current status of the document.
        error:
          $ref: '#/components/schemas/ErrorDetail'
        createdAt:
          type: string
          format: date-time
          description: The timestamp for when the document was created.
        updatedAt:
          type: string
          format: date-time
          description: The timestamp for when the document was last updated.
    VideoExtractionConfiguration:
      type: object
      properties:
        videoExtractionStatus:
          type: string
          enum:
          - ENABLED
          - DISABLED
          description: The status of video extraction (ENABLED or DISABLED) for processing video content from files.
      required:
      - videoExtractionStatus
    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
    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
    BatchDeleteDocumentRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the Amazon Q Business application.
        indexId:
          type: string
          description: The identifier of the Amazon Q Business index that contains the documents to delete.
        documents:
          type: array
          items:
            $ref: '#/components/schemas/DeleteDocument'
          description: Documents deleted from the Amazon Q Business index.
        dataSourceSyncId:
          type: string
          description: The identifier of the data source sync during which the documents were deleted.
      required:
      - applicationId
      - indexId
      - documents
    BatchPutDocumentRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the Amazon Q Business application.
        indexId:
          type: string
          description: The identifier of the Amazon Q Business index to add the documents to.
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
          description: One or more documents to add to the index. Ensure that the name of your document doesn't contain any confidential information. Amazon Q Business returns document names in chat responses and citations when relevant.
        roleArn:
          type: string
          description: The Amazon Resource Name (ARN) of an IAM role with permission to access your S3 bucket.
        dataSourceSyncId:
          type: string
          description: The identifier of the data source sync during which the documents were added.
      required:
      - applicationId
      - indexId
      - documents
    AudioExtractionConfiguration:
      type: object
      properties:
        audioExtractionStatus:
          type: string
          enum:
          - ENABLED
          - DISABLED
          description: The status of audio extraction (ENABLED or DISABLED) for processing audio content from files.
      required:
      - audioExtractionStatus
    ImageExtractionConfiguration:
      type: object
      properties:
        imageExtractionStatus:
          type: string
          enum:
          - ENABLED
          - DISABLED
          description: Specify whether to extract semantic meaning from images and visuals from documents.
      required:
      - imageExtractionStatus
    PrincipalUser:
      type: object
      properties:
        id:
          type: string
          description: The identifier of the user.
        access:
          type: string
          enum:
          - ALLOW
          - DENY
          description: Provides information about whether to allow or deny access to the principal.
        membershipType:
          type: string
          enum:
          - INDEX
          - DATASOURCE
          description: The type of group.
      required:
      - access
    DeleteDocument:
      type: object
      properties:
        documentId:
          type: string
          description: The identifier of the deleted document.
      required:
      - documentId
    DocumentContent:
      type: object
      properties:
        blob:
          type: string
          description: The contents of the document. Documents passed to the blob parameter must be base64 encoded. Your code might not need to encode the document file bytes if you're using an Amazon Web Services SDK to call Amazon Q Business APIs. If you are calling the Amazon Q Business endpoint directly using REST, you must base64 encode the contents before sending.
        s3:
          $ref: '#/components/schemas/S3'
      description: Exactly one member is set.
    DocumentEnrichmentConfiguration:
      type: object
      properties:
        inlineConfigurations:
          type: array
          items:
            $ref: '#/components/schemas/InlineDocumentEnrichmentConfiguration'
          description: Configuration information to alter document attributes or metadata fields and content when ingesting documents into Amazon Q Business.
        preExtractionHookConfiguration:
          $ref: '#/components/schemas/HookConfiguration'
        postExtractionHookConfiguration:
          $ref: '#/components/schemas/HookConfiguration'
    DocumentAttributeTarget:
      type: object
      properties:
        key:
          type: string
          description: The identifier of the target document attribute or metadata field. For example, 'Department' could be an identifier for the target attribute or metadata field that includes the department names associated with the documents.
        value:
          $ref: '#/components/schemas/DocumentAttributeValue'
        attributeValueOperator:
          type: string
          enum:
          - DELETE
          description: TRUE to delete the existing target value for your specified target attribute key. You cannot create a target value and set this to TRUE.
      required:
      - key
  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)