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

get

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
Path parameters
kmIDstringRequired

The knowledge map ID to start a session against

Query parameters
useDraftbooleanOptional

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

versionintegerOptional

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

Responses
200
Session start information
application/json
get
GET /start/{kmID} HTTP/1.1
Host: api.rainbird.ai
X-API-Key: YOUR_API_KEY
Accept: */*
200

Session start information

{
  "id": "12345678-1234-1234-1234567890ac",
  "kmVersion": {
    "id": "abcdefgh-abcd-abcd-abcdefghijkl"
  }
}

Inject - Inject facts into a session

post

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

Path parameters
sessionIDstringRequired

The session to inject facts into

Bodyobject[]
subjectstringRequired

The subject side concept instance or value

relationshipstringRequired

The relationship between subject and object

objectone ofRequired

The object side concept instance or value

stringOptional
or
numberOptional
or
booleanOptional
certaintynumber · min: 1 · max: 100Required

How certain this fact or answer is

Responses
200
Facts were injected successfully
application/json
post
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
  }
]
200

Facts were injected successfully

{
  "result": "OK"
}

Query - Query a running session

post

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.

Path parameters
sessionIDstringRequired

The session to query against

Body
subjectstringOptional

The subject side concept instance or value

relationshipstringRequired

The relationship between subject and object

objectone ofOptional

The object side concept instance or value

stringOptional
or
numberOptional
or
booleanOptional
Responses
200
An answer if one is reached, or a question
application/json
Responseone of
or
post
POST /{sessionID}/query HTTP/1.1
Host: api.rainbird.ai
Content-Type: application/json
Accept: */*
Content-Length: 42

{
  "subject": "John",
  "relationship": "speaks"
}
200

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"
  }
}

Response - Respond with an answer to a question

post

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.

Path parameters
sessionIDstringRequired

The session to send responses to

Body
Responses
200
An answer if one is reached, or a question
application/json
Responseone of
or
post
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
    }
  ]
}
200

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"
  }
}

Undo - Undoes the previous answer

post

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.

Path parameters
sessionIDstringRequired

The session to step back with an undo

Body
objectOptional
Responses
200
Session stepped back to a previous question or result
application/json
Responseone of
or
post
POST /{sessionID}/undo HTTP/1.1
Host: api.rainbird.ai
Content-Type: application/json
Accept: */*
Content-Length: 2

{}
200

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"
  }
}

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

post

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
Header parameters
VersionstringRequired

Version of the natural language API

Default: v1
Body
sessionIDstringRequired

The session ID needed to access that specific session

userPromptstringRequired

The user's prompt for natural language processing

Responses
200
Response to the user prompt
application/json
post
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"
}
200

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"
    ]
  }
}