Amazon Kendra Documents API

openapi: 3.2.0
info:
  title: Amazon Kendra Documents API
  version: '2019-02-03'
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  description: 'Operations tagged Documents across 2 of this provider''s published API definitions: amazon-kendra-openapi.yml, amazon-kendra-documents-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://kendra.{region}.amazonaws.com
  description: Amazon Kendra regional endpoint
  variables:
    region:
      default: us-east-1
      description: AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-2
      - eu-west-1
      - ap-southeast-1
      - ap-southeast-2
      - ap-northeast-1
security:
- sigv4: []
tags:
- name: Documents
  description: Operations for managing documents in the index
paths:
  /indexes/{IndexId}/documents:
    post:
      operationId: BatchPutDocument
      summary: Amazon Kendra Batch Put Document
      description: Adds one or more documents to an Amazon Kendra index.
      tags:
      - Documents
      parameters:
      - name: IndexId
        in: path
        required: true
        schema:
          type: string
        description: The identifier of the index.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - Documents
              properties:
                Documents:
                  type: array
                  description: One or more documents to add to the index.
      responses:
        '200':
          description: Success
        '400':
          description: Bad request - invalid input parameters
        '403':
          description: Access denied - insufficient permissions
        '500':
          description: Internal server error
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: BatchDeleteDocument
      summary: Amazon Kendra Batch Delete Document
      description: Removes one or more documents from an Amazon Kendra index.
      tags:
      - Documents
      parameters:
      - name: IndexId
        in: path
        required: true
        schema:
          type: string
        description: The identifier of the index.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - DocumentIdList
              properties:
                DocumentIdList:
                  type: array
                  description: The list of document IDs to delete.
      responses:
        '200':
          description: Success
        '400':
          description: Bad request - invalid input parameters
        '403':
          description: Access denied - insufficient permissions
        '500':
          description: Internal server error
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    servers:
    - url: https://kendra.{region}.amazonaws.com
      description: Amazon Kendra regional endpoint
      variables:
        region:
          default: us-east-1
          description: AWS region
          enum:
          - us-east-1
          - us-east-2
          - us-west-2
          - eu-west-1
          - ap-southeast-1
          - ap-southeast-2
          - ap-northeast-1
  /indexes/{IndexId}/documents/status:
    post:
      operationId: BatchGetDocumentStatus
      summary: Amazon Kendra Batch Get Document Status
      description: Returns the indexing status for one or more documents submitted with BatchPutDocument.
      tags:
      - Documents
      parameters:
      - name: IndexId
        in: path
        required: true
        schema:
          type: string
        description: The identifier of the index.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - DocumentInfoList
              properties:
                DocumentInfoList:
                  type: array
                  description: A list of DocumentInfo objects that identify the documents for which to get the status.
      responses:
        '200':
          description: Success
        '400':
          description: Bad request - invalid input parameters
        '403':
          description: Access denied - insufficient permissions
        '500':
          description: Internal server error
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    servers:
    - url: https://kendra.{region}.amazonaws.com
      description: Amazon Kendra regional endpoint
      variables:
        region:
          default: us-east-1
          description: AWS region
          enum:
          - us-east-1
          - us-east-2
          - us-west-2
          - eu-west-1
          - ap-southeast-1
          - ap-southeast-2
          - ap-northeast-1
  /#BatchDeleteDocument:
    post:
      operationId: post#BatchDeleteDocument
      summary: Batch Delete Document
      description: Removes one or more documents from an index. The documents must have been added with the BatchPutDocument API. The documents are deleted asynchronously. You can see the progress of the deletion by using Amazon Web Services CloudWatch. Any error messages related to the processing of the batch are sent to your Amazon Web Services CloudWatch log. You can also use the BatchGetDocumentStatus API to monitor the progress of deleting your documents. Deleting documents from an index using BatchDeleteDocument could take up to an hour or more, depending on the number of documents you want to delete.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/BatchDeleteDocumentResponse'
        '403':
          description: AccessDeniedException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ValidationException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AWSKendraFrontendService.BatchDeleteDocument
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/BatchDeleteDocumentRequest'
      tags:
      - Documents
      x-operation-id-source: normalized
      x-operation-id-original: BatchDeleteDocument
    servers:
    - url: https://kendra.{region}.amazonaws.com
      variables:
        region:
          default: us-east-1
  /#BatchPutDocument:
    post:
      operationId: post#BatchPutDocument
      summary: Batch Put Document
      description: Adds one or more documents to an index. The BatchPutDocument API enables you to ingest inline documents or a set of documents stored in an Amazon S3 bucket. Use this API to ingest your text and unstructured text into an index, add custom attributes to the documents, and to attach an access control list to the documents added to the index. The documents are indexed asynchronously. You can see the progress of the batch using Amazon Web Services CloudWatch. Any error messages related to processing the batch are sent to your Amazon Web Services CloudWatch log. You can also use the BatchGetDocumentStatus API to monitor the progress of indexing your documents. For an example of ingesting inline documents using Python and Java SDKs, see Adding files directly to an index.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/BatchPutDocumentResponse'
        '403':
          description: AccessDeniedException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '402':
          description: ServiceQuotaExceededException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ServiceQuotaExceededException'
        '429':
          description: ThrottlingException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ValidationException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AWSKendraFrontendService.BatchPutDocument
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/BatchPutDocumentRequest'
      tags:
      - Documents
      x-operation-id-source: normalized
      x-operation-id-original: BatchPutDocument
    servers:
    - url: https://kendra.{region}.amazonaws.com
      variables:
        region:
          default: us-east-1
