Getting Started
In this section we will demonstrate use of Kyla AI RESTful API using JSON format. API can be accessed using the following URL: [https://kyla.ai/api/]. The use of the API is limited to authorized users only, for a limited demonstration access TODO: how to get access.
Providing Patient Information
Most of the functionality provided by the Kyla API is focused on personalized assessments. For that reason it makes sense to start with an example of providing information about a patient.
There are two facts about the patient that are always required: these are age and sex. All other facts related to the patient are passed using key-value pairs. The key is a node id that corresponds to a medical concept (e.g. N00143 - sore throat) and the value one of corresponding outcomes. To learn about node ids and matching them to medical concepts see a section on Matching Concepts to Nodes.
As an example we can use a 35-year-old male patient complaining on sore throat. The information would be encoded as follows:
{
"sex": "MALE",
"age": 35,
"observations": [
{
"nodeId": "N00143",
"outcome": "present"
}
]
}
To test functionality of Kyla API we can start with an endpoint which provides diagnostic information. The /diagnosis POST endpoint takes as an input only information about the patient and the example provided above is sufficient to produce a result.
To send request you can use:
curl -X 'POST' \
'https://aiaas.dev.kyla.com/engines/api/v1/diag/diagnosis' \
-H 'accept: application/json' \
-H 'Authorization: api-key_Xg0VVkzE6ROHzr7uvo3ZDKJW8WWC6mHgb3raIoRgTQbelkh31N' \
-H 'Content-Type: application/json' \
-d '{
"sex": "MALE",
"age": 35,
"observations": [
{
"nodeId": "N00143",
"outcome": "present"
}
]
}
'
In a nutshell, the endpoint takes information about the patient, makes an assessment based on the information provided and suggests the next question to ask along the suggested most likely conditions (given the current state of the knowledge about the patient). One should keep in mind, that the best results are achieved when information about the patient is reasonably comprehensive. This normally should be achieved by iterative application of the /diagnosis endpoint.
But even for such limited information as provided in this example, we can inspect the response produced. It consists of the next most informative question identified by Kyla AI and the most likely diagnosis:
{
"success": true,
"data": {
"conditions": [
{
"nodeId": "C01339",
"title": "Common Cold",
"probability": 0.38028156757354736
}
],
"question": {
"type": "SINGLE",
"text": "Pharyngeal Exudate",
"nodes": [
{
"id": "N01795",
"title": "Pharyngeal Exudate",
"outcomes": [
{
"outcome": "unknown",
"label": "Don't know"
},
{
"outcome": "present",
"label": "present"
},
{
"outcome": "absent",
"label": "absent"
}
],
"type": "DISCRETE",
"unitOfContinuousType": null
}
]
},
"completedDiagnosis": false
},
"errors": [
{
"code": "RESULT_SECURITY_PROTECTION",
"message": "Number of condition results limited to 1"
}
]
}
In the response Kyla API suggests that the most likely diagnosis is Common Cold, but more investigation is needed to reach desired certainty, which is indicated by the flag "completedDiagnosis": false. But most importantly, a next question to ask the patient is provided: in this case it is about presence of Pharyngeal Exudate (node id N01795), which is accumulation of pus or mucus on the wall of the pharynx.
Typically the diagnostic API provides more than one suggested diagnosis, however to prevent knowledge base scraping, some requests with a small number or excessively high number of observations may have put some limitations on the results. When it happens, the user is informed by providing the error message of type RESULT_SECURITY_PROTECTION.
Let us assume, that the patient does not have pus or mucus. In that case we set the value for node N01795 to absent and execute the next API call with the updated data about the patient:
{
"sex": "MALE",
"age": 35,
"observations": [
{
"nodeId": "N00143",
"outcome": "present"
},
{
"nodeId": "N01795",
"outcome": "absent"
}
]
}
The corresponding request would be as follows:
curl -X 'POST' \
'https://aiaas.dev.kyla.com/engines/api/v1/diag/diagnosis' \
-H 'accept: application/json' \
-H 'Authorization: api-key_Xg0VVkzE6ROHzr7uvo3ZDKJW8WWC6mHgb3raIoRgTQbelkh31N' \
-H 'Content-Type: application/json' \
-d '{
"sex": "MALE",
"age": 35,
"observations": [
{
"nodeId": "N00143",
"outcome": "present"
},
{
"nodeId": "N01795",
"outcome": "absent"
}
]
}
'
In the response Kyla AI takes into account new information provided and produces revised probabilities for conditions and the next question:
{
"success": true,
"data": {
"conditions": [
{
"nodeId": "C01339",
"title": "Common Cold",
"probability": 0.3956716060638428
}
],
"question": {
"type": "SINGLE",
"text": "Do you currently have a runny nose (rhinorrhea)?",
"nodes": [
{
"id": "N00146",
"title": "Rhinorrhea",
"outcomes": [
{
"outcome": "unknown",
"label": "Don't know"
},
{
"outcome": "present",
"label": "present"
},
{
"outcome": "absent",
"label": "absent"
}
],
"type": "DISCRETE",
"unitOfContinuousType": null
}
]
},
"completedDiagnosis": false
},
"errors": [
{
"code": "RESULT_SECURITY_PROTECTION",
"message": "Number of condition results limited to 1"
}
]
}
This section presented how to pass information about a patient in Kyla API in the context of one of the most important functionality of Kyla AI - the diagnostic interview.
It should be noted, that in normal use the number of observations provided related to the patient information should be relatively large. Even though these examples had only one or two observations, we strongly discorage users to use diagnostic functionality with too few observations. The best results are achieved when there are at least several observations provided as the initial evidence.