openapi: 3.0.2
info:
  version: 3.0.0
  title: Kensho Extract annotations-async 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. \nKensho Extract interprets messy page layout, structuring text into cohesive paragraphs that can be effectively\
    \ analyzed and searched. <br><br> The Kensho Extract API V3 has incorporated changes to how users must call the API.\n\
    Please note there are more required fields in API V3 than API V2 (deprecated). The following fields are *mandatory* for\
    \ `/v3/extractions`: file, document_type, ocr and enhanced_table_extraction. <br><br> API V3 introduces new upload and\
    \ download functionality, allowing the upload of the original document and retrieval of the extracted document output\
    \ via pre-signed URLs. The pre-signed URLs expire after 15 minutes. <br> These new endpoints must be called in the following\
    \ order.\n  - `/v3/extractions/upload-url`\n    - followed by POST'ing the document to the `url` provided in the response\n\
    \  - `/v3/extractions/upload-complete`\n  - `/v3/extractions/download-url/{request_id}`\n    - followed by a calling the\
    \ GET `output_url` provided in the response\n"
servers:
- url: https://nerd.kensho.com
tags:
- name: annotations-async
paths:
  /api/v1/annotations-async:
    post:
      tags:
      - annotations-async
      summary: Start A NERD Annotation Job
      operationId: api_annotations_async_post
      description: Submit a document to NERD to kick off an annotation job that will be processed asynchronously. Endpoint
        users submit a text document and at least one knowledge base to be used to annotate the detected entities. There are
        two available knowledge bases, the Wikimedia knowledge base and the Capital IQ knowledge base, denoted `"wikimedia"`
        and `"capiq"`, respectively.
      requestBody:
        $ref: '#/components/requestBodies/nerd_request_post'
      responses:
        '202':
          content:
            application/json:
              schema:
                type: object
                example:
                  job_id: J1234
                  request_id: R1234
                properties:
                  job_id:
                    type: string
                    description: Job identifier associated with the document's NERD processing. Used to retrieve annotation
                      results at a later time.
                  request_id:
                    type: string
                    description: Optional identifier submitted by the caller to track their own requests. If provided, it
                      is returned in the response as it was submitted.
          description: Indicates the job request was successfully received. `job_id` is returned in the response.
        '400':
          description: Indicates a bad request because at least one knowledge base and document text must be specified.
        '401':
          description: Indicates that the authentication information is missing or invalid.
        '403':
          description: Indicates that the authorization information is missing or invalid.
        '429':
          description: Indicates that user request rate has been exceeded.
        5XX:
          description: Indicates that an unexpected error occurred and should be further investigated.
      x-openapi-router-controller: openapi_server.controllers.async_controller
      security:
      - BearerAuth:
        - token_info
    put:
      tags:
      - annotations-async
      summary: Start A NERD Annotation Job Given A Provided Job ID
      operationId: api_annotations_async_put
      description: Notify NERD to start the annotation job given a provided job ID from uploading a text file using an upload
        URL. To upload a text file, please see [upload-url](/nerd/api#tag/upload-url/operation/api_annotations_upload_url)
        for more information.
      requestBody:
        $ref: '#/components/requestBodies/nerd_request_put'
      parameters:
      - in: query
        name: job_id
        description: Job identifier used to start the annotations job. Corresponds to the `job_id` returned from a GET request
          to the [upload-url](/nerd/api#tag/upload-url/operation/api_annotations_upload_url) endpoint.
        schema:
          type: string
      responses:
        '202':
          content:
            application/json:
              schema:
                type: object
                example:
                  job_id: J1234
                  request_id: R1234
                properties:
                  job_id:
                    type: string
                    description: Job identifier associated with the document's NERD processing. Used to retrieve annotation
                      results at a later time.
                  request_id:
                    type: string
                    description: Optional identifier submitted by the caller to track their own requests. If provided, it
                      is returned in the response as it was submitted.
          description: Indicates the job request was successfully received. `job_id` is returned in the response.
        '400':
          description: Indicates a bad request because at least one knowledge base must be specified and the document text
            for the provided `job_id` was not uploaded.
        '401':
          description: Indicates that the authentication information is missing or invalid.
        '403':
          description: Indicates that the authorization information is missing or invalid.
        '429':
          description: Indicates that user request rate has been exceeded.
        5XX:
          description: Indicates that an unexpected error occurred and should be further investigated.
      security:
      - BearerAuth:
        - token_info
    get:
      tags:
      - annotations-async
      summary: Get Annotations For The Specified Job ID
      operationId: api_annotations_async_get
      description: This endpoint returns the results of a NERD annotations job. The endpoint expects the `job_id` to be specified
        as the query parameter. The response contains a status, message, and the annotation results.
      parameters:
      - in: query
        name: job_id
        description: Job identifier used to obtain the annotations. Corresponds to the `job_id` returned from a POST request
          to the async annotations endpoint.
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/nerd_job_response'
          description: Indicates the request was successfully received and processed. Annotated data is returned in the response.
        '400':
          description: Indicates a bad request due to 1) missing knowledge base; 2) missing document text; or 3) missing `job_id`.
        '401':
          description: Indicates that the authentication information is missing or invalid.
        '403':
          description: Indicates that the authorization information is missing or invalid.
        '404':
          description: Indicates that the job was not found in the system.
        '429':
          description: Indicates that user rate has been exceeded.
        5XX:
          description: Indicates that an unexpected error occurred and should be further investigated.
      x-openapi-router-controller: openapi_server.controllers.async_controller
      security:
      - BearerAuth:
        - token_info
    delete:
      tags:
      - annotations-async
      summary: Delete Annotations For The Specified Job ID
      operationId: api_annotations_async_delete
      description: This endpoint deletes the results of a NERD annotations job. The endpoint expects the `job_id` to be specified
        as the query parameter. The response contains a status and message
      parameters:
      - in: query
        name: job_id
        description: Job identifier used to obtain the annotations. Corresponds to the `job_id` returned from a POST request
          to the async annotations endpoint.
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Job has been successfully deleted.
                properties:
                  message:
                    type: string
                    description: Additional information
          description: Indicates the request was successfully received and processed. Annotated data is returned in the response.
        '400':
          description: Indicates a bad request due to a missing or invalid `job_id`
        '401':
          description: Indicates that the authentication information is missing or invalid.
        '403':
          description: Indicates that the authorization information is missing or invalid.
        '404':
          description: Indicates that the job was not found in the system.
        '409':
          description: Indicates that the job is pending and therefore cannot be deleted.
        '429':
          description: Indicates that user request rate has been exceeded.
        5XX:
          description: Indicates that an unexpected error occurred and should be further investigated.
      x-openapi-router-controller: openapi_server.controllers.async_controller
      security:
      - BearerAuth:
        - token_info