components:
  schemas:
    Document:
      type: object
      properties:
        Id:
          type: string
          description: A identifier of the document in the index. Note, each document ID must be unique per index. You cannot create a data source to index your documents with their unique IDs and then use the BatchPutDocument API to index the same documents, or vice versa. You can delete a data source and then use the BatchPutDocument API to index the same documents, or vice versa.
        Title:
          type: string
          description: The title of the document.
        Blob:
          type: string
          format: byte
          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 Kendra APIs. If you are calling the Amazon Kendra endpoint directly using REST, you must base64 encode the contents before sending.
        S3Path:
          $ref: '#/components/schemas/S3Path'
        Attributes:
          type: array
          items:
            $ref: '#/components/schemas/DocumentAttribute'
          description: Custom attributes to apply to the document. Use the custom attributes to provide additional information for searching, to provide facets for refining searches, and to provide additional information in the query response. For example, 'DataSourceId' and 'DataSourceSyncJobId' are custom attributes that provide information on the synchronization of documents running on a data source. Note, 'DataSourceSyncJobId' could be an optional custom attribute as Amazon Kendra will use the ID of a running sync job.
        AccessControlList:
          type: array
          items:
            $ref: '#/components/schemas/Principal'
          description: Information on principals (users and/or groups) and which documents they should have access to. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.
        HierarchicalAccessControlList:
          type: array
          items:
            $ref: '#/components/schemas/HierarchicalPrincipal'
          description: The list of principal lists that define the hierarchy for which documents users should have access to.
        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 must add the HTML start and closing tags (content) around the content.
        AccessControlConfigurationId:
          type: string
          description: The identifier of the access control configuration that you want to apply to the document.
      required:
      - Id
    DocumentAttribute:
      type: object
      properties:
        Key:
          type: string
          description: The identifier for the attribute.
        Value:
          $ref: '#/components/schemas/DocumentAttributeValue'
      required:
      - Key
      - Value
    InlineCustomDocumentEnrichmentConfiguration:
      type: object
      properties:
        Condition:
          $ref: '#/components/schemas/DocumentAttributeCondition'
        Target:
          $ref: '#/components/schemas/DocumentAttributeTarget'
        DocumentContentDeletion:
          type: boolean
          description: TRUE to delete content if the condition used for the target attribute is met.
    BatchPutDocumentResponse:
      type: object
      properties:
        FailedDocuments:
          type: array
          items:
            $ref: '#/components/schemas/BatchPutDocumentResponseFailedDocument'
          description: A list of documents that were not added to the 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. If there was an error adding a document to an index the error is reported in your Amazon Web Services CloudWatch log. For more information, see Monitoring Amazon Kendra with Amazon CloudWatch logs.
    DocumentAttributeCondition:
      type: object
      properties:
        ConditionDocumentAttributeKey:
          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 Kendra currently does not support _document_body as an attribute key used for the condition.
        Operator:
          type: string
          enum:
          - GreaterThan
          - GreaterThanOrEquals
          - LessThan
          - LessThanOrEquals
          - Equals
          - NotEquals
          - Contains
          - NotContains
          - Exists
          - NotExists
          - BeginsWith
          description: The condition operator. For example, you can use 'Contains' to partially match a string.
        ConditionOnValue:
          $ref: '#/components/schemas/DocumentAttributeValue'
      required:
      - ConditionDocumentAttributeKey
      - Operator
    CustomDocumentEnrichmentConfiguration:
      type: object
      properties:
        InlineConfigurations:
          type: array
          items:
            $ref: '#/components/schemas/InlineCustomDocumentEnrichmentConfiguration'
          description: Configuration information to alter document attributes or metadata fields and content when ingesting documents into Amazon Kendra.
        PreExtractionHookConfiguration:
          $ref: '#/components/schemas/HookConfiguration'
        PostExtractionHookConfiguration:
          $ref: '#/components/schemas/HookConfiguration'
        RoleArn:
          type: string
          description: The Amazon Resource Name (ARN) of an IAM role with permission to run PreExtractionHookConfiguration and PostExtractionHookConfiguration for altering document metadata and content during the document ingestion process. For more information, see an IAM roles for Amazon Kendra.
    BatchDeleteDocumentResponseFailedDocument:
      type: object
      properties:
        Id:
          type: string
          description: The identifier of the document that couldn't be removed from the index.
        DataSourceId:
          type: string
          description: The identifier of the data source connector that the document belongs to.
        ErrorCode:
          type: string
          enum:
          - InternalError
          - InvalidRequest
          description: The error code for why the document couldn't be removed from the index.
        ErrorMessage:
          type: string
          description: An explanation for why the document couldn't be removed from the index.
    BatchDeleteDocumentResponse:
      type: object
      properties:
        FailedDocuments:
          type: array
          items:
            $ref: '#/components/schemas/BatchDeleteDocumentResponseFailedDocument'
          description: A list of documents that could not be removed from the index. Each entry contains an error message that indicates why the document couldn't be removed from the index.
    HookConfiguration:
      type: object
      properties:
        InvocationCondition:
          $ref: '#/components/schemas/DocumentAttributeCondition'
        LambdaArn:
          type: string
          description: The Amazon Resource Name (ARN) of an IAM role with permission to run a Lambda function during ingestion. For more information, see an IAM roles for Amazon Kendra.
        S3Bucket:
          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.
      required:
      - LambdaArn
      - S3Bucket
    InternalServerException:
      type: object
      properties:
        Message:
          type: string
    DataSourceSyncJobMetricTarget:
      type: object
      properties:
        DataSourceId:
          type: string
          description: The ID of the data source that is running the sync job.
        DataSourceSyncJobId:
          type: string
          description: The ID of the sync job that is running on the data source. If the ID of a sync job is not provided and there is a sync job running, then the ID of this sync job is used and metrics are generated for this sync job. If the ID of a sync job is not provided and there is no sync job running, then no metrics are generated and documents are indexed/deleted at the index level without sync job metrics included.
      required:
      - DataSourceId
    BatchDeleteDocumentRequest:
      type: object
      properties:
        IndexId:
          type: string
          description: The identifier of the index that contains the documents to delete.
        DocumentIdList:
          type: array
          items:
            type: string
          description: One or more identifiers for documents to delete from the index.
        DataSourceSyncJobMetricTarget:
          $ref: '#/components/schemas/DataSourceSyncJobMetricTarget'
      required:
      - IndexId
      - DocumentIdList
    ValidationException:
      type: object
      properties:
        Message:
          type: string
    HierarchicalPrincipal:
      type: object
      properties:
        PrincipalList:
          type: array
          items:
            $ref: '#/components/schemas/Principal'
          description: A list of principal lists that define the hierarchy for which documents users should have access to. Each hierarchical list specifies which user or group has allow or deny access for each document.
      required:
      - PrincipalList
    BatchPutDocumentRequest:
      type: object
      properties:
        IndexId:
          type: string
          description: The identifier of the index to add the documents to. You need to create the index first using the CreateIndex API.
        RoleArn:
          type: string
          description: The Amazon Resource Name (ARN) of an IAM role with permission to access your S3 bucket. For more information, see IAM access roles for Amazon Kendra.
        Documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
          description: One or more documents to add to the index. Documents have the following file size limits. 50 MB total size for any file 5 MB extracted text for any file For more information, see Quotas.
        CustomDocumentEnrichmentConfiguration:
          $ref: '#/components/schemas/CustomDocumentEnrichmentConfiguration'
      required:
      - IndexId
      - Documents
    AccessDeniedException:
      type: object
      properties:
        Message:
          type: string
    S3Path:
      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
    DocumentAttributeTarget:
      type: object
      properties:
        TargetDocumentAttributeKey:
          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.
        TargetDocumentAttributeValueDeletion:
          type: boolean
          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. To create a target value (TargetDocumentAttributeValue), set this to FALSE.
        TargetDocumentAttributeValue:
          $ref: '#/components/schemas/DocumentAttributeValue'
    ThrottlingException:
      type: object
      properties:
        Message:
          type: string
    DocumentAttributeValue:
      type: object
      properties:
        StringValue:
          type: string
          description: A string, such as "department".
        StringListValue:
          type: array
          items:
            type: string
          description: A list of strings. The default maximum length or number of strings is 10.
        LongValue:
          type: integer
          description: A long integer value.
        DateValue:
          type: string
          format: date-time
          description: A date expressed as an ISO 8601 string. It is 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.
    Principal:
      type: object
      properties:
        Name:
          type: string
          description: The name of the user or group.
        Type:
          type: string
          enum:
          - USER
          - GROUP
          description: The type of principal.
        Access:
          type: string
          enum:
          - ALLOW
          - DENY
          description: Whether to allow or deny document access to the principal.
        DataSourceId:
          type: string
          description: The identifier of the data source the principal should access documents from.
      required:
      - Name
      - Type
      - Access
    ConflictException:
      type: object
      properties:
        Message:
          type: string
    ServiceQuotaExceededException:
      type: object
      properties:
        Message:
          type: string
    ResourceNotFoundException:
      type: object
      properties:
        Message:
          type: string
    BatchPutDocumentResponseFailedDocument:
      type: object
      properties:
        Id:
          type: string
          description: The identifier of the document.
        DataSourceId:
          type: string
          description: The identifier of the data source connector that the failed document belongs to.
        ErrorCode:
          type: string
          enum:
          - InternalError
          - InvalidRequest
          description: The type of error that caused the document to fail to be indexed.
        ErrorMessage:
          type: string
          description: A description of the reason why the document could not be indexed.
  securitySchemes:
    sigv4:
      type: apiKey
      name: Authorization
      in: header
      description: AWS Signature Version 4 authentication
x-refined-from:
- amazon-kendra-openapi.yml
- amazon-kendra-documents-api-openapi.yml