Natural Language (beta)

The Natural Language APIs are currently in beta. They are unsupported and are subject to change. They rely on an external service provided by OpenAI. The knowledge map and any data you provide will be processed by them. By using this API you will be bound by OpenAI’s terms and conditions. To protect your data we recommend the following:

  1. Do not share personal data about yourself or others

  2. Do not disclose sensitive business data

  3. Use hypothetical scenarios or anonymised data

  4. Do not use with knowledge maps you would deem to contain confidential information As a beta feature, response times and consistency might vary.

Interact

post

Given a body of text, the endpoint will return a question, result or an error.

question

If a question response 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 question response 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 result response is received, this contains the answer to the user's original question and can be presented as required. Once a result response 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
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
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: 40

{
  "sessionID": "text",
  "userPrompt": "text"
}
200

Response to the user prompt

{
  "responseType": "question",
  "query": {
    "subject": "text",
    "relationship": "text",
    "object": "text"
  },
  "questions": {
    "subject": "text",
    "object": "text",
    "objectType": "text",
    "objectMetadata": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "dataType": "text",
    "relationship": "text",
    "type": "text",
    "plural": true,
    "allowCF": true,
    "allowUnknown": true,
    "canAdd": true,
    "prompt": "text",
    "knownAnswers": [],
    "concepts": [
      {
        "conceptType": "text",
        "name": "text",
        "type": "text",
        "value": "text",
        "invalidResponse": true
      }
    ]
  },
  "results": [
    {
      "Certainty": 1,
      "FactID": "text",
      "Object": "text",
      "ObjectMetadata": {},
      "ObjectValue": "text",
      "Relationship": "text",
      "Subject": "text",
      "SubjectMetadata": {},
      "SubjectValue": "text"
    }
  ],
  "error": {
    "code": 1,
    "message": "text",
    "suggestedChatResponse": "text",
    "statusCode": "text"
  },
  "metadata": {
    "querySubmittedAt": "2025-07-07T16:26:56.706Z",
    "languageEngineResponseTime": 1,
    "llmTokens": {
      "completionTokens": 1,
      "promptTokens": 1,
      "totalTokens": 1
    },
    "apiVersion": "text",
    "endpoint": "text"
  },
  "facts": {
    "injected": [
      {
        "subject": "text",
        "relationship": "text",
        "object": "text",
        "certainty": 1
      }
    ],
    "invalid": [
      {
        "subject": "text",
        "relationship": "text",
        "object": "text",
        "certainty": 1
      }
    ],
    "unmatched": [
      "text"
    ]
  }
}

Explain

post

The 'explain' endpoint processes a body of text, generating a natural language exposition of the evidence based on the user-provided session and fact.

Authorizations
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
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: 54

{
  "language": "text",
  "sessionID": "text",
  "factID": "text"
}
200

Response to the language

{
  "explanation": "text",
  "error": {
    "code": 1,
    "message": "text",
    "suggestedChatResponse": "text",
    "statusCode": "text"
  },
  "metadata": {
    "querySubmittedAt": "2025-07-07T16:26:56.706Z",
    "languageEngineResponseTime": 1,
    "llmTokens": {
      "completionTokens": 1,
      "promptTokens": 1,
      "totalTokens": 1
    },
    "apiVersion": "text",
    "endpoint": "text"
  }
}