Rainbird API Guide
1 Overview
The Rainbird API docs are currently being improved as follows:
- Interactive docs: https://rainbird.redoc.ly/
- Extended documentation and supporting information for the interactive docs (this website).
It is therefore recommended that both resources are used.
In addition, please find SDKs for JavaScript and Go below:
- https://www.npmjs.com/package/@rainbird/sdk
- https://www.npmjs.com/package/@rainbird/sdk-react
- https://www.npmjs.com/package/@rainbird/sdk-react-material
- https://pkg.go.dev/gitlab.com/rainbird-ai/sdk-go
1.1 Interactive Documentation - Examples
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.
Description | Value |
---|---|
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.
A query
can be run against the speaks relationship in the following ways by making a POST request to /{sessionID}/query
:
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" }
1.2 API Request Flow
A common approach to using the Rainbird API is described in the diagram below.
- Start endpoint is called to start a new session.
- Query endpoint is called to perform a query. The response to query will contain either a question or a result.
- If a question has been returned, then the response endpoint should be called with an answer. This request may return another question.
- The response endpoint will return a result once the query has reached a conclusion.
In addition to the endpoints mentioned in the example flow, the inject endpoint can be used to inject facts into a Rainbird session. This can be used to inject data into Rainbird from other systems and/or to reduce the number of questions asked during an interaction before a result is returned. It is not recommended to inject more than 250 facts per request as this could lead to inconsistent responses.
2 Extended API Documentation
2.1 Environments
If you have a Community account the API can be accessed at:
https://api.rainbird.ai
For Enterprise users the API can be accessed at:
https://enterprise-api.rainbird.ai
2.2 Experimental and Alternate Engines
In addition to the default reasoning engine, if you have been provided the name of an experimental/alternate engine implementation you may interact with it by setting the x-rainbird-engine
HTTP header in all requests. Sessions started with the x-rainbird-engine
header set must include the header in all subsequent interaction with the session.
2.3 Errors
We use standard HTTP error codes to indicate success or failure of a request. Any request that returns HTTP 200 indicates success. Any HTTP 50x indicates that something failed server-side. If you see persistent HTTP 50x errors please contact us.
HTTP 40x errors indicate that something is wrong with your request. For instance:
Code | Meaning |
---|---|
400 | Your request is missing a required parameter |
401 | Your API key is invalid |
403 | Your API key does not permit access to the resource |
404 | The resource (session, KM etc.) could not be found |
2.4 Skipping an answer to a question
Depending on the configuration within the Knowledge Map, it may be possible to skip the answering of a question. This is indicated by passing "unanswered": true
in the answer object sent to /{sessionID}/response
. Example:
{
"answers": [
{
"subject": "Tom",
"relationship": "lives in",
"object":"",
"unanswered": true,
"certainty": 100
}
]
}
If the Knowledge Map doesn't allow the question to be skipped, then answering with "unanswered": true
won't be accepted and you will receive a 400 response containing:
{
"err": [
"Please provide an expected boolean value for unanswered."
]
}
2.5 Using scopes
When calling the start endpoint, you can optionally include a context ID. This allows facts to be shared between sessions on concepts and relationships that have the scope property set. This is performed by passing the contextid
query param.
https://api.rainbird.ai/start/{KNOWLEDGE_MAP_ID}?contextid={CONTEXT_ID}
2.6 Retrieving a full Evidence Tree for use with a custom UI or application
By utilising the evidence endpoint, it is possible to retrieve the full evidence tree behind a decision (a result of a query). The tree can be navigated by making additional requests to the evidence endpoint using factIDs returned in previous responses. Therefore, in order to retrieve the whole tree, you should expect to make a set of recursive requests.
Here is an example:
By using the factID found in the result object of a Rainbird query, an initial request can be made to the evidence endpoint.
The response will contain the information about the fact which the factID represents.
If the source of this fact was a rule, the response object will contain a rule object. Within the rule object, a conditions array will contain information about how each condition was satisfied.
Loop through each condition.
If the condition contains subject, relationship and object properties, it will also contain a factID property. In order to follow this branch of the Evidence Tree, you should now make an additional request to the evidence endpoint using the condition's factID and continue to step 2. If the condition doesn't contain a factID property, you are at the end of this branch.
This endpoint is optionally secured with a key, which can be configured via the Rainbird Studio. This key must then be provided in the x-evidence-key header to access evidence.