rainbird-docs

Repository for documentation such as the API guide.

View project on GitHub

Rainbird API Guide

1. Overview

The Rainbird API provides a REST based interface for querying knowledge maps built in the Rainbird platform. We provide endpoints for querying, responding to questions and injecting data.

Every interaction is done within a session. A session provides a mechanism for Rainbird to learn facts, inferences and weightings from one query to the next.

The API can be accessed only via HTTPS. It uses HTTP authentication and standard HTTP error codes. Attempts to access the API by HTTP will fail and not be redirected. We also support cross-origin resource sharing so you can interact with our API from your own web-based clients.

All API requests return JSON objects (including errors) which are described in this document.

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

In all code examples any sections wrapped in curly braces are to be replaced with your own knowledge map ID, API key and session data. Examples are given as simple curl commands. If you have curl installed you can run them directly by copying and pasting them into your terminal.

For example, to start a new session:

curl https://api.rainbird.ai/start/{KMID} -u {API_KEY}:

KMID Button in the Rainbird editor

Your KMID can be found by clicking the KMID button when editing your map.

Note that curl uses -u to pass the user. The : character tells curl not to prompt for a password.

3. Using the API

All interactions with the API must be done within a session on a specific knowledge map you’ve created in Rainbird. To generate a new session, or to retrieve one you have stored under an alias, use the start endpoint. You then query and respond as required.

The basic flow is as follows:

1. Start a new session

You start a new session for a knowledge map by calling the start endpoint with the KMID you require – passing your API key using HTTP basic authentication.

2. Query

Using the session ID you’ve just received or a previous session you’ve saved, pose a query to the Rainbird engine. This will either return a result or a question.

3. Respond to any questions

If a question was returned, you’ll need to send a response. This may return further questions or a set of solutions.

4. Authentication

All requests must be authenticated.

You authenticate a request to the API using your API key. Your API key can be found in your profile. Your API key is valuable and uniquely identifies you. Be sure to keep it secure and secret as it provides access to your Rainbird account.

If you think your API key has been compromised, please contact us immediately.

Authentication is performed using HTTP Basic Authentication. You should pass your API key as your user name. You do not need to provide a password.

You can only access our API via HTTPS. Any request via HTTP will fail and not be redirected.

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

All errors return an error object.

The Error Object:

{
	"error": "Human readable error message detailing what went wrong.""
}

6. Methods

6.1 start

GET: - https://api.rainbird.ai/start/{KNOWLEDGE_MAP_ID}?alias={CONTEXT_ID_ALIAS}

Every query or response must be made in a session. You create a session by calling the /start endpoint. Sessions never expire.

The /start endpoint is authenticated. You must pass your API key in the HTTP basic authentication header.

Optionally you can include a context ID alias. This allows facts to be shared between sessions on relationships that are tagged with ‘scope=”context”‘.

Parameters

{knowledge_map_id}

(required) The ID of the knowledge map this session will be opened for. The knowledge map must have been created by the owner of the API key provided.

Example

curl https://api.rainbird.ai/start/{KMID} -u {API_KEY}:

Returns

id

The session ID you’ll use for subsequent calls to the API.

kmVersion

The kmVersion which will be used for this session. This will be the live version of the knowledge map ID in the request to /start.

Example

{
 “id”: “103c65f6-ac52-4b87-b15a-a412112c05a8",
 “kmVersion”: {
 “id”: “a73647df-1e50-4bdd-9dc4-8b60137ee741”
 }
}

6.2 query

POST: - https://api.rainbird.ai/{SESSION_ID}/query

Start a new query. You query Rainbird for a relationship instance (triple) with at least one unknown concept instance. For example (Person:John)-[speaks]->().

You must query within a session previously started via a call to /start. Leaving any of the parameters empty prompts Rainbird to infer for a potential match.

Parameters

{session_id}

(required) The session ID created via call to /start.

subject

(optional) A subject side concept instance

relationship

(required) The relationship to query for

object

(optional) The object side concept instance

Returns

If a result is found (or the query has failed), without needing further consultation, a result object will be returned. Otherwise a question object is returned.

Example

curl https://api.rainbird.ai/{SESSION_ID}/query 
-d '{"subject":"John", "relationship":"speaks"}'
-H "Content-Type: application/json"

6.3 response

POST: - https://api.rainbird.ai/{SESSION_ID}/response

Respond to a previous question. Questions my be returned from a call to the /query endpoint or from a previous call to /response.

The response endpoint allows you to return plural answers with differing certainty to second form questions. If you return multiple answers to a first form question only the first answer will be used.

Parameters

{session_id}

(required) The session ID created via call to /start.

answers

(required) An array of answers containing:

subject – The subject side concept instance relationship – The relationship for the question object – The object side concept instance cf – The certainty of this answer (from 0 – 100) answer – Required for first form questions only – ‘yes’ or ‘no’ unanswered – (optional) boolean, true or false to omit answering a question

Returns

If a result is found (or the query has failed), without needing further consultation, a result object will be returned. Otherwise, a question object is returned.

Example

curl https://api.rainbird.ai/{SESSION_ID}/response 
        -d '{"answers": 
                [{"subject":"John","relationship":"lives in","object":"England", "cf":"85"}]}'
        -H "Content-Type: application/json"

6.4 inject

POST: - https://api.rainbird.ai/{SESSION_ID}/inject

Assert a new fact within a session, outside of a question / response consultation. This endpoint is useful when asserting new data collected via a process outside of Rainbird (a user form for instance).

Parameters

{session_id}

(required) The session ID created via call to /start.

data

(required) An array of facts to assert:

subject – The subject side concept instance relationship – The relationship for the question object – The object side concept instance cf (optional) – The certainty of this answer (from 0 – 100)

Returns

OK on success or an error if something went wrong.

Example

curl https://api.rainbird.ai/{SESSION_ID}/inject
        -d '[{"subject":"John","relationship":"lives in","object":"England", "cf":"85"}]'
        -H "Content-Type: application/json"

6.5 undo

POST: - https://api.rainbird.ai/{SESSION_ID}/undo

To ‘undo’ the previous answer provided to the ‘response’ endpoint, submit a request to the /undo endpoint.

Parameters

{session_id}

(required) The session ID created via call to /start.

data

(required) An empty object.

Returns

If a result is found (or the query has failed), without needing further consultation, a result object will be returned. Otherwise, a question object is returned.

Example

curl https://api.rainbird.ai/{SESSION_ID}/undo
        -d '{}'
        -H "Content-Type: application/json"

6.6 version

GET: - https://api.rainbird.ai/version

Returns the latest API version number.

7. Response Objects

The following object may be returned by a call to /query or /response.

7.1 question

When Rainbird needs more information to continue, it will ask a question. This object holds the details.

{
 "question": {
 "subject": The subject side concept instance if known,

"relationship": The relationship this question is for,

"prompt": A natural language string for this question,

"type": One of: ‘First Form’ or ‘Second Form’,

"plural": boolean - indicates if this relationship is plural and can hold multiple answers,

"allowUnknown": boolean - indicates if ‘unknown’ is a valid answer,

"allowCF": boolean - indicates if uncertain answers will be accepted,

"concepts": An array of potentially valid answers
 [
 {
 "name": The name of this instance,

"conceptType": The type of concept this is an instance of,

"type": The data type of this instance,

"value": A display value for this instance,

"dynamic": boolean - indicates if this instance is automatically generated,

"metadata": Any metadata associated with this instance
 "fsid": internal use,
 "invalidResponse": If present and boolean true this concept is not a valid answer
}, ] }, "stats": {…}, 
"sid": The session ID this question relates to 
}

7.2 result

When Rainbird finds a solution to a query, a response object is returned with the potential values and their certainties.

{
"result": An array of results
[
{
"relationshipType": The name of the relationship the
query was for,

"certainty": How certain this answer is,

"subject": The subject side concept instance,

"object": The object side concept instance,

"objectMetadata": If it exists the object side meta
data,

"subjectMetadata": If it exists the subject side meta
data

"factID": ID used to fetch the evidence tree that lead
to this decision
}
],
"stats": {...},
"sid": The session
ID this question relates to
}

8. Evidence Tree

The Evidence Tree is the part of the system which captures the reasoning behind each fact used in a final answer. It provides an ‘audit-trail’ of the systems decisions.

When a Rainbird inferencing session ends with one or more result facts, each fact will have an associated evidence tree. This evidence tree can be explored by using the factID property from the fact object.

8.1 Evidence Tree Endpoints

8.1.1 analysis/evidence

GET: - https://api.rainbird.ai/analysis/evidence/{FACT_ID}

Retrieves a section of the evidence tree for the provided factID.

Parameters

{FACT_ID}

(required) The factID of a fact.

Returns

An object identifying the source of the fact, the fact itself and if the source was a rule, information about conditions used in the rule.

Each condition will contain a factID which can be followed, using this endpoint, to get the next section of the evidence tree.

The complete list of fact ‘sources’ with their meanings is as follows:

  • ‘km’ - This fact is defined in the knowledge-map.

  • ‘rule’ - This fact was created by a rule.

  • ‘answer’ - The system asked a question and the user gave this fact as an answer.

  • ‘injection’ - Indicates that the fact was injected using the API.

  • ‘datasource’ - The knowledgemap defines a datasource which was called during inference and provided this fact.

  • ‘synthesis’ - A synthetic fact is used when a rule condition is not mandatory. During an inference, if a fact cannot be found for a non-mandatory rule condition, we ‘synthesise’ that fact (with zero certainty) to allow the rule to continue running.

For all sources other than ‘km’ and ‘synthesis’ the time in milliseconds that the fact was created will also be added to the result object.

Example


GET: - https://api.rainbird.ai/analysis/evidence/WA:RF:46270715222c02dca319bd10

{
    "factID": "WA:RF:46270715222c02dca319bd10",
    "source": "rule",
    "fact": {
        "subject": {
            "type": "person",
            "value": "Bob",
            "dataType": "string"
        },
        "relationship": {
            "type": "speaks"
        },
        "object": {
            "type": "language",
            "value": "English",
            "dataType": "string"
        },
        "certainty": 75
    },
    "time": 1522060091106,
    "rule": {
        "bindings": {
            "S": "Bob",
            "O": "English",
            "COUNTRY": "England"
        },
        "conditions": [
            {
                "subject": "England",
                "relationship": "national language",
                "object": "English",
                "salience": 100,
                "certainty": 100,
                "factID": "WA:KF:7ccf0415f3af204b5eb3",
                "objectType": "string"
            },
            {
                "subject": "Bob",
                "relationship": "lives in",
                "object": "England",
                "salience": 100,
                "certainty": 100,
                "factID": "WA:AF:8e5b2c204b5eb3b24ba1",
                "objectType": "string"
            }
        ]
    }
}

8.2 Retrieving a full Evidence Tree for use with a custom UI or application

By utilising the evidence endpoint in section 8.1, 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.