API Documentation


The REST API enables the integration of our state of the art knowledge processing pipeline into other applications. The API exposes predictable resources, returns JSON-encoded responses, and uses standard HTTP response codes and verbs.

The base URL for the requests is:

All calls require a valid apiKey – please use the form below to get one.

Error codes

We use conventional HTTP response codes to indicate the success or failure of an API request. In general:

  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.).
  • Codes in the 5xx range indicate an error with our servers.

Below is the list of all codes returned by the API, together with their corresponding interpretation:

  • 200 [OK] – Everything worked as expected.
  • 400 [Bad Request] – The request was unacceptable, often due to missing a required parameter.
  • 401 [Unauthorized] – No valid API key provided.
  • 404 [Not Found] – The requested resource doesn’t exist.
  • 5xx [Server Errors] – Something went wrong on our end.

Concept recognition API

Our concept recognition API enables you to bridge the gap between free text and structured data represented via ontology concepts. Below is the list of ontologies currently supported by the API, and the endpoint / payload information.

Human Phenotype Ontology (

HPO CR performance

The HPO CR (listed as PH below) has been evaluated on the Pubmed abstract corpus initially published in (Groza, 2015) and then extended in (Couto, 2017). Results (P | R | F1) are reported against IHP (Lobo, 2017) and NCR (Arbabi, 2019):

PH:  0.953 | 0.906 | 0.928
IHP: 0.872 | 0.854 | 0.863
NCR: 0.803 | 0.624 | 0.702

РGroza T, Köhler S, Doelken S, Collier N, Oellrich A, Smedley D, Couto FM, Baynam G, Zankl A, Robinson PN. Automatic concept recognition using the human phenotype ontology reference and test suite corpora. Database (Oxford). 2015 Feb 27;2015. pii: bav005.
– Lobo M, Lamurias A, Couto FM. Identifying Human Phenotype Terms by Combining Machine Learning and Validation Rules. Biomed Res Int. 2017; 2017: 8565739.
– Arbabi A, Adams DR, Fidler S, Brudno M. Identifying Clinical Terms in Medical Text Using Ontology-Guided Machine Learning. JMIR Med Inform. 2019 Apr-Jun; 7(2): e12596.



Payload: String

Response (example):

  "data": [
      "startOffset": 18,
      "endOffset": 26,
      "term": {
        "curie": "HP:0003510",
        "uri": "",
        "label": "Severe short stature",
        "locale": "en",
        "metadata": {
          "metadata": {
            "DEFINITION": "A severe degree of short stature, ...",
            "NOTHING": "false",
            "LEAF": "true",
            "COMMENT": "The term severe short stature is to be preferred ...",
            "THING": "false"
        "synonyms": [
            "synonym": "Severe short stature",
            "synonymType": "LAYPERSON"
        "references": [
            "source": "SNOMEDCT_US",
            "reference": "237836003"
        "altIds": [
      "negated": false


This service is using the Human Phenotype Ontology. Find out more at

Get your trial API key here

Enter your details below to receive your API key via email.

  • This field is for validation purposes and should be left unchanged.