# 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.
```json
{"openapi":"3.1.0","info":{"title":"Rainbird API Documentation","version":"1.2.0"},"tags":[{"name":"Evidence","description":"Access the facts, information and the chain of reasoning that led to a decision\n"}],"servers":[{"url":"https://api.rainbird.ai","description":"Rainbird Community Environment"},{"url":"https://enterprise-api.rainbird.ai","description":"Rainbird Enterprise Environment"}],"security":[{},{"evidenceKey":[]}],"components":{"securitySchemes":{"evidenceKey":{"description":"To access secured evidence, you should pass your evidence key. Evidence is secured by default. The key can be found (or evidence unsecured) by visiting the access controls section of the knowledge map publish page","in":"header","name":"x-evidence-key","type":"apiKey"}},"schemas":{"Object":{"description":"The object side concept instance or value","oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"Certainty":{"description":"How certain this fact or answer is","type":"number","minimum":1,"maximum":100},"Subject":{"description":"The subject side concept instance or value","type":"string"},"Relationship":{"description":"The relationship between subject and object","type":"string"},"Salience":{"description":"The weight of a condition","type":"number","minimum":1,"maximum":100},"Impact":{"description":"The impact this condition has on the result as a percentage","type":"number"},"Alt":{"description":"Alternative Text for the condition displayed in the Evidence Tree","type":"string"},"WasMet":{"description":"Whether the expression returned true or false when not assigned to a variable. Always returns true when assigned to a variable","type":"boolean"}}},"paths":{"/analysis/evidence/{factID}/{sessionID}":{"get":{"summary":"Evidence - Returns the evidence for a given fact","tags":["Evidence"],"description":"View the source of the fact, including how it was derived when inferred from a rule.","operationId":"evidence","parameters":[{"in":"path","name":"factID","schema":{"type":"string"},"required":true,"description":"The factID for which to retrieve evidence"},{"in":"path","name":"sessionID","schema":{"type":"string"},"required":true,"description":"The sessionID where the fact was created"}],"responses":{"200":{"description":"Fact detail","content":{"application/json":{"schema":{"type":"object","properties":{"factID":{"type":"string"},"source":{"type":"string"},"fact":{"type":"object","properties":{"subject":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"},"dataType":{"type":"string"}}},"relationship":{"type":"object","properties":{"type":{"type":"string"}}},"object":{"type":"object","properties":{"type":{"type":"string"},"value":{"$ref":"#/components/schemas/Object"},"dataType":{"type":"string"}}},"certainty":{"$ref":"#/components/schemas/Certainty"}}},"time":{"type":"number"},"rule":{"type":"object","properties":{"bindings":{"type":"object","additionalProperties":true},"conditions":{"type":"array","description":"An array of conditions and/or expressions of the rule","items":{"oneOf":[{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/Subject"},"relationship":{"$ref":"#/components/schemas/Relationship"},"object":{"$ref":"#/components/schemas/Object"},"salience":{"$ref":"#/components/schemas/Salience"},"certainty":{"$ref":"#/components/schemas/Certainty"},"impact":{"$ref":"#/components/schemas/Impact"},"factID":{"type":"string"},"objectType":{"type":"string"},"alt":{"$ref":"#/components/schemas/Alt"},"factKey":{"type":"string"}}},{"type":"object","properties":{"expression":{"type":"object","properties":{"functions":{"type":"object","properties":{"function-that-was-called":{"type":"object","properties":{"facts":{"type":"array","items":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/Subject"},"relationship":{"$ref":"#/components/schemas/Relationship"},"object":{"$ref":"#/components/schemas/Object"},"certainty":{"$ref":"#/components/schemas/Certainty"},"factID":{"type":"string"},"objectType":{"type":"string"},"factKey":{"type":"string"}}}},"result":{"type":"object","properties":{"type":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}}}}}},"text":{"type":"string"},"value":{"type":"string"}}},"impact":{"$ref":"#/components/schemas/Impact"},"salience":{"$ref":"#/components/schemas/Salience"},"wasMet":{"$ref":"#/components/schemas/WasMet"},"alt":{"$ref":"#/components/schemas/Alt"}}}]}},"ruleMaxCertainty":{"$ref":"#/components/schemas/Certainty"}}}}}}}}}}}}}
```
## 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.
```json
{"openapi":"3.1.0","info":{"title":"Rainbird API Documentation","version":"1.2.0"},"tags":[{"name":"Evidence","description":"Access the facts, information and the chain of reasoning that led to a decision\n"}],"servers":[{"url":"https://api.rainbird.ai","description":"Rainbird Community Environment"},{"url":"https://enterprise-api.rainbird.ai","description":"Rainbird Enterprise Environment"}],"security":[{},{"interactionKey":[]}],"components":{"securitySchemes":{"interactionKey":{"description":"To access secured interaction logs, you should pass your interaction key","in":"header","name":"x-interaction-key","type":"apiKey"}},"schemas":{"InteractionEventStart":{"description":"Start event retrieved via the interaction log","type":"object","properties":{"start":{"type":"object","properties":{"useDraft":{"type":"boolean","description":"Whether the current draft of the knowledge map is being used\n"},"kmVersion":{"type":"string","description":"ID of the version being queried, which will be different to the knowledge map ID when querying live versions of a knowledge map\n"},"sessionID":{"type":"string","description":"The sessionID the interaction log is based on"}}}}},"InteractionEventQuestions":{"description":"Questions event retrieved via the interaction log","type":"object","properties":{"questions":{"type":"array","items":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/Subject"},"relationship":{"$ref":"#/components/schemas/Relationship"},"object":{"$ref":"#/components/schemas/Object"},"prompt":{"$ref":"#/components/schemas/Prompt"}}}}}},"Subject":{"description":"The subject side concept instance or value","type":"string"},"Relationship":{"description":"The relationship between subject and object","type":"string"},"Object":{"description":"The object side concept instance or value","oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"Prompt":{"description":"User interaction required for further processing","type":"string"},"InteractionEventQuery":{"description":"Query event retrieved via the interaction log","type":"object","properties":{"query":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/Subject"},"relationship":{"$ref":"#/components/schemas/Relationship"},"object":{"$ref":"#/components/schemas/Object"}}}}},"InteractionEventAnswers":{"description":"Answers event retrieved via the interaction log","type":"object","properties":{"answers":{"type":"array","items":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/Subject"},"relationship":{"$ref":"#/components/schemas/Relationship"},"object":{"$ref":"#/components/schemas/Object"},"certainty":{"$ref":"#/components/schemas/Certainty"}}}}}},"Certainty":{"description":"How certain this fact or answer is","type":"number","minimum":1,"maximum":100},"InteractionEventResults":{"description":"Results event retrieved via the interaction log","type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/Subject"},"relationship":{"$ref":"#/components/schemas/Relationship"},"object":{"$ref":"#/components/schemas/Object"},"certainty":{"$ref":"#/components/schemas/Certainty"}}}}}},"InteractionEventInject":{"description":"Inject event retrieved via the interaction log","type":"object","properties":{"facts":{"type":"array","items":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/Subject"},"relationship":{"$ref":"#/components/schemas/Relationship"},"object":{"$ref":"#/components/schemas/Object"},"certainty":{"$ref":"#/components/schemas/Certainty"}}}}}},"InteractionEventDatasource":{"description":"Datasource event retrieved via the interaction log","type":"object","properties":{"datasources":{"type":"array","items":{"type":"object","properties":{"relationship":{"$ref":"#/components/schemas/Relationship"},"certainty":{"$ref":"#/components/schemas/Certainty"}}}}}}}},"paths":{"/analysis/interactions/{sessionID}":{"get":{"summary":"Interaction Log - Retrieves interaction events","tags":["Evidence"],"description":"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.","operationId":"interactions","parameters":[{"in":"path","name":"sessionID","schema":{"type":"string"},"required":true,"description":"The session id to access the interaction logs"},{"in":"query","name":"format","schema":{"type":"string"},"required":false,"description":"Format of the retrieved data. CSV or JSON"}],"responses":{"200":{"description":"Interaction log detail","content":{"application/json":{"schema":{"properties":{"values":{"oneOf":[{"$ref":"#/components/schemas/InteractionEventStart"},{"$ref":"#/components/schemas/InteractionEventQuestions"},{"$ref":"#/components/schemas/InteractionEventQuery"},{"$ref":"#/components/schemas/InteractionEventAnswers"},{"$ref":"#/components/schemas/InteractionEventResults"},{"$ref":"#/components/schemas/InteractionEventInject"},{"$ref":"#/components/schemas/InteractionEventDatasource"}],"type":"object","description":"The object that contains the specific interaction log\n"},"event":{"type":"string","description":"The interaction event name\n"},"created":{"type":"string","description":"The creation time of the specific interaction\n"}}}}}}}}}}}
```
## 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.
```json
{"openapi":"3.1.0","info":{"title":"Rainbird API Documentation","version":"1.2.0"},"tags":[{"name":"Evidence","description":"Access the facts, information and the chain of reasoning that led to a decision\n"}],"servers":[{"url":"https://api.rainbird.ai","description":"Rainbird Community Environment"},{"url":"https://enterprise-api.rainbird.ai","description":"Rainbird Enterprise Environment"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"description":"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](https://docs.rainbird.ai/rainbird/knowledge-modelling/publishing-your-km/api-management). \n\nOur legacy authentication method of HTTP BasicAuth continues to be supported, but we highly advise transitioning to the new method.\n","in":"header","name":"X-API-Key","type":"apiKey"}},"schemas":{"SessionDetail":{"description":"Information about the session","type":"object","properties":{"km":{"type":"object","description":null,"properties":{"id":{"type":"string","description":"The ID of the knowledge map"},"name":{"type":"string","description":"the name of the knowledge map"},"versionID":{"type":"string","description":"ID of the version being queried, which will be different to the knowledge map ID when querying live versions of a knowledge map\n"},"versionCreated":{"type":"string","format":"date-time","description":"Timestamp when the query was created"},"versionStatus":{"type":"string","description":"The type of version and version number. Either \"Draft\" or \"Version1\", \"Version2\" etc."}}}}},"FactsObject":{"description":"An object containing the facts of the knowledge map. Can be filtered.","type":"object","properties":{"global":{"type":"array","items":{"description":"A fact stored globally in the knowledge map","type":"object","properties":{"$ref":"#/components/schemas/FactProperties"}}},"local":{"type":"array","items":{"description":"A fact created locally in the session","type":"object","properties":{"$ref":"#/components/schemas/FactProperties"}}},"context":{"type":"array","items":{"description":"A fact shared from another session","type":"object","properties":{"$ref":"#/components/schemas/FactProperties"}}}}},"FactProperties":{"id":{"type":"string"},"subject":{"type":"object","properties":{"concept":{"description":"Concept name","type":"string"},"value":{"$ref":"#/components/schemas/Subject"},"dataType":{"$ref":"#/components/schemas/DataType"}}},"relationship":{"$ref":"#/components/schemas/Relationship"},"object":{"type":"object","properties":{"concept":{"description":"Concept name","type":"string"},"value":{"$ref":"#/components/schemas/Object"},"dataType":{"$ref":"#/components/schemas/DataType"}}},"certainty":{"$ref":"#/components/schemas/Certainty"},"source":{"$ref":"#/components/schemas/FactSource"}},"Subject":{"description":"The subject side concept instance or value","type":"string"},"DataType":{"description":"The type of the data held in the object value","type":"string","enum":["string","number","truth","date"]},"Relationship":{"description":"The relationship between subject and object","type":"string"},"Object":{"description":"The object side concept instance or value","oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"Certainty":{"description":"How certain this fact or answer is","type":"number","minimum":1,"maximum":100},"FactSource":{"description":"The source of the fact","type":"string","enum":["knowledgemap","rule","answer","injection","datasource","synthesis"]}}},"paths":{"/analysis/session/{sessionID}":{"get":{"summary":"Session - Returns session information","tags":["Evidence"],"description":"Access session information, such as all of the facts available within a session, or version information for the knowledge map used in a session.","operationId":"session","parameters":[{"in":"path","name":"sessionID","schema":{"type":"string"},"required":true,"description":"The sessionID of the session"},{"in":"query","name":"filter","schema":{"type":"string","enum":["version","facts"],"default":"version"},"required":false,"description":"The type of information requested - `version` or `facts`"},{"in":"query","name":"relationships","schema":{"type":"array","items":{"type":"string"}},"explode":false,"description":"A comma-separated list of relationships to filter the session data by.","required":false}],"responses":{"200":{"description":"Session detail","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SessionDetail"},{"$ref":"#/components/schemas/FactsObject"}]}}}}}}}}}
```
## 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.
```json
{"openapi":"3.1.0","info":{"title":"Rainbird API Documentation","version":"1.2.0"},"tags":[{"name":"Evidence","description":"Access the facts, information and the chain of reasoning that led to a decision\n"}],"servers":[{"url":"https://api.rainbird.ai","description":"Rainbird Community Environment"},{"url":"https://enterprise-api.rainbird.ai","description":"Rainbird Enterprise Environment"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"description":"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](https://docs.rainbird.ai/rainbird/knowledge-modelling/publishing-your-km/api-management). \n\nOur legacy authentication method of HTTP BasicAuth continues to be supported, but we highly advise transitioning to the new method.\n","in":"header","name":"X-API-Key","type":"apiKey"}},"parameters":{"NLVersion":{"name":"Version","in":"header","description":"Version of the natural language API","required":true,"schema":{"type":"string","default":"v1"}}},"schemas":{"NLError":{"description":"Error for the natural language endpoints","type":"object","properties":{"code":{"type":"integer","description":"An internal error code."},"message":{"type":"string","description":"A description of the error."},"suggestedChatResponse":{"type":"string","description":"A recommended message for chat-based clients to show the user. This message is designed to be user-friendly and assumes no knowledge of Rainbird."},"statusCode":{"type":"string","description":"The HTTP status code of the response."}}},"NLMetadata":{"description":"Metadata for the natural language endpoints","type":"object","properties":{"querySubmittedAt":{"type":"string","format":"date-time","description":"Timestamp when the query was submitted"},"languageEngineResponseTime":{"type":"integer","description":"Response time of the language engine in milliseconds"},"llmTokens":{"type":"object","description":"Token information from the LLM response","properties":{"completionTokens":{"type":"integer","description":"Number of completion tokens"},"promptTokens":{"type":"integer","description":"Number of prompt tokens"},"totalTokens":{"type":"integer","description":"Total number of tokens"}}},"apiVersion":{"type":"string","description":"Version of the API"},"endpoint":{"type":"string","description":"Name of the endpoint"},"sessionID":{"type":"string","description":"Session ID of the session"}}}}},"paths":{"/nl/explain":{"post":{"summary":"Explain (BETA) - Returns a natural language explanation of the evidence tree","description":"Get a natural language explanation of the chain of reasoning for any given fact.\n","tags":["Evidence"],"operationId":"explain","requestBody":{"description":"Language, factID, and sessionID for natural language processing","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string","description":"The users preferred language setting i.e. \"en\", \"za\""},"sessionID":{"type":"string","description":"The session ID needed to access that specific session"},"factID":{"type":"string","description":"The ID of a fact specific to that session to retrieve data from"}},"required":["language","sessionID","factID"]}}}},"parameters":[{"$ref":"#/components/parameters/NLVersion"}],"responses":{"200":{"description":"Response to the language","content":{"application/json":{"schema":{"type":"object","properties":{"explanation":{"type":"string","description":"The natural language representation of the fact evidence being queried"},"error":{"$ref":"#/components/schemas/NLError"},"metadata":{"$ref":"#/components/schemas/NLMetadata"}}}}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.rainbird.ai/rainbird/developer-docs/api-reference/evidence.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.