# 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

> Start a session with the reasoning engine, specifying the knowledge map and (optionally) the version you require.\<br>\<br> 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.\<br>\<br> 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.

```json
{"openapi":"3.1.0","info":{"title":"Rainbird API Documentation","version":"1.2.0"},"tags":[{"name":"Decisions","description":"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.<br><br> **Note:** query, response and undo endpoints can all return *either* a **questionResponse** (the reasoning engine needs more information) *or* a **resultResponse** (the decision).<br><br> 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."}],"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"}}},"paths":{"/start/{kmID}":{"get":{"summary":"Start - Start a new session","tags":["Decisions"],"description":"Start a session with the reasoning engine, specifying the knowledge map and (optionally) the version you require.<br><br> 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.<br><br> 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.","operationId":"start","parameters":[{"in":"path","name":"kmID","schema":{"type":"string"},"required":true,"description":"The knowledge map ID to start a session against, this is in GUID format and can be obtained by clicking View Knowledge Map ID in the map details menu"},{"in":"query","name":"useDraft","schema":{"type":"boolean"},"required":false,"description":"Flag to use the draft version of the knowledge map, cannot be used simultaneously with 'version' parameter"},{"in":"query","name":"version","schema":{"type":"integer"},"required":false,"description":"Parameter to use a specific version of the map, cannot be used simultaneously with 'useDraft' parameter"}],"responses":{"200":{"description":"Session start information","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID of newly created session"},"kmVersion":{"type":"object","properties":{"id":{"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"}}}}}}}}}}}}}
```

## Inject - Inject facts into a session

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

```json
{"openapi":"3.1.0","info":{"title":"Rainbird API Documentation","version":"1.2.0"},"tags":[{"name":"Decisions","description":"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.<br><br> **Note:** query, response and undo endpoints can all return *either* a **questionResponse** (the reasoning engine needs more information) *or* a **resultResponse** (the decision).<br><br> 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."}],"servers":[{"url":"https://api.rainbird.ai","description":"Rainbird Community Environment"},{"url":"https://enterprise-api.rainbird.ai","description":"Rainbird Enterprise Environment"}],"security":[{}],"paths":{"/{sessionID}/inject":{"post":{"summary":"Inject - Inject facts into a session","tags":["Decisions"],"description":"Inject an array of facts as triples. For large requests we recommend injecting in batches of 250 facts.","operationId":"inject","parameters":[{"in":"path","name":"sessionID","schema":{"type":"string"},"required":true,"description":"The session to inject facts into"}],"requestBody":{"description":"Array of facts to inject","required":true,"content":{"application/json":{"schema":{"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"}},"required":["subject","relationship","object","certainty"]}}}}},"responses":{"200":{"description":"Facts were injected successfully","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"string"}}}}}}}}}},"components":{"schemas":{"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"}]},"Certainty":{"description":"How certain this fact or answer is","type":"number","minimum":1,"maximum":100}}}}
```

## Query - Query a running session

