Named-Entity Recognition and Disambiguation REST service linking text mentions to S&P Capital IQ company identifiers and to Wikimedia entities (people, places, events). Supports asynchronous batch annotation with optional person tagging and originating-entity context for financial documents.
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelistoverlay
POST/api/v1/annotations-asyncSubmit text for asynchronous entity annotation · Start A NERD Annotation Job#
Ask an LLM
“How do I send a document's text to NERD and have entities linked to Capital IQ or Wikimedia?”
“Can I submit raw text for named entity recognition and get the results later?”
Tell an agent
Submit this text for annotation against Capital IQ: {text}
Start an async annotation job on {text} using knowledge bases {knowledge_bases}.
PUT/api/v1/annotations-asyncStart annotating an uploaded text file · Start A NERD Annotation Job Given A Provided Job ID#
Ask an LLM
“I uploaded a text file through an upload URL - how do I tell NERD to start annotating it?”
“Can I kick off annotation for a file I already uploaded using its job ID?”
Tell an agent
Start the annotation job for uploaded file job {job_id} against the {knowledge_bases} knowledge bases.
Begin annotating uploaded job {job_id} with people tagging set to {tag_people}.
GET/api/v1/annotations-asyncFetch results of an entity annotation job · Get Annotations For The Specified Job ID#
Ask an LLM
“Where can I pick up the entity annotations once my NERD job finishes?”
“Can I check whether an asynchronous annotation job is still running or done?”
Tell an agent
Get the annotation results for NERD job {job_id}.
Check the status and entities found for annotation job {job_id}.
DELETE/api/v1/annotations-asyncDelete the results of an annotation job · Delete Annotations For The Specified Job ID#
Ask an LLM
“Can I remove stored annotation results after I've downloaded them?”
“How do I clean up a finished NERD annotation job?”
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
openapi: 3.2.0
info:
description: This page contains the full API reference for Kensho NERD.
title: NERD Service Annotations Async API
version: '1.0'
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 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_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_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_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_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_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:
bearerFormat: JWT
scheme: bearer
type: http
x-bearerInfoFunc: openapi_server.controllers.security_controller_.info_from_BearerAuth
APIKey:
type: apiKey
name: kensho_nerd_token
in: cookie
x-apikeyInfoFunc: openapi_server.controllers.security_controller_.info_from_CookieAuth