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 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.
The knowledge map ID to start a session against
Flag to use the draft version of the knowledge map, cannot be used simultaneously with 'version' parameter
Parameter to use a specific version of the map, cannot be used simultaneously with 'useDraft' parameter
GET /start/{kmID} HTTP/1.1
Host: api.rainbird.ai
X-API-Key: YOUR_API_KEY
Accept: */*
Session start information
{
"id": "12345678-1234-1234-1234567890ac",
"kmVersion": {
"id": "abcdefgh-abcd-abcd-abcdefghijkl"
}
}Inject an array of facts as triples. For large requests we recommend injecting in batches of 250 facts.
The session to inject facts into
The subject side concept instance or value
The relationship between subject and object
The object side concept instance or value
How certain this fact or answer is
POST /{sessionID}/inject HTTP/1.1
Host: api.rainbird.ai
Content-Type: application/json
Accept: */*
Content-Length: 240
[
{
"subject": "John",
"relationship": "lives in",
"object": "England",
"certainty": 100
},
{
"subject": "John",
"relationship": "lives in",
"object": "Germany",
"certainty": 100
},
{
"subject": "John",
"relationship": "born in",
"object": "England",
"certainty": 100
}
]Facts were injected successfully
{
"result": "OK"
}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.
The session to query against
The subject side concept instance or value
The relationship between subject and object
The object side concept instance or value
POST /{sessionID}/query HTTP/1.1
Host: api.rainbird.ai
Content-Type: application/json
Accept: */*
Content-Length: 42
{
"subject": "John",
"relationship": "speaks"
}An answer if one is reached, or a question
{
"result": [
{
"subject": "text",
"relationshipType": "text",
"object": "text",
"certainty": 1,
"factID": "text",
"relationship": "text",
"subjectMetadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"objectMetadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"queryProfile": [],
"sid": "text",
"stats": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}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.
The session to send responses to
POST /{sessionID}/response HTTP/1.1
Host: api.rainbird.ai
Content-Type: application/json
Accept: */*
Content-Length: 93
{
"answers": [
{
"subject": "John",
"relationship": "lives in",
"object": "England",
"certainty": 100
}
]
}An answer if one is reached, or a question
{
"result": [
{
"subject": "text",
"relationshipType": "text",
"object": "text",
"certainty": 1,
"factID": "text",
"relationship": "text",
"subjectMetadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"objectMetadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"queryProfile": [],
"sid": "text",
"stats": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}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.
The session to step back with an undo
POST /{sessionID}/undo HTTP/1.1
Host: api.rainbird.ai
Content-Type: application/json
Accept: */*
Content-Length: 2
{}Session stepped back to a previous question or result
{
"result": [
{
"subject": "text",
"relationshipType": "text",
"object": "text",
"certainty": 1,
"factID": "text",
"relationship": "text",
"subjectMetadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"objectMetadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"queryProfile": [],
"sid": "text",
"stats": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}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.
Version of the natural language API
v1The session ID needed to access that specific session
The user's prompt for natural language processing
POST /nl/interact HTTP/1.1
Host: api.rainbird.ai
X-API-Key: YOUR_API_KEY
Version: v1
Content-Type: application/json
Accept: */*
Content-Length: 40
{
"sessionID": "text",
"userPrompt": "text"
}Response to the user prompt
{
"responseType": "question",
"query": {
"subject": "text",
"relationship": "text",
"object": "text"
},
"questions": {
"subject": "text",
"object": "text",
"objectType": "text",
"objectMetadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"dataType": "text",
"relationship": "text",
"type": "text",
"plural": true,
"allowCF": true,
"allowUnknown": true,
"canAdd": true,
"prompt": "text",
"knownAnswers": [],
"concepts": [
{
"conceptType": "text",
"name": "text",
"type": "text",
"value": "text",
"invalidResponse": true
}
]
},
"results": [
{
"Certainty": 1,
"FactID": "text",
"Object": "text",
"ObjectMetadata": {},
"ObjectValue": "text",
"Relationship": "text",
"Subject": "text",
"SubjectMetadata": {},
"SubjectValue": "text"
}
],
"error": {
"code": 1,
"message": "text",
"suggestedChatResponse": "text",
"statusCode": "text"
},
"metadata": {
"querySubmittedAt": "2025-07-10T10:31:22.137Z",
"languageEngineResponseTime": 1,
"llmTokens": {
"completionTokens": 1,
"promptTokens": 1,
"totalTokens": 1
},
"apiVersion": "text",
"endpoint": "text",
"sessionID": "text"
},
"facts": {
"injected": [
{
"subject": "text",
"relationship": "text",
"object": "text",
"certainty": 1
}
],
"invalid": [
{
"subject": "text",
"relationship": "text",
"object": "text",
"certainty": 1
}
],
"unmatched": [
"text"
]
}
}