Evidence

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

Evidence - Returns the evidence for a given fact

get

/analysis/evidence/{factID}/{sessionID}

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

Authorizations

Path parameters

factIDstringRequired

The factID for which to retrieve evidence

sessionIDstringRequired

The sessionID where the fact was created

Responses

200

Fact detail

application/json

get

/analysis/evidence/{factID}/{sessionID}

GET /analysis/evidence/{factID}/{sessionID} HTTP/1.1
Host: api.rainbird.ai
Accept: */*

200

Fact detail

{
  "factID": "WA:RF:82a7b990eb2fe491389f37de10b1cd752cbd692b8c2c0d3fb36b354491f68173",
  "source": "rule",
  "fact": {
    "subject": {
      "type": "policy holder",
      "value": "Ben",
      "dataType": "string"
    },
    "relationship": {
      "type": "can claim"
    },
    "object": {
      "type": "claim",
      "value": "repair",
      "dataType": "string"
    },
    "certainty": 100
  },
  "time": 1752142054143,
  "rule": {
    "bindings": {
      "EQUIPMENT": "mobile phone",
      "LOSS": "water damage",
      "O": "repair",
      "POLICY": "Gold",
      "S": "Ben"
    },
    "conditions": [
      {
        "certainty": 100,
        "factID": "WA:IF:af4d81cc4d1175c0c488d6632599f718520366541ce99e61fc83eff7f640749a",
        "factKey": "9c141933-344b-4d36-a3ef-ffdd96fbcb81",
        "impact": 14.29,
        "object": "Gold",
        "objectType": "string",
        "relationship": "holds",
        "salience": 100,
        "subject": "Ben"
      },
      {
        "certainty": 100,
        "factID": "WA:KF:c2a63a881f856798e2df8999d7b7956bc28dd50e8e99d6728ca46730955263c1",
        "impact": 14.29,
        "object": "repair",
        "objectType": "string",
        "relationship": "provides",
        "salience": 100,
        "subject": "Gold"
      },
      {
        "certainty": 100,
        "factID": "WA:AF:82b2bc07382e0372685aa06e30b1c9db95ccc30051cfc2ea3de4c2e7fc69d0c6",
        "factKey": "04b02c60-73c1-436c-b0d3-1ee44df7c14b",
        "impact": 14.29,
        "object": "water damage",
        "objectType": "string",
        "relationship": "suffered",
        "salience": 100,
        "subject": "Ben"
      },
      {
        "certainty": 100,
        "factID": "WA:KF:cb08149770bded892f06d37433c305f4f4667837323167d21580b24de3a9c5dd",
        "impact": 14.29,
        "object": "water damage",
        "objectType": "string",
        "relationship": "appropriate for",
        "salience": 100,
        "subject": "repair"
      },
      {
        "certainty": 100,
        "factID": "WA:KF:ec6e5652be4a48515d68c795b0497e87d6beeb83a384c4ae11ca562c6ba0e499",
        "impact": 14.29,
        "object": "mobile phone",
        "objectType": "string",
        "relationship": "insures",
        "salience": 100,
        "subject": "Gold"
      },
      {
        "certainty": 100,
        "factID": "WA:AF:c6a366105ea7691fffae2e75fe27293bd66b4155d352213cee51368272af07b6",
        "factKey": "22667649-4df6-4731-9498-e4eb9c25d22c",
        "impact": 14.29,
        "object": "mobile phone",
        "objectType": "string",
        "relationship": "happened to",
        "salience": 100,
        "subject": "water damage"
      },
      {
        "certainty": 100,
        "factID": "WA:KF:7467c2c1c00149ac477f0246173ef9cb19d08243624b52ddf8a7e05791cd5550",
        "impact": 14.29,
        "object": "water damage",
        "objectType": "string",
        "relationship": "covers",
        "salience": 100,
        "subject": "Gold"
      },
      {
        "expression": {
          "functions": {
            "countRelationshipInstances( 'Ben', 'has previously claimed', *)": {
              "facts": [
                {
                  "certainty": 100,
                  "factID": "WA:AF:6ee11124ef7abd40707e1813a4d0b7851d86f1c36e42eaf3e559f02f441668e5",
                  "factKey": "5a337648-3fa1-46ec-b67e-7f0aa5662863",
                  "object": "laptop",
                  "objectType": "string",
                  "relationship": "has previously claimed",
                  "subject": "Ben"
                },
                {
                  "certainty": 100,
                  "factID": "WA:AF:6ee11124ef7abd40707e1813a4d0b7851d86f1c36e42eaf3e559f02f441668e5",
                  "factKey": "5a337648-3fa1-46ec-b67e-7f0aa5662863",
                  "object": "headphones",
                  "objectType": "string",
                  "relationship": "has previously claimed",
                  "subject": "Ben"
                },
                {
                  "certainty": 100,
                  "factID": "WA:AF:6ee11124ef7abd40707e1813a4d0b7851d86f1c36e42eaf3e559f02f441668e5",
                  "factKey": "5a337648-3fa1-46ec-b67e-7f0aa5662863",
                  "object": "bicycle",
                  "objectType": "string",
                  "relationship": "has previously claimed",
                  "subject": "Ben"
                }
              ],
              "result": {
                "type": "number",
                "value": 3
              }
            }
          },
          "text": "countRelationshipInstances( 'Ben', 'has previously claimed', *)",
          "value": "%RELS"
        },
        "impact": 14.29,
        "salience": 100,
        "wasMet": true
      },
      {
        "expression": {
          "text": "%RELS is less than 10",
          "value": "%O"
        },
        "impact": 14.29,
        "salience": 100,
        "wasMet": true
      }
    ],
    "ruleMaxCertainty": 100
  }
}

Interaction Log - Retrieves interaction events

get

/analysis/interactions/{sessionID}

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

Path parameters

sessionIDstringRequired

The session id to access the interaction logs

Query parameters

formatstringOptional

Format of the retrieved data. CSV or JSON

Responses

200

Interaction log detail

application/json

get

/analysis/interactions/{sessionID}

GET /analysis/interactions/{sessionID} HTTP/1.1
Host: api.rainbird.ai
Accept: */*