> 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]\(<https://docs.rainbird.ai/rainbird/developer-docs/api-guide/example-api-request-flow#query>).

```json
{"openapi":"3.1.0","info":{"title":"Rainbird API Documentation","version":"1.2.0"},"tags":[{"name":"Decisions","description":"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.<br><br> **Note:** query, response and undo endpoints can all return *either* a **questionResponse** (the reasoning engine needs more information) *or* a **resultResponse** (the decision).<br><br> 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."}],"servers":[{"url":"https://api.rainbird.ai","description":"Rainbird Community Environment"},{"url":"https://enterprise-api.rainbird.ai","description":"Rainbird Enterprise Environment"}],"security":[{}],"paths":{"/{sessionID}/query":{"post":{"summary":"Query - Query a running session","tags":["Decisions"],"description":"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](https://docs.rainbird.ai/rainbird/developer-docs/api-guide/example-api-request-flow#query).","operationId":"query","parameters":[{"in":"path","name":"sessionID","schema":{"type":"string"},"required":true,"description":"The session to query against"}],"requestBody":{"description":"Query for the engine to try to answer","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/Subject"},"relationship":{"$ref":"#/components/schemas/Relationship"},"object":{"$ref":"#/components/schemas/Object"}},"required":["relationship"]}}}},"responses":{"200":{"description":"An answer if one is reached, or a question","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/QuestionResponse"},{"$ref":"#/components/schemas/ResultResponse"}]}}}}}}}},"components":{"schemas":{"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"}]},"QuestionResponse":{"description":"A question the engine wants answered","type":"object","properties":{"question":{"$ref":"#/components/schemas/Question"},"extraQuestions":{"type":"array","additionalProperties":true,"description":"If extra questions exist - this would be an array of question objects"},"sid":{"type":"string","description":"The ID of the session"},"stats":{"type":"object","additionalProperties":true,"description":"This has been deprecated"}},"required":["question","sid"]},"Question":{"type":"object","description":"A question object that needs a response","properties":{"subject":{"type":"string"},"object":{"type":"string"},"objectType":{"type":"string"},"objectMetadata":{"type":"object","additionalProperties":true,"description":"If it exists the object side meta"},"dataType":{"type":"string"},"relationship":{"type":"string"},"type":{"type":"string"},"plural":{"type":"boolean"},"allowCF":{"type":"boolean"},"allowUnknown":{"type":"boolean"},"canAdd":{"$ref":"#/components/schemas/CanAdd"},"prompt":{"$ref":"#/components/schemas/Prompt"},"knownAnswers":{"$ref":"#/components/schemas/KnownAnswers"},"concepts":{"type":"array","items":{"type":"object","properties":{"conceptType":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"invalidResponse":{"type":"boolean"}}}}}},"CanAdd":{"description":"Whether further objects can be added to the query","type":"boolean"},"Prompt":{"description":"User interaction required for further processing","type":"string"},"KnownAnswers":{"description":"An array of objects that have been answered","type":"array"},"ResultResponse":{"description":"The engine is providing results","type":"object","properties":{"result":{"type":"array","description":"An array of results","items":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/Subject"},"relationshipType":{"description":"The name of the relationship the query was for","type":"string"},"object":{"$ref":"#/components/schemas/Object"},"certainty":{"$ref":"#/components/schemas/Certainty"},"factID":{"type":"string","description":"ID used to fetch the evidence tree that lead to this decision"},"relationship":{"$ref":"#/components/schemas/Relationship"},"subjectMetadata":{"type":"object","additionalProperties":true,"description":"If it exists the subject side meta"},"objectMetadata":{"type":"object","additionalProperties":true,"description":"If it exists the object side meta"}}}},"queryProfile":{"type":"array","description":"This has been deprecated"},"sid":{"type":"string","description":"The session ID this result relates to"},"stats":{"type":"object","additionalProperties":true,"description":"This has been deprecated"}},"required":["result","sid"]},"Certainty":{"description":"How certain this fact or answer is","type":"number","minimum":1,"maximum":100}}}}
```

## Response - Respond with an answer to a question

> 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.\<br>\<br> \*\*Note:\*\* properties returned in the question object will determine how you can respond.

```json
{"openapi":"3.1.0","info":{"title":"Rainbird API Documentation","version":"1.2.0"},"tags":[{"name":"Decisions","description":"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.<br><br> **Note:** query, response and undo endpoints can all return *either* a **questionResponse** (the reasoning engine needs more information) *or* a **resultResponse** (the decision).<br><br> 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."}],"servers":[{"url":"https://api.rainbird.ai","description":"Rainbird Community Environment"},{"url":"https://enterprise-api.rainbird.ai","description":"Rainbird Enterprise Environment"}],"security":[{}],"paths":{"/{sessionID}/response":{"post":{"summary":"Response - Respond with an answer to a question","tags":["Decisions"],"description":"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.<br><br> **Note:** properties returned in the question object will determine how you can respond.","operationId":"response","parameters":[{"in":"path","name":"sessionID","schema":{"type":"string"},"required":true,"description":"The session to send responses to"}],"requestBody":{"description":"Items to send as a response","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"answers":{"type":"array","items":{"type":"object","required":["subject","relationship","object"],"properties":{"subject":{"$ref":"#/components/schemas/Subject"},"relationship":{"$ref":"#/components/schemas/Relationship"},"object":{"$ref":"#/components/schemas/Object"},"certainty":{"$ref":"#/components/schemas/Certainty"},"answer":{"description":"Required to answer a first form question","type":"string","enum":["yes","no"]}}}}}}}}},"responses":{"200":{"description":"An answer if one is reached, or a question","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/QuestionResponse"},{"$ref":"#/components/schemas/ResultResponse"}]}}}}}}}},"components":{"schemas":{"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"}]},"Certainty":{"description":"How certain this fact or answer is","type":"number","minimum":1,"maximum":100},"QuestionResponse":{"description":"A question the engine wants answered","type":"object","properties":{"question":{"$ref":"#/components/schemas/Question"},"extraQuestions":{"type":"array","additionalProperties":true,"description":"If extra questions exist - this would be an array of question objects"},"sid":{"type":"string","description":"The ID of the session"},"stats":{"type":"object","additionalProperties":true,"description":"This has been deprecated"}},"required":["question","sid"]},"Question":{"type":"object","description":"A question object that needs a response","properties":{"subject":{"type":"string"},"object":{"type":"string"},"objectType":{"type":"string"},"objectMetadata":{"type":"object","additionalProperties":true,"description":"If it exists the object side meta"},"dataType":{"type":"string"},"relationship":{"type":"string"},"type":{"type":"string"},"plural":{"type":"boolean"},"allowCF":{"type":"boolean"},"allowUnknown":{"type":"boolean"},"canAdd":{"$ref":"#/components/schemas/CanAdd"},"prompt":{"$ref":"#/components/schemas/Prompt"},"knownAnswers":{"$ref":"#/components/schemas/KnownAnswers"},"concepts":{"type":"array","items":{"type":"object","properties":{"conceptType":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"invalidResponse":{"type":"boolean"}}}}}},"CanAdd":{"description":"Whether further objects can be added to the query","type":"boolean"},"Prompt":{"description":"User interaction required for further processing","type":"string"},"KnownAnswers":{"description":"An array of objects that have been answered","type":"array"},"ResultResponse":{"description":"The engine is providing results","type":"object","properties":{"result":{"type":"array","description":"An array of results","items":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/Subject"},"relationshipType":{"description":"The name of the relationship the query was for","type":"string"},"object":{"$ref":"#/components/schemas/Object"},"certainty":{"$ref":"#/components/schemas/Certainty"},"factID":{"type":"string","description":"ID used to fetch the evidence tree that lead to this decision"},"relationship":{"$ref":"#/components/schemas/Relationship"},"subjectMetadata":{"type":"object","additionalProperties":true,"description":"If it exists the subject side meta"},"objectMetadata":{"type":"object","additionalProperties":true,"description":"If it exists the object side meta"}}}},"queryProfile":{"type":"array","description":"This has been deprecated"},"sid":{"type":"string","description":"The session ID this result relates to"},"stats":{"type":"object","additionalProperties":true,"description":"This has been deprecated"}},"required":["result","sid"]}}}}
```

## Undo - Undoes the previous answer

> 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.\<br>\<br> \*\*Note:\*\* when there are no further answers to undo, the same question will be returned.

```json
{"openapi":"3.1.0","info":{"title":"Rainbird API Documentation","version":"1.2.0"},"tags":[{"name":"Decisions","description":"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.<br><br> **Note:** query, response and undo endpoints can all return *either* a **questionResponse** (the reasoning engine needs more information) *or* a **resultResponse** (the decision).<br><br> 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."}],"servers":[{"url":"https://api.rainbird.ai","description":"Rainbird Community Environment"},{"url":"https://enterprise-api.rainbird.ai","description":"Rainbird Enterprise Environment"}],"security":[{}],"paths":{"/{sessionID}/undo":{"post":{"summary":"Undo - Undoes the previous answer","description":"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.<br><br> **Note:** when there are no further answers to undo, the same question will be returned.","tags":["Decisions"],"operationId":"undo","parameters":[{"in":"path","name":"sessionID","schema":{"type":"string"},"required":true,"description":"The session to step back with an undo"}],"requestBody":{"description":"An empty object","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Session stepped back to a previous question or result","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/QuestionResponse"},{"$ref":"#/components/schemas/ResultResponse"}]}}}}}}}},"components":{"schemas":{"QuestionResponse":{"description":"A question the engine wants answered","type":"object","properties":{"question":{"$ref":"#/components/schemas/Question"},"extraQuestions":{"type":"array","additionalProperties":true,"description":"If extra questions exist - this would be an array of question objects"},"sid":{"type":"string","description":"The ID of the session"},"stats":{"type":"object","additionalProperties":true,"description":"This has been deprecated"}},"required":["question","sid"]},"Question":{"type":"object","description":"A question object that needs a response","properties":{"subject":{"type":"string"},"object":{"type":"string"},"objectType":{"type":"string"},"objectMetadata":{"type":"object","additionalProperties":true,"description":"If it exists the object side meta"},"dataType":{"type":"string"},"relationship":{"type":"string"},"type":{"type":"string"},"plural":{"type":"boolean"},"allowCF":{"type":"boolean"},"allowUnknown":{"type":"boolean"},"canAdd":{"$ref":"#/components/schemas/CanAdd"},"prompt":{"$ref":"#/components/schemas/Prompt"},"knownAnswers":{"$ref":"#/components/schemas/KnownAnswers"},"concepts":{"type":"array","items":{"type":"object","properties":{"conceptType":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"invalidResponse":{"type":"boolean"}}}}}},"CanAdd":{"description":"Whether further objects can be added to the query","type":"boolean"},"Prompt":{"description":"User interaction required for further processing","type":"string"},"KnownAnswers":{"description":"An array of objects that have been answered","type":"array"},"ResultResponse":{"description":"The engine is providing results","type":"object","properties":{"result":{"type":"array","description":"An array of results","items":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/Subject"},"relationshipType":{"description":"The name of the relationship the query was for","type":"string"},"object":{"$ref":"#/components/schemas/Object"},"certainty":{"$ref":"#/components/schemas/Certainty"},"factID":{"type":"string","description":"ID used to fetch the evidence tree that lead to this decision"},"relationship":{"$ref":"#/components/schemas/Relationship"},"subjectMetadata":{"type":"object","additionalProperties":true,"description":"If it exists the subject side meta"},"objectMetadata":{"type":"object","additionalProperties":true,"description":"If it exists the object side meta"}}}},"queryProfile":{"type":"array","description":"This has been deprecated"},"sid":{"type":"string","description":"The session ID this result relates to"},"stats":{"type":"object","additionalProperties":true,"description":"This has been deprecated"}},"required":["result","sid"]},"Subject":{"description":"The subject side concept instance or value","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},"Relationship":{"description":"The relationship between subject and object","type":"string"}}}}
```

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

> 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.<br>

```json
{"openapi":"3.1.0","info":{"title":"Rainbird API Documentation","version":"1.2.0"},"tags":[{"name":"Decisions","description":"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.<br><br> **Note:** query, response and undo endpoints can all return *either* a **questionResponse** (the reasoning engine needs more information) *or* a **resultResponse** (the decision).<br><br> 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."}],"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":{"Question":{"type":"object","description":"A question object that needs a response","properties":{"subject":{"type":"string"},"object":{"type":"string"},"objectType":{"type":"string"},"objectMetadata":{"type":"object","additionalProperties":true,"description":"If it exists the object side meta"},"dataType":{"type":"string"},"relationship":{"type":"string"},"type":{"type":"string"},"plural":{"type":"boolean"},"allowCF":{"type":"boolean"},"allowUnknown":{"type":"boolean"},"canAdd":{"$ref":"#/components/schemas/CanAdd"},"prompt":{"$ref":"#/components/schemas/Prompt"},"knownAnswers":{"$ref":"#/components/schemas/KnownAnswers"},"concepts":{"type":"array","items":{"type":"object","properties":{"conceptType":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"invalidResponse":{"type":"boolean"}}}}}},"CanAdd":{"description":"Whether further objects can be added to the query","type":"boolean"},"Prompt":{"description":"User interaction required for further processing","type":"string"},"KnownAnswers":{"description":"An array of objects that have been answered","type":"array"},"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"}}},"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"}]},"Certainty":{"description":"How certain this fact or answer is","type":"number","minimum":1,"maximum":100}}},"paths":{"/nl/interact":{"post":{"summary":"Interact (BETA) - natural language injection, queries and question responses","description":"Given a body of text, the endpoint will return a question, result or an error.\n\n### question\n\nIf 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.\n\n### result\n\nIf 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.\n\n### error\n\nIf 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.\n","tags":["Decisions"],"operationId":"interact","requestBody":{"description":"User prompt for natural language processing","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionID":{"type":"string","description":"The session ID needed to access that specific session"},"userPrompt":{"type":"string","description":"The user's prompt for natural language processing"}},"required":["sessionID","userPrompt"]}}}},"parameters":[{"$ref":"#/components/parameters/NLVersion"}],"responses":{"200":{"description":"Response to the user prompt","content":{"application/json":{"schema":{"type":"object","required":["responseType"],"properties":{"responseType":{"type":"string","enum":["question","result","error"],"description":"Indicates how the response should be handled."},"query":{"type":"object","properties":{"subject":{"type":"string","description":"The subject extracted from the user prompt"},"relationship":{"type":"string","description":"The relationship extracted from the user prompt"},"object":{"type":"string","description":"The object extracted from the user prompt (if available)"}},"required":["subject","relationship"]},"questions":{"type":"array","items":{"$ref":"#/components/schemas/Question"}},"results":{"type":"array","items":{"type":"object","properties":{"Certainty":{"type":"integer","description":"Certainty level of the answer"},"FactID":{"type":"string","description":"ID of the fact"},"Object":{"type":"string","description":"The object in the answer"},"ObjectMetadata":{"type":"object","description":"Metadata related to the object"},"ObjectValue":{"type":"string","description":"Value of the object"},"Relationship":{"type":"string","description":"The relationship in the answer"},"Subject":{"type":"string","description":"The subject in the answer"},"SubjectMetadata":{"type":"object","description":"Metadata related to the subject"},"SubjectValue":{"type":"string","description":"Value of the subject"}}}},"error":{"$ref":"#/components/schemas/NLError"},"metadata":{"$ref":"#/components/schemas/NLMetadata"},"facts":{"type":"object","properties":{"injected":{"type":"array","description":"facts identified and injected in the reasoning engine session","items":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/Subject"},"relationship":{"$ref":"#/components/schemas/Relationship"},"object":{"$ref":"#/components/schemas/Object"},"certainty":{"$ref":"#/components/schemas/Certainty"}}}},"invalid":{"type":"array","description":"facts identified but invalid for the current knowledge map, hence not injected","items":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/Subject"},"relationship":{"$ref":"#/components/schemas/Relationship"},"object":{"$ref":"#/components/schemas/Object"},"certainty":{"$ref":"#/components/schemas/Certainty"}}}},"unmatched":{"type":"array","description":"unused pieces of information from the user prompt","items":{"type":"string"}}}}}}}}}}}}}}
```


---

# 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/decisions.md?ask=<question>
```

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.