Powered by Redocly

Rainbird API Documentation (1.2.0)

Download OpenAPI specification:Download

Welcome to the Rainbird API documentation. It contains details of the API calls required to query a Knowledge Map and view evidence for the decisions returned. Knowledge Maps must first be created via the Rainbird Studio. More information on this can be found here.

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

Decisions

Get decisions from your knowledge maps. Start a session, inject any available facts, run a query, provide a response to any questions asked and undo your answers to give a different response.

Note: query, response and undo endpoints can all return either a questionResponse (the reasoning engine needs more information) or a resultResponse (the decision).

Alternatively you can interact with the reasoning engine via natural language. This is in beta, is subject to change and responses may vary due to natural language interpretation.

Start - Start a new session

Start a session with the reasoning engine, specifying the knowledge map and (optionally) the version you require.

By default it will start a session using the live version. If no version has been set live it will default to 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. We recommend using a new session for each query, unless you need to make multiple queries within the same context.

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": "c1bf18d7-d1f0-44bc-a639-8cd4ded56dce",
  • "kmVersion": {
    }
}

Inject - Inject facts into a session

Inject an array of facts as triples. For large requests we recommend injecting in batches of 250 facts.

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

A query is the method to get decisions from your knowledge map. You query a relationship in the knowledge map and provide either the subject, the object or both. More information can be found here.

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": "Ben",
  • "relationship": "can claim"
}

Response samples

Content type
application/json
Example
QuestionResponse
QuestionResponse
ResultResponse
{
  • "question": {
    },
  • "sid": "c1bf18d7-d1f0-44bc-a639-8cd4ded56dce"
}

Response - Respond with an answer to a question

If you have received a questionResponse from the query, response or undo endpoints, you can submit an array of answers. These must be provided as triples.

Note: properties returned in the question object will determine how you can respond.

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
QuestionResponse
QuestionResponse
ResultResponse
{
  • "question": {
    },
  • "sid": "c1bf18d7-d1f0-44bc-a639-8cd4ded56dce"
}

Undo - Undoes the previous answer

A method to undo the previous answer array posted to the response endpoint. This rolls back the session, removing any facts inferred from the answer array and returns the original question. A different answer can be provided or undo can be used again to further roll-back the session.

Note: when there are no further answers to undo, the same question will be returned.

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
QuestionResponse
QuestionResponse
ResultResponse
{
  • "question": {
    },
  • "sid": "c1bf18d7-d1f0-44bc-a639-8cd4ded56dce"
}

Interact (BETA) - natural language injection, queries and question responses

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

question

If a questionResponse 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 questionResponse 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 resultResponse is received, this contains the answer to the user's original question and can be presented as required. Once a resultResponse 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
Example
query
query
response
{
  • "sessionID": "bdef015c-0ab4-417c-982f-b8d9ff48efc1",
  • "userPrompt": "Can Ben claim?"
}

Response samples

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

Evidence

Access the facts, information and the chain of reasoning that led to a decision

Evidence - Returns the evidence for a given fact

View the source of the fact, including how it was derived when inferred from a rule.

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:82a7b990eb2fe491389f37de10b1cd752cbd692b8c2c0d3fb36b354491f68173",
  • "source": "rule",
  • "fact": {
    },
  • "time": 1752142054143,
  • "rule": {
    }
}

Interaction Log - Retrieves interaction events

View a log of interaction events within the session, including queries, injected facts, questions asked, answers given and results returned.

Note: interaction log recording is switched off by default. It must be enabled in the Studio per version per knowledge map. Only sessions started after it is enabled will be recorded.

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
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Session - Returns session information

Access session information, such as all of the facts available within a session, or version information for the knowledge map used in a session.

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
Example
version
version
facts
{
  • "km": {
    }
}

Explain (BETA) - Returns a natural language explanation of the evidence tree

Get a natural language explanation of the chain of reasoning for any given 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": "en",
  • "sessionID": "bdef015c-0ab4-417c-982f-b8d9ff48efc1",
  • "factID": "WA:RF:e1d3a2380a814cea00d5a1adf69b2cdafba0e0228192cd8014400925bb4422ea"
}

Response samples

Content type
application/json
{
  • "explanation": "Based on the information provided, Ben can claim for a repair. This decision is supported by several key facts:\n\nBen holds a Gold policy, which provides comprehensive coverage for his mobile phone. The Gold policy specifically covers water damage, which is the type of loss Ben has suffered. \n\nThe incident in question involves water damage to Ben's mobile phone. This aligns with the coverage provided by his Gold policy, as the policy explicitly insures mobile phones and covers water damage.\n\nIn response to this type of loss, a repair claim is deemed appropriate. The Gold policy includes provisions for repair claims, making this a suitable course of action for addressing the water damage to Ben's mobile phone.\n\nAll of these factors come together to support the conclusion that Ben is eligible to claim for a repair of his water-damaged mobile phone under his Gold policy.",
  • "metadata": {
    }
}

Platform

Retrieve information about the Rainbird Platform itself.

Version - Reports engine version

Authorizations:

Responses

Request samples 

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

Response samples

Content type
text/plain
4.89.0