---
title: "Interact (BETA) - natural language injection, queries and question responses"
method: POST
path: "/nl/interact"
tags: ["Decisions"]
---

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

## Headers

- `Version` string, required

## Request body

- object
  - `sessionID` string, required — The session ID needed to access that specific session
  - `userPrompt` string, required — The user's prompt for natural language processing

## Response `200`

Response to the user prompt

- object
  - `responseType` 'question' | 'result' | 'error', required — Indicates how the response should be handled.
  - `query` object
    - `subject` string, required — The subject extracted from the user prompt
    - `relationship` string, required — The relationship extracted from the user prompt
    - `object` string — The object extracted from the user prompt (if available)
  - `questions` Question[]
    - `subject` string
    - `object` string
    - `objectType` string
    - `objectMetadata` object — If it exists the object side meta
    - `dataType` string
    - `relationship` string
    - `type` string
    - `plural` boolean
    - `allowCF` boolean
    - `allowUnknown` boolean
    - `canAdd` boolean — Whether further objects can be added to the query
    - `prompt` string — User interaction required for further processing
    - `knownAnswers` unknown[] — An array of objects that have been answered
      - unknown
    - `concepts` object[]
      - `conceptType` string
      - `name` string
      - `type` string
      - `value` string
      - `invalidResponse` boolean
  - `results` object[]
    - `Certainty` integer — Certainty level of the answer
    - `FactID` string — ID of the fact
    - `Object` string — The object in the answer
    - `ObjectMetadata` object — Metadata related to the object
    - `ObjectValue` string — Value of the object
    - `Relationship` string — The relationship in the answer
    - `Subject` string — The subject in the answer
    - `SubjectMetadata` object — Metadata related to the subject
    - `SubjectValue` string — Value of the subject
  - `error` NLError — Error for the natural language endpoints
    - `code` integer — An internal error code.
    - `message` string — A description of the error.
    - `suggestedChatResponse` string — 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` string — The HTTP status code of the response.
  - `metadata` NLMetadata — Metadata for the natural language endpoints
    - `querySubmittedAt` string, date-time — Timestamp when the query was submitted
    - `languageEngineResponseTime` integer — Response time of the language engine in milliseconds
    - `llmTokens` object — Token information from the LLM response
      - `completionTokens` integer — Number of completion tokens
      - `promptTokens` integer — Number of prompt tokens
      - `totalTokens` integer — Total number of tokens
    - `apiVersion` string — Version of the API
    - `endpoint` string — Name of the endpoint
    - `sessionID` string — Session ID of the session
  - `facts` object
    - `injected` object[] — facts identified and injected in the reasoning engine session
      - `subject` string — The subject side concept instance or value
      - `relationship` string — The relationship between subject and object
      - `object` union — The object side concept instance or value
        - string
        - number
        - boolean
      - `certainty` number — How certain this fact or answer is
    - `invalid` object[] — facts identified but invalid for the current knowledge map, hence not injected
      - `subject` string — The subject side concept instance or value
      - `relationship` string — The relationship between subject and object
      - `object` union — The object side concept instance or value
        - string
        - number
        - boolean
      - `certainty` number — How certain this fact or answer is
    - `unmatched` string[] — unused pieces of information from the user prompt

---

[API](https://skmtc.net/rainbird/apis/rainbird-api-documentation.md) · [All operations](https://skmtc.net/rainbird/apis/rainbird-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/rainbird/rainbird-api-documentation/revisions/0b8d2bc38f5d/schema)