Kensho Extract API

openapi: 3.2.0
info:
  version: 3.0.0
  title: Kensho Extract Extractions API
  description: Kensho Extract allows users to quickly transform their unstructured documents into a machine-readable format that identifies titles, subtitles, paragraphs, tables, and footers detected within the document in their natural reading order.
servers:
- url: https://extract.kensho.com/
tags:
- name: Extractions
paths:
  /v3/extractions:
    post:
      description: Submit a document for extraction
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - file
              - document_type
              - ocr
              - enhanced_table_extraction
              type: object
              properties:
                file:
                  type: string
                  description: The document to extract. The maximum file size is 100MB.
                  format: binary
                document_type:
                  type: string
                  description: 'The output document format. Kensho Extract offers three document types: `hierarchical`, `hierarchical_v2`, and `general`.

                    Please refer to our [overview page](home) for a detailed breakdown of which model will provide the most optimal output for your use case.

                    '
                ocr:
                  type: string
                  description: 'Identifies whether the document is scanned or is a native pdf. This must be `true` or `false`.

                    See the [OCR](ocr) page for more information.

                    '
                enhanced_table_extraction:
                  type: string
                  description: 'Use our newest model to extract data from complex tables more accurately than ever.                     This must be `true` or `false`.

                    '
                figure_extraction:
                  type: string
                  description: 'Use our newest model to extract data from figures.                     This must be `true` or `false`.

                    See the [Figure Extraction](figex) page for more information.

                    '
                include_images:
                  type: string
                  description: 'Whether to return the locations of images. This must be `true` or `false`.

                    '
                include_relations:
                  type: string
                  description: 'Whether to return the relations between items. This must be `true` or `false`.

                    '
                document_id:
                  type: string
                  description: A custom document identifier.
                priority:
                  type: string
                  enum:
                  - low
                  description: The priority level. Anything besides `low` will be considered `high` priority.
                pages:
                  type: string
                  description: 'This specifies the pages to extract. Page numbers start at 1. Format: `1-5,7,11,14-16`.'
                return_absolute_pdf_page_numbers:
                  type: boolean
                  default: false
                  description: 'Whether to return absolute PDF page numbers in the output. Absolute PDF page numbers refer to the original page numbers requested, while relative page numbers start at 0 and increment by 1 for each page requested

                    '
                output_format:
                  type: string
                  description: 'This can be `structured_document`, `structured_document_with_locations`, or `structured_document_with_char_offsets`. It determines if the response format will include location bounding box information.

                    <br>

                    Including this parameter requires making a call to `/v3/extractions/download-url/{request_id}` to obtain a URL for downloading the document from AWS.

                    '
      responses:
        '200':
          description: The request was successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    format: uuid
        '400':
          description: This can be any combination of the required parameters are not provided, a parameter that is invalid, or if a specific pages is requested in the `pages` parameter and that page is not in the document. E.g., requesting page 57 for a 10 page document.
        '401':
          description: The authentication token is missing or invalid.
        default:
          description: An unexpected error occurred.
      security:
      - bearerAuth: []
      tags:
      - Extractions
      summary: Create extractions
      x-summary-source: derived
      operationId: postV3Extractions
      x-operation-id-source: derived
  /v3/extractions/upload-url:
    post:
      summary: Upload URL To Submit A Document For Extraction
      description: Creates the request and returns a pre-signed upload URL to upload the document for extraction.
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - output_format
              - document_type
              - ocr
              - enhanced_table_extraction
              type: object
              properties:
                output_format:
                  type: string
                  description: This can be `structured_document`, `structured_document_with_locations`, or `structured_document_with_char_offsets`. It determines if the extracted document format will include location bounding box information and character offsets.
                document_type:
                  type: string
                  description: 'The output document format. Kensho Extract offers three document types: `hierarchical`, `hierarchical_v2`, and `general`.

                    Please refer to our [overview page](home) for a detailed breakdown of which model will provide the most optimal output for your use case.

                    '
                ocr:
                  type: string
                  description: 'Identifies whether the document is scanned or is a native pdf. This must be `true` or `false`.

                    See the [OCR](ocr) page for more information.

                    '
                enhanced_table_extraction:
                  type: string
                  description: 'Use our newest model to extract data from complex tables more accurately than ever. This must be `true` or `false`.

                    '
                figure_extraction:
                  type: string
                  description: 'Use our newest model to extract data from figures. This must be `true` or `false`.

                    See the [Figure Extraction](figex) page for more information.

                    '
                document_id:
                  type: string
                  description: A custom document identifier.
                priority:
                  type: string
                  enum:
                  - low
                  description: The priority level. Anything besides `low` will be considered `high` priority.
                pages:
                  type: string
                  description: 'This specifies the pages to extract. Page numbers start at 1. Format: `1-5,7,11,14-16`.'
                num_pages_to_extract:
                  type: integer
                  description: This specifies the total number of pages to extract.
            encoding:
              file:
                contentType: application/pdf
        required: true
      responses:
        '200':
          description: The request was successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    format: uuid
                  upload_spec:
                    type: object
                    properties:
                      url:
                        type: string
                        description: The URL to POST the document upload to. Returns 204 on success. Refer to the AWS pre-signed URL documentation for detailed information on specific response codes and their meanings.
                      fields:
                        type: object
                        additionalProperties:
                          type: string
                        description: Fields required in the form data of the POST request for uploading the document to the `url`.
        '400':
          description: This can be any combination of the required parameters are not provided or parameter value is invalid.
        '401':
          description: The authentication token is missing or invalid.
        default:
          description: An unexpected error occurred.
      security:
      - bearerAuth: []
      tags:
      - Extractions
      operationId: postV3ExtractionsUploadUrl
      x-operation-id-source: derived
  /v3/extractions/upload-complete:
    put:
      summary: Mark The Upload As Complete To Start Extraction
      description: Call this after the document has been uploaded to the pre-signed URL returned by `/v3/extractions/upload-url`. The extraction process will not begin until this endpoint is called.
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - request_id
              type: object
              properties:
                request_id:
                  type: uuid
                  description: The request_id for the extraction.
        required: true
      responses:
        '204':
          description: The request was marked as uploaded successfully.
        '400':
          description: The request_id was not provided by the client, or was not created via `/v3/extractions/upload-url`.
        '401':
          description: The authentication token is missing or invalid.
        '404':
          description: The request_id or the uploaded document could not be found.
        default:
          description: An unexpected error occurred.
      security:
      - bearerAuth: []
      tags:
      - Extractions
      operationId: putV3ExtractionsUploadComplete
      x-operation-id-source: derived
  /v3/extractions/{request_id}:
    get:
      description: Retrieve the extracted document
      parameters:
      - name: request_id
        in: path
        description: request uuid
        required: true
        schema:
          type: string
          format: uuid
      - name: output_format
        in: query
        description: This can be `structured_document`, `structured_document_with_locations`, or `structured_document_with_char_offsets`. It determines if the response format will include location bounding box information.
        required: false
        schema:
          type: string
          default: structured_document_with_locations
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    - failed
                    - pending
                  error:
                    type: string
                  output:
                    type: object
                    $ref: '#/components/schemas/Output'
                  metadata:
                    type: object
                    properties: {}
        '400':
          description: 'The request_id was not provided by the client, or output_format was specified when the request was created.

            <br>

            If output_format was specified when the request was created, /v3/extractions/download-url/{request_id} must be called to get a pre-signed URL to retrieve the extracted output.

            '
        '401':
          description: The authentication token is missing or invalid.
        '404':
          description: The request_id could not be found.
        '405':
          description: The request is on a different API version than the POST request that created the request.
        default:
          description: An unexpected error occurred.
      security:
      - bearerAuth: []
      tags:
      - Extractions
      summary: Get extractions by request id
      x-summary-source: derived
      operationId: getV3ExtractionsByRequestId
      x-operation-id-source: derived
  /v3/extractions/download-url/{request_id}:
    get:
      summary: Retrieve The Extracted Document's Download URL
      description: GET the `output_url` in the response to download the extracted document.
      parameters:
      - name: request_id
        in: path
        description: request uuid
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    - failed
                    - pending
                    - awaiting_document_upload
                    - awaiting_document_upload_complete_notification
                  error:
                    type: string
                  output_url:
                    type: string
                  metadata:
                    type: object
                    properties: {}
        '400':
          description: The request_id was not provided by the client, or output_format was not specified when the request was created.
        '401':
          description: The authentication token is missing or invalid.
        '404':
          description: The request_id could not be found.
        '405':
          description: The request is on a different API version than the POST request that created the request, the document has not been uploaded, or /v3/extractions/upload-complete has not been called to marked the upload complete.
        default:
          description: An unexpected error occurred.
      security:
      - bearerAuth: []
      tags:
      - Extractions
      operationId: getV3ExtractionsDownloadUrlByRequestId
      x-operation-id-source: derived
components:
  schemas:
    ContentTree:
      type: object
      properties:
        uid:
          type: string
          description: Identifier for a content node that is unique across all nodes in a document
        type:
          type: string
          description: Type of a content node, must be one of document|paragraph|H1|H2|table|table_cell|table_title
        content:
          type: string
          description: Text that corresponds to the content node (optional)
        children:
          type: array
          description: List of child content nodes (recursive)
          items:
            $ref: '#'
      required:
      - uid
      - type
      - content
      - children
    Annotations:
      type: array
      description: Additional data about structure of the document that references text content nodes by their UIDs
      items:
        type: object
        description: Individual annotation
        properties:
          type:
            type: string
            description: Type of an annotation, (e.g. table structure / row header, etc.).
          content_uids:
            type: array
            description: Non-empty list of UIDs of content nodes corresponding to the annotation.
            items:
              type: string
            minItems: 1
          data:
            type: object
        required:
        - type
        - content_uids
    Output:
      type: object
      properties:
        content_tree:
          type: object
          $ref: '#/components/schemas/ContentTree'
        annotations:
          type: object
          $ref: '#/components/schemas/Annotations'
      required:
      - content_tree
      - annotations
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT