# Example API requests Below guides you through an example set of API requests to **start** a session, **inject** a fact, run a **query**, provide a **response** to a question, receive a decision and request the **evidence** for this result. If you have followed our [quickstart guide](https://docs.rainbird.ai/rainbird/getting-started/quickstart-guide) to build a HelloWorld knowledge map, you could use your own API key and Knowledge Map ID. Alternatively you can use the details below to access our example HelloWorld knowledge map. **OpenAPI specifications** Documentation for the Rainbird API schema is available in the [API reference](https://docs.rainbird.ai/rainbird/developer-docs/api-reference/decisions) section. However if you are using an API platform such as Postman, you can create a collection from our [OpenAPI specifications](https://api.rainbird.ai/docs/openapi.yaml). | Description | Value | | ---------------- | ------------------------------------ | | API Base URL | | | 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. ```json { "id": "25f02c14-e42e-4e91-9543-92336f613809", "kmVersion": { "id": "dcfec17b-83b1-4029-bd75-6984734538ba" } } ``` ## 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. ```json [ { "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. 1. To find what language Tom speaks (Tom -> speaks -> ?), pass subject and relationship: ```json { "subject": "Tom", "relationship": "speaks" } ``` 2. To find who speaks French (? -> speaks -> French), pass relationship and object: ```json { "relationship": "speaks", "object": "French" } ``` 3. To check if Tom speaks French (Tom -> speaks -> French), pass subject, relationship and object: ```json { "subject": "Tom", "relationship": "speaks", "object": "French" } ``` Using the first query for `Tom -> speaks -> ?` you should receive a **questionResponse** that looks like the following: ```json { "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:
PropertyImpact to the response
"plural": falseA single fact must be returned for the subject and relationship of Germany -> national language
"allowCF": trueA level of certainty can be expressed in the response
"allowUnknown": falseA response containing the object value must be provided and so question cannot be skipped.
"canAdd": trueInstances 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: ```json { "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: ```json { "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. ```json { "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](https://docs.rainbird.ai/rainbird/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](https://docs.rainbird.ai/rainbird/developer-docs/api-guide/retrieving-a-full-evidence-tree-for-use-with-a-custom-ui-or-application).