200

Interaction log detail

[
  {
    "values": {
      "start": {
        "useDraft": false,
        "kmVersionID": "77135768-7634-49f0-9fbf-ed915ce08a66",
        "sessionID": "c1bf18d7-d1f0-44bc-a639-8cd4ded56dce"
      }
    },
    "event": "start",
    "created": "2025-07-10T10:06:27.780Z"
  },
  {
    "values": {
      "facts": [
        {
          "subject": "Ben",
          "object": "Gold",
          "relationship": "holds",
          "certainty": 100
        }
      ]
    },
    "event": "inject",
    "created": "2025-07-10T10:06:37.987Z"
  },
  {
    "values": {
      "query": {
        "subject": "Ben",
        "relationship": "can claim"
      }
    },
    "event": "query",
    "created": "2025-07-10T10:06:44.532Z"
  },
  {
    "values": {
      "questions": [
        {
          "prompt": "What type of loss has Ben suffered?",
          "relationship": "suffered",
          "subject": "Ben"
        }
      ]
    },
    "event": "question",
    "created": "2025-07-10T10:06:44.713Z"
  },
  {
    "values": {
      "answers": [
        {
          "subject": "Ben",
          "object": "water damage",
          "relationship": "suffered",
          "certainty": 100
        }
      ]
    },
    "event": "answer",
    "created": "2025-07-10T10:07:19.252Z"
  },
  {
    "values": {
      "questions": [
        {
          "prompt": "What item of equipment suffered water damage?",
          "relationship": "happened to",
          "subject": "water damage"
        }
      ]
    },
    "event": "question",
    "created": "2025-07-10T10:07:19.523Z"
  },
  {
    "values": {
      "answers": [
        {
          "subject": "water damage",
          "object": "mobile phone",
          "relationship": "happened to",
          "certainty": 100
        }
      ]
    },
    "event": "answer",
    "created": "2025-07-10T10:07:34.098Z"
  },
  {
    "values": {
      "results": [
        {
          "subject": "Ben",
          "object": "repair",
          "relationship": "can claim",
          "certainty": 100
        },
        {
          "subject": "Ben",
          "object": "new replacement",
          "relationship": "can claim",
          "certainty": 97
        }
      ]
    },
    "event": "result",
    "created": "2025-07-10T10:07:34.276Z"
  }
]

Session - Returns session information

get

/analysis/session/{sessionID}

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

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

sessionIDstringRequired

The sessionID of the session

Query parameters

filterstring · enumOptional

The type of information requested - version or facts

Default: versionPossible values:

relationshipsstring[]Optional

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

Responses

200

Session detail

application/json

Responseone of

get

/analysis/session/{sessionID}

GET /analysis/session/{sessionID} HTTP/1.1
Host: api.rainbird.ai
X-API-Key: YOUR_API_KEY
Accept: */*

200

Session detail

{
  "km": {
    "id": "77135768-7634-49f0-9fbf-ed915ce08a66",
    "name": "Loss Assessment",
    "versionID": "77135768-7634-49f0-9fbf-ed915ce08a66",
    "versionCreated": "2025-07-09T14:27:22Z",
    "versionStatus": "Draft"
  }
}

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

post

/nl/explain

Get a natural language explanation of the chain of reasoning for any given fact.

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

languagestringRequired

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

sessionIDstringRequired

The session ID needed to access that specific session

factIDstringRequired

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

Responses

200

Response to the language

application/json

post

/nl/explain

POST /nl/explain HTTP/1.1
Host: api.rainbird.ai
X-API-Key: YOUR_API_KEY
Version: v1
Content-Type: application/json
Accept: */*
Content-Length: 150

{
  "language": "en",
  "sessionID": "bdef015c-0ab4-417c-982f-b8d9ff48efc1",
  "factID": "WA:RF:e1d3a2380a814cea00d5a1adf69b2cdafba0e0228192cd8014400925bb4422ea"
}

200

Response to the language

{
  "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": {
    "querySubmittedAt": "2025-07-10T11:16:12.597111859Z",
    "languageEngineResponseTime": 5538,
    "llmTokens": {
      "completionTokens": 174,
      "promptTokens": 726,
      "totalTokens": 900
    },
    "apiVersion": "",
    "endpoint": "explain",
    "sessionID": "bdef015c-0ab4-417c-982f-b8d9ff48efc1"
  }
}

Last updated 2 days ago