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/{kmID}

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

X-API-KeystringRequired

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.

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

/start/{kmID}

GET /start/{kmID} HTTP/1.1
Host: api.rainbird.ai
X-API-Key: YOUR_API_KEY
Accept: */*

200

Session start information

{
  "id": "c1bf18d7-d1f0-44bc-a639-8cd4ded56dce",
  "kmVersion": {
    "id": "77135768-7634-49f0-9fbf-ed915ce08a66"
  }
}

Inject - Inject facts into a session

post

/{sessionID}/inject

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

numberOptional

booleanOptional

certaintynumber · min: 1 · max: 100Required

How certain this fact or answer is

Responses

200

Facts were injected successfully

application/json

post

/{sessionID}/inject

POST /{sessionID}/inject HTTP/1.1
Host: api.rainbird.ai
Content-Type: application/json
Accept: */*
Content-Length: 74

[
  {
    "subject": "Ben",
    "relationship": "holds",
    "object": "Gold",
    "certainty": 100
  }
]

200

Facts were injected successfully

{
  "result": "OK"
}

Query - Query a running session

post

/{sessionID}/query

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

numberOptional

booleanOptional

Responses

200

An answer if one is reached, or a question

application/json

Responseone of

post

/{sessionID}/query

POST /{sessionID}/query HTTP/1.1
Host: api.rainbird.ai
Content-Type: application/json
Accept: */*
Content-Length: 44

{
  "subject": "Ben",
  "relationship": "can claim"
}

200

An answer if one is reached, or a question

{
  "question": {
    "subject": "Ben",
    "dataType": "string",
    "relationship": "suffered",
    "type": "Second Form Object",
    "plural": true,
    "allowCF": true,
    "allowUnknown": false,
    "canAdd": true,
    "prompt": "What type of loss has Ben suffered?",
    "knownAnswers": [],
    "concepts": [
      {
        "conceptType": "loss",
        "name": "cosmetic damage",
        "type": "string",
        "value": "cosmetic damage"
      },
      {
        "conceptType": "loss",
        "name": "water damage",
        "type": "string",
        "value": "water damage"
      },
      {
        "conceptType": "loss",
        "name": "loss",
        "type": "string",
        "value": "loss"
      },
      {
        "conceptType": "loss",
        "name": "theft",
        "type": "string",
        "value": "theft"
      }
    ]
  },
  "sid": "c1bf18d7-d1f0-44bc-a639-8cd4ded56dce"
}

Response - Respond with an answer to a question

post

/{sessionID}/response

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

post

/{sessionID}/response

POST /{sessionID}/response HTTP/1.1
Host: api.rainbird.ai
Content-Type: application/json
Accept: */*
Content-Length: 97

{
  "answers": [
    {
      "subject": "Ben",
      "relationship": "suffered",
      "object": "water damage",
      "certainty": 100
    }
  ]
}

200

An answer if one is reached, or a question

{
  "question": {
    "subject": "Ben",
    "dataType": "string",
    "relationship": "suffered",
    "type": "Second Form Object",
    "plural": true,
    "allowCF": true,
    "allowUnknown": false,
    "canAdd": true,
    "prompt": "What type of loss has Ben suffered?",
    "knownAnswers": [],
    "concepts": [
      {
        "conceptType": "loss",
        "name": "cosmetic damage",
        "type": "string",
        "value": "cosmetic damage"
      },
      {
        "conceptType": "loss",
        "name": "water damage",
        "type": "string",
        "value": "water damage"
      },
      {
        "conceptType": "loss",
        "name": "loss",
        "type": "string",
        "value": "loss"
      },
      {
        "conceptType": "loss",
        "name": "theft",
        "type": "string",
        "value": "theft"
      }
    ]
  },
  "sid": "c1bf18d7-d1f0-44bc-a639-8cd4ded56dce"
}

Undo - Undoes the previous answer

post

/{sessionID}/undo

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

post

/{sessionID}/undo

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

{
  "question": {
    "subject": "Ben",
    "dataType": "string",
    "relationship": "suffered",
    "type": "Second Form Object",
    "plural": true,
    "allowCF": true,
    "allowUnknown": false,
    "canAdd": true,
    "prompt": "What type of loss has Ben suffered?",
    "knownAnswers": [],
    "concepts": [
      {
        "conceptType": "loss",
        "name": "cosmetic damage",
        "type": "string",
        "value": "cosmetic damage"
      },
      {
        "conceptType": "loss",
        "name": "water damage",
        "type": "string",
        "value": "water damage"
      },
      {
        "conceptType": "loss",
        "name": "loss",
        "type": "string",
        "value": "loss"
      },
      {
        "conceptType": "loss",
        "name": "theft",
        "type": "string",
        "value": "theft"
      }
    ]
  },
  "sid": "c1bf18d7-d1f0-44bc-a639-8cd4ded56dce"
}

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

post

/nl/interact

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

X-API-KeystringRequired

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.

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

/nl/interact

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: 82

{
  "sessionID": "bdef015c-0ab4-417c-982f-b8d9ff48efc1",
  "userPrompt": "Can Ben claim?"
}

200

Response to the user prompt

{
  "responseType": "question",
  "facts": {},
  "metadata": {
    "querySubmittedAt": "2025-07-10T10:49:13.231973361Z",
    "languageEngineResponseTime": 2173,
    "llmTokens": {
      "completionTokens": 52,
      "promptTokens": 3117,
      "totalTokens": 3169
    },
    "apiVersion": "",
    "endpoint": "interact",
    "sessionID": "bdef015c-0ab4-417c-982f-b8d9ff48efc1"
  },
  "query": {
    "subject": "Ben",
    "relationship": "can claim",
    "object": null
  },
  "questions": [
    {
      "allowCF": true,
      "canAdd": true,
      "concepts": [
        {
          "conceptType": "policy",
          "name": "Gold",
          "type": "string",
          "value": "Gold"
        },
        {
          "conceptType": "policy",
          "name": "Silver",
          "type": "string",
          "value": "Silver"
        },
        {
          "conceptType": "policy",
          "name": "Bronze",
          "type": "string",
          "value": "Bronze"
        }
      ],
      "dataType": "string",
      "prompt": "Which policy does Ben hold?",
      "relationship": "holds",
      "subject": "Ben",
      "type": "Second Form Object"
    }
  ],
  "results": null
}

Last updated 1 month ago

hashtagStart - Start a new session

hashtagInject - Inject facts into a session

hashtagQuery - Query a running session

hashtagResponse - Respond with an answer to a question

hashtagUndo - Undoes the previous answer

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

hashtagquestion

hashtagresult

hashtagerror

Start - Start a new session

Inject - Inject facts into a session

Query - Query a running session

Response - Respond with an answer to a question

Undo - Undoes the previous answer

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

question

result

error