Kensho NERD API

openapi: 3.2.0
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.\nPlease 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_put:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/nerd_request_put'
      required: true
    nerd_request_post:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/nerd_request_post'
      required: true
  schemas:
    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_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_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
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT