Powered by Redocly

Rainbird Engine - v2.0 (1.2.0)

Download OpenAPI specification:Download

Welcome to the Rainbird API documentation for the v2.0 engine. It contains details of the API calls required to perform Rainbird queries against a Knowledge Map

Authentication

apiKey

Authentication with the Rainbird API uses a user key, passed in the header. This can be found on the Account page or with the controls for publishing a Knowledge Map.

Our legacy authentication method of HTTP BasicAuth continues to be supported, but we highly advise transitioning to the new method.

Security Scheme Type API Key
Header parameter name: X-API-Key

evidenceKey

To access secured evidence, you should pass your evidence key

Security Scheme Type API Key
Header parameter name: x-evidence-key

interactionKey

To access secured interaction logs, you should pass your interaction key

Security Scheme Type API Key
Header parameter name: x-interaction-key

Core

Start - Start a new session

This endpoint starts a new session that can be used in subsequent API calls. By default it will start a session using the live version of the given knowledge map. If no version has been set live it will default to using the draft version. Alternatively the query parameters “useDraft” or “version” can be used as an override to request either the draft or a specific version.

Authorizations:
apiKey
path Parameters
kmID
required
string

The knowledge map ID to start a session against

query Parameters
useDraft
boolean

Flag to use the draft version of the knowledge map, cannot be used simultaneously with 'version' parameter

version
integer

Parameter to use a specific version of the map, cannot be used simultaneously with 'useDraft' parameter

Responses

Request samples 

curl -i -X GET \
  'https://api.rainbird.ai/start/:kmID?useDraft=true&version=0' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "12345678-1234-1234-1234567890ac",
  • "kmVersion": {
    }
}

Inject - Inject facts into a session

Authorizations:
path Parameters
sessionID
required
string

The session to inject facts into

Request Body schema: application/json

Array of facts to inject

Array ()
subject
required
string (Subject)

The subject side concept instance or value

relationship
required
string (Relationship)

The relationship between subject and object

required
string or number or boolean (Object)

The object side concept instance or value

certainty
required
number (Certainty) [ 1 .. 100 ]

How certain this fact or answer is

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "result": "OK"
}

Query - Query a running session

Authorizations:
path Parameters
sessionID
required
string

The session to query against

Request Body schema: application/json

Query for the engine to try to answer

subject
string (Subject)

The subject side concept instance or value

relationship
required
string (Relationship)

The relationship between subject and object

string or number or boolean (Object)

The object side concept instance or value

Responses

Request samples

Content type
application/json
{
  • "subject": "John",
  • "relationship": "speaks"
}

Response samples

Content type
application/json
Example
ResultResponse
ResultResponse
QuestionResponse
{
  • "result": [
    ],
  • "queryProfile": [ ],
  • "sid": "string",
  • "stats": { }
}

Response - Respond to an asked question

Authorizations:
path Parameters
sessionID
required
string

The session to send responses to

Request Body schema: application/json

Items to send as a response

Array of objects

Responses

Request samples

Content type
application/json
{
  • "answers": [
    ]
}

Response samples

Content type
application/json
Example
ResultResponse
ResultResponse
QuestionResponse
{
  • "result": [
    ],
  • "queryProfile": [ ],
  • "sid": "string",
  • "stats": { }
}

Undo - Undoes previous interaction with the engine

Authorizations:
path Parameters
sessionID
required
string

The session to step back with an undo

Request Body schema: application/json

An empty object

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
Example
ResultResponse
ResultResponse
QuestionResponse
{
  • "result": [
    ],
  • "queryProfile": [ ],
  • "sid": "string",
  • "stats": { }
}

Version - Reports engine version

Authorizations:

Responses

Request samples 

curl -i -X GET \
  https://api.rainbird.ai/version

Analysis

Evidence - Returns the evidence for a given fact

Authorizations:
evidenceKey
path Parameters
factID
required
string

The factID for which to retrieve evidence

sessionID
required
string

The sessionID where the fact was created

Responses

Request samples 

curl -i -X GET \
  https://api.rainbird.ai/analysis/evidence/:factID/:sessionID

Response samples

Content type
application/json
{
  • "factID": "WA:RF:46270715221c02dca319bd10",
  • "source": "rule",
  • "fact": {
    },
  • "time": 1522060091106,
  • "rule": {
    }
}

Interaction Log - Retrieves interaction events

Authorizations:
interactionKey
path Parameters
sessionID
required
string

The session id to access the interaction logs

query Parameters
format
string

Format of the retrieved data. CSV or JSON

Responses

Request samples 

curl -i -X GET \
  'https://api.rainbird.ai/analysis/interactions/:sessionID?format=string'

Response samples

Content type
application/json
Example
start
start
questions
query
answers
results
inject
datasource
{
  • "values": {
    },
  • "event": "start",
  • "created": "2022-03-04T10:13:04.224Z"
}

Session - Returns session information

Authorizations:
apiKey
path Parameters
sessionID
required
string

The sessionID of the session

query Parameters
filter
Array of strings
Default: ["version"]

The type of information requested.

Items Enum: "version" "facts"
relationships
Array of strings

A comma-separated list of relationships to filter the session data by.

Responses

Request samples 

curl -i -X GET \
  'https://api.rainbird.ai/analysis/session/:sessionID?filter=version&relationships=string' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "km": {
    },
  • "facts": {
    }
}

Natural Language (beta)

The Natural Language APIs are currently in beta. They are unsupported and are subject to change. They rely on an external service provided by OpenAI. The knowledge map and any data you provide will be processed by them. By using this API you will be bound by OpenAI’s terms and conditions. To protect your data we recommend the following:

  1. Do not share personal data about yourself or others
  2. Do not disclose sensitive business data
  3. Use hypothetical scenarios or anonymised data
  4. Do not use with knowledge maps you would deem to contain confidential information As a beta feature, response times and consistency might vary.

Interact

Given a body of text, the endpoint will return a question, result or an error.

question

If a question response is received, the question prompt can be displayed in a UI or used to embed and search a vector store to solicit an answer. The data containing the answer can be resubmitted in a new interact request, ensuring the same session ID is used. Please note: when a question response has been received, the session is locked to the current query in progress. Therefore, if any additional requests contain a new question asked to Rainbird, the new question will be ignored until a result is received.

result

If a result response is received, this contains the answer to the user's original question and can be presented as required. Once a result response is received, the session is unlocked and further queries can be made in that session.

error

If an error response is received, this may be due to an internal error, but it can also be caused by such things as not being able to detect the query, the question being asked in an unfamiliar way, or the knowledge map not being designed to answer it. A suggested error response is included that can be used in chat interfaces. Alternatively, the error code can be mapped to your own custom error messages.

Authorizations:
apiKey
header Parameters
Version
required
string
Default: v1

Version of the natural language API

Request Body schema: application/json

User prompt for natural language processing

sessionID
required
string

The session ID needed to access that specific session

userPrompt
required
string

The user's prompt for natural language processing

Responses

Request samples

Content type
application/json
{
  • "sessionID": "string",
  • "userPrompt": "string"
}

Response samples

Content type
application/json
{
  • "responseType": "question",
  • "query": {
    },
  • "questions": {
    },
  • "results": [
    ],
  • "error": {
    },
  • "metadata": {
    },
  • "facts": {
    }
}

Explain

The 'explain' endpoint processes a body of text, generating a natural language exposition of the evidence based on the user-provided session and fact.

Authorizations:
apiKey
header Parameters
Version
required
string
Default: v1

Version of the natural language API

Request Body schema: application/json

Language, factID, and sessionID for natural language processing

language
required
string

The users preferred language setting i.e. "en", "za"

sessionID
required
string

The session ID needed to access that specific session

factID
required
string

The ID of a fact specific to that session to retrieve data from

Responses

Request samples

Content type
application/json
{
  • "language": "string",
  • "sessionID": "string",
  • "factID": "string"
}

Response samples

Content type
application/json
{
  • "explanation": "string",
  • "error": {
    },
  • "metadata": {
    }
}