Example API request flow
From within the interactive documentation, example requests can be made to a live Rainbird environment using the example api key and Knowledge Map ID below.
API Host
https://api.rainbird.ai
API Key
37582f71-b9b1-4451-b9e6-c130c7fd2412
Knowledge Map ID
2fd1be28-b38d-4fa3-8b9d-b0976821912c
The example Knowledge Map is a simple model of national languages and the likelihood that a person who lives in the country, speaks the national language of the country. The Knowledge Map contains a single rule on the speaks relationship. When performing a query against the speaks relationship this rule is eligible to be run by the Rainbird engine.
Start
A start request must be made to start a session with the reasoning engine using the required knowledge map. The session ID returned is used in subsequent API calls.
Begin by making a GET request to /start/{kmid} including the API key in the header X-API-Key: {API Key}
An example response is shown below. The 1st ID is the Session ID required in all subsequent requests.
{
"id": "25f02c14-e42e-4e91-9543-92336f613809",
"kmVersion": {
"id": "abcdefgh-abcd-abcd-abcdefghijkl"
}
}Inject
An inject request can be made when you have data available that you can provide in advance of the query. In this example, we will inject a single fact as a triple, just to demonstrate the inject method.
Make a POST request to /{sessionID}/inject with the following information in the body.
[
{
"subject": "Tom",
"relationship": "lives in",
"object": "Germany",
"certainty": "100"
}
]Relationship names must correspond to the knowledge map the data is being injected onto, observing case sensitivity.
Plurality of relationships should also be considered. i.e. you cannot inject multiple facts for the same subject onto a singular relationship.
Observe correct object types:
Object values must be sent as a "string", but the value sent must correctly correspond to the expected types in the knowledge map which might be string, date, number or boolean.
Dates must be injected in ISO-8601 format (YYYY-MM-DD) or as Unix timestamps using milliseconds.
Query
A query can be run against the speaks relationship making a POST request to /{sessionID}/query
The query can be constructed in the body in different ways, depending on what answers you want to get. Below shows three examples.
To find what language Tom speaks (Tom -> speaks -> ?), pass subject and relationship:
{
"subject": "Tom",
"relationship": "speaks"
}To find who speaks French (? -> speaks -> French), pass relationship and object:
{
"relationship": "speaks",
"object": "French"
}To check if Tom speaks French (Tom -> speaks -> French), pass subject, relationship and object:
{
"subject": "Tom",
"relationship": "speaks",
"object": "French"
}Using the first query for Tom -> speaks -> ? you should receive a questionResponse that looks like the following:
{
"question": {
"subject": "Germany",
"dataType": "string",
"relationship": "national language",
"type": "Second Form Object",
"plural": false,
"allowCF": true,
"allowUnknown": false,
"canAdd": true,
"prompt": "What is the national language of Germany?",
"knownAnswers": [],
"concepts": [
{
"conceptType": "language",
"name": "English",
"type": "string",
"value": "English"
},
{
"conceptType": "language",
"name": "French",
"type": "string",
"value": "French"
}
]
},
"sid": "25f02c14-e42e-4e91-9543-92336f613809"
}This has been asked because the knowledge map doesn't have information about Germany, including it's national language. The response endpoint must be used to respond to this question.
It is important to note that a query could return a resultResponse if it has all the data required to make a decision. This could be because it's encoded in the knowledge map, all the data required was included in the inject request, or the knowledge map is configured to make requests out to external datasources to fetch data.
Response
The response endpoint allows an array of answers to be sent to one or multiple questions. However the properties in the question object will dictate how you can respond (and how you might render this question and form inputs in a custom user interface).
In this example we can see the following:
"plural": false
A single fact must be returned for the subject and relationship of Germany -> national language
"allowCF": true
A level of certainty can be expressed in the response
"allowUnknown": false
A response containing the object value must be provided and so question cannot be skipped.
"canAdd": true
Instances outside of the concepts array (containing only English and French in this example) can be included in the response. When false, only instances in the concept array can be used.
Make a POST request to /{sessionID}/response with the following in the body:
{
"answers": [
{
"subject": "Germany",
"relationship": "national language",
"object": "German",
"certainty": "100"
}
]
}This should return a resultResponse that looks like the following suggesting Tom speaks German with 75% certainty:
{
"result": [
{
"subject": "Tom",
"relationshipType": "speaks",
"object": "German",
"certainty": 75,
"factID": "WA:RF:20ecfacf8825b6ace2645713fcbe0d0692b2fe49498156eba4b99776a95eaa51",
"relationship": "speaks"
}
],
"queryProfile": [],
"sid": "25f02c14-e42e-4e91-9543-92336f613809"
}If speaks was a plural relationship, the resultResponse may include multiple results.
Evidence
Evidence for how this fact was inferred can be requested from the evidence endpoint.
Make a GET request to /analysis/evidence{factID}/{sessionID}, which should return the following.
{
"factID": "WA:RF:20ecfacf8825b6ace2645713fcbe0d0692b2fe49498156eba4b99776a95eaa51",
"source": "rule",
"fact": {
"subject": {
"type": "person",
"value": "Tom",
"dataType": "string"
},
"relationship": {
"type": "speaks"
},
"object": {
"type": "language",
"value": "German",
"dataType": "string"
},
"certainty": 75
},
"time": 1751644730474,
"rule": {
"bindings": {
"COUNTRY": "Germany",
"O": "German",
"S": "Tom"
},
"conditions": [
{
"certainty": 100,
"factID": "WA:IF:4b51e33a91a6d13203ef5f4a041b2bc079903d00e69e262829742403aff43f0e",
"factKey": "414fcb69-0a58-4cde-a23a-be4b92a7bd54",
"impact": 37.5,
"object": "Germany",
"objectType": "string",
"relationship": "lives in",
"salience": 100,
"subject": "Tom"
},
{
"certainty": 100,
"factID": "WA:AF:5302d24b5e369eac902119aedce0c076a39096932ab97f9a78e0490b2cb02681",
"factKey": "cb7b0d31-cb16-4f76-af7a-7ffe6450c025",
"impact": 37.5,
"object": "German",
"objectType": "string",
"relationship": "national language",
"salience": 100,
"subject": "Germany"
}
],
"ruleMaxCertainty": 75
}
}Further information about the evidence tree can found in the evidence section.
The evidence for the conditions that satisfied the rule can also be viewed using the evidence endpoint by using their fact IDs and traversing the evidence tree. More information on retrieving the full evidence tree can be found here.
Last updated