components:
  requestBodies:
    nerd_request_post:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/nerd_request_post'
      required: true
    nerd_request_put:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/nerd_request_put'
      required: true
  schemas:
    nerd_response_results:
      example:
        knowledge_base: capiq
        annotations:
        - start_index: 0
          end_index: 6
          text: Kensho
          ner_score: 0.99
          ned_score: 0.96
          ner_type: ORG
          entity_label: Kensho Technologies
          entity_type: ORG
          entity_kb_id: 251994106
        - start_index: 130
          end_index: 144
          text: The LEGO Group
          ner_score: 0.89
          ned_score: 0.99
          ner_type: ORG
          entity_label: LEGO A/S
          entity_type: ORG
          entity_kb_id: 701221
        entity_relevance_scores:
        - '701221': 0.5
          '251994106': 0.5
      properties:
        knowledge_base:
          type: string
        annotations:
          items:
            $ref: '#/components/schemas/nerd_response_annotation'
          type: array
        entity_relevance_scores:
          type: object
          additionalProperties:
            type: object
            properties:
              relevance_score:
                type: number
              entity_id:
                type: string
    nerd_job_response:
      example:
        status: success
        message: OK
        request_id: R1234
        results:
        - knowledge_base: capiq
          annotations:
          - start_index: 0
            end_index: 6
            text: Kensho
            ner_score: 0.99
            ned_score: 0.96
            ner_type: ORG
            entity_label: Kensho Technologies
            entity_type: ORG
            entity_kb_id: '251994106'
          - start_index: 130
            end_index: 144
            text: The LEGO Group
            ner_score: 0.89
            ned_score: 0.99
            ner_type: ORG
            entity_label: LEGO A/S
            entity_type: ORG
            entity_kb_id: '701221'
          entity_relevance_scores:
            '701221': 0.5
            '251994106': 0.5
        - knowledge_base: wikimedia
          annotations:
          - start_index: 1000
            end_index: 1007
            text: Nairobi
            ner_score: 1
            ned_score: 0.43
            ner_type: LOC
            entity_label: Nairobi
            entity_type: CITY
            entity_kb_id: '3870'
          - start_index: 1201
            end_index: 1203
            text: AU
            ner_score: 1
            ned_score: 0.43
            ner_type: ORG
            entity_label: African Union
            entity_type: NGO
            entity_kb_id: '7159'
          entity_relevance_scores:
            '3870': 0.5
            '7159': 0.5
      properties:
        status:
          type: string
          description: Current status of the requested job. `"pending"` denotes that the job is still pending, and `"success"`
            denotes that the job has completed.
        message:
          type: string
          description: If no errors occurred, the message contains `"OK"`. If errors occurred, then the message contains the
            error description.
        request_id:
          type: string
          description: Identifier submitted by the caller to track their own requests, returned if and as it was provided.
        results:
          items:
            $ref: '#/components/schemas/nerd_response_results'
    nerd_request_put:
      example:
        knowledge_bases:
        - capiq
        tag_people: false
        originating_entity_id: '701221'
        request_id: R1234
      properties:
        knowledge_bases:
          items:
            type: string
          type: array
          description: Knowledge bases to disambiguate to, e.g., `["capiq"]`, `["wikimedia"]`, or `["capiq", "wikimedia"]`.
        tag_people:
          type: boolean
          description: Whether to tag people on a CapIQ request. Requires access to people tagging.
        originating_entity_id:
          type: string
          description: Specifies the Capital IQ ID of the company issuing the source document. For example, the company whose
            earnings call transcript or 10K filing is passed through NERD would be the originating entity for that document.
            Used only when submitting documents for linking to the Capital IQ knowledge base. If there isn't an appropriate
            originating entity for a document, such as in the case of a news article, simply enter `"0"` or omit the field.
        request_id:
          type: string
          description: Optional identifier submitted by the caller to track their own requests. If provided, it is returned
            in the response as it was submitted.
      type: object
    nerd_response_annotation:
      example:
        start_index: 0
        end_index: 6
        text: Kensho
        ner_score: 0.99
        ned_score: 0.96
        ner_type: ORG
        entity_label: Kensho Technologies
        entity_type: ORG
        entity_kb_id: '251994106'
      properties:
        text:
          type: string
          description: Text of the entity mention identified by NERD.
        start_index:
          type: integer
          description: Starting offset of the entity mention in the source document text.
        end_index:
          type: integer
          description: Ending offset of the entity mention in the source document.
        entity_kb_id:
          type: string
          description: Identifier in the chosen knowledge base of the entity that this span was linked to. If no link was
            found (but the model determined that this span is an entity), this field is returned null.
        entity_label:
          type: string
          description: Name in the chosen knowledge base of the entity that this span was linked to. If no link was found
            (but the model determined that this span is an entity), this field is returned null.
        entity_type:
          type: string
          description: Predicted entity type in the chosen knowledge base of the entity that this span was linked to. If no
            link was found (but the model determined that this span is an entity), this field is returned null. Entities linked
            to the Capital IQ knowledge base will always be of type "ORG" (organization). Entities linked to the Wikimedia
            knowledge base may be of several types, including "PERSON", "COMPANY", "NGO", and "GOVERNMENT". Wikimedia does
            not publish entity types, so for Wikimedia annotated entities, this field is merely a prediction and should not
            be taken as ground truth.
        ner_score:
          type: number
          description: Score that denotes how confident the NERD model is that the span’s text refers to an entity.
        ned_score:
          type: number
          description: Score the denotes the NERD model's confidence in the link between the entity mention and the entry
            in the knowledge base (i.e., the entity_kb_id). If no link was found (but the model determined that this span
            is an entity), this field is returned null.
        ner_type:
          type: string
          description: Predicted entity type for the text span corresponding to this annotation. This field is independent
            of both `entity_type` and `entity_kb_id` and denotes the type of entity that the NERD model predicted for the
            text span. The value of this field is always "ORG" for Capital IQ NERD and one of {"EVENT", "FAC", "GPE", "LAW",
            "LOC", "NORP", "ORG", "PERSON", "PRODUCT", "WORK_OF_ART"} for Wikimedia NERD.
    nerd_request_post:
      example:
        knowledge_bases:
        - capiq
        tag_people: false
        text: Kensho announced the release of NERD in 2021....The LEGO Group posted earnings in August....Nairobi was the
          top destination....the AU made the decision...
        originating_entity_id: '701221'
        request_id: R1234
      properties:
        knowledge_bases:
          items:
            type: string
          type: array
          description: Knowledge bases to disambiguate to, e.g., `["capiq"]`, `["wikimedia"]`, or `["capiq", "wikimedia"]`.
        tag_people:
          type: boolean
          description: Whether to tag people on a CapIQ request. Requires access to people tagging.
        text:
          type: string
          description: Content of the source document.
        originating_entity_id:
          type: string
          description: Specifies the Capital IQ ID of the company issuing the source document. For example, the company whose
            earnings call transcript or 10K filing is passed through NERD would be the originating entity for that document.
            Used only when submitting documents for linking to the Capital IQ knowledge base. If there isn't an appropriate
            originating entity for a document, such as in the case of a news article, simply enter `"0"` or omit the field.
        request_id:
          type: string
          description: Optional identifier submitted by the caller to track their own requests. If provided, it is returned
            in the response as it was submitted.
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT