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:

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.

  1. Start endpoint is called to start a new session.
  2. Query endpoint is called to perform a query. The response to query will contain either a question or a result.
  3. If a question has been returned, then the response endpoint should be called with an answer. This request may return another question.
  4. 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.

API Flow

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:

  1. By using the factID found in the result object of a Rainbird query, an initial request can be made to the evidence endpoint.

  2. The response will contain the information about the fact which the factID represents.

  3. 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.

  4. Loop through each condition.

  5. 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.