Rainbird Technologies Decisions API

openapi: 3.2.0
info:
  title: Rainbird API Documentation Decisions API
  version: 1.2.0
  description: 'Welcome to the Rainbird API documentation. It contains details of the API calls required to query a Knowledge Map and view evidence for the decisions returned. Knowledge Maps must first be created via the Rainbird Studio. More information on this can be found [here](https://docs.rainbird.ai/rainbird/knowledge-modelling/overview).


    # Authentication


    <!-- ReDoc-Inject: <security-definitions> -->'
servers:
- url: https://api.rainbird.ai
  description: Rainbird Community Environment
- url: https://enterprise-api.rainbird.ai
  description: Rainbird Enterprise Environment
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.
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
      - 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
      security:
      - apiKey: []
      responses:
        '200':
          description: Session start information
          content:
            application/json:
              schema:
                type: object
                example:
                  id: c1bf18d7-d1f0-44bc-a639-8cd4ded56dce
                  kmVersion:
                    id: 77135768-7634-49f0-9fbf-ed915ce08a66
                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

                          '
  /{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
      security:
      - {}
      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:
              example:
              - subject: Ben
                relationship: holds
                object: Gold
                certainty: 100
              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
                example:
                  result: OK
                properties:
                  result:
                    type: string
  /{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-guides/api-guide/example-api-request-flow#query).
      operationId: query
      security:
      - {}
      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:
              example:
                subject: Ben
                relationship: can claim
              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'
  /{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
      security:
      - {}
      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:
              example:
                answers:
                - subject: Ben
                  relationship: suffered
                  object: water damage
                  certainty: 100
              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'
  /{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
      security:
      - {}
      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:
              example: {}
              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'
  /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.


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

        '
      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
            examples:
              query:
                value:
                  sessionID: bdef015c-0ab4-417c-982f-b8d9ff48efc1
                  userPrompt: Can Ben claim?
              response:
                value:
                  sessionID: bdef015c-0ab4-417c-982f-b8d9ff48efc1
                  userPrompt: Ben holds a Gold policy and his mobile phone suffered water damage
      security:
      - apiKey: []
      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
              examples:
                question:
                  value:
                    responseType: question
                    facts: {}
                    metadata:
                      querySubmittedAt: '2025-07-10T10:49:13.231973361Z'
                      languageEngineResponseTime: 2173
                      llmTokens:
                        completionTokens: 52
                        promptTokens: 3117
                        totalTokens: 3169
                      apiVersion: ''
                      endpoint: interact
                      sessionID: bdef015c-0ab4-417c-982f-b8d9ff48efc1
                    query:
                      subject: Ben
                      relationship: can claim
                      object: null
                    questions:
                    - allowCF: true
                      canAdd: true
                      concepts:
                      - conceptType: policy
                        name: Gold
                        type: string
                        value: Gold
                      - conceptType: policy
                        name: Silver
                        type: string
                        value: Silver
                      - conceptType: policy
                        name: Bronze
                        type: string
                        value: Bronze
                      dataType: string
                      prompt: Which policy does Ben hold?
                      relationship: holds
                      subject: Ben
                      type: Second Form Object
                    results: null
                result:
                  value:
                    responseType: result
                    facts:
                      injected:
                      - subject: Ben
                        relationship: suffered
                        object: water damage
                        cf: ''
                        certainty: 100
                        metadata:
                          source: user
                      - subject: water damage
                        relationship: happened to
                        object: mobile phone
                        cf: ''
                        certainty: 100
                        metadata:
                          source: user
                      - subject: Ben
                        relationship: holds
                        object: Gold
                        cf: ''
                        certainty: 100
                        metadata: {}
                    metadata:
                      querySubmittedAt: '2025-07-10T10:59:01.816771016Z'
                      languageEngineResponseTime: 4379
                      llmTokens:
                        completionTokens: 170
                        promptTokens: 3229
                        totalTokens: 3399
                      apiVersion: ''
                      endpoint: interact
                      sessionID: bdef015c-0ab4-417c-982f-b8d9ff48efc1
                    query:
                      subject: Ben
                      relationship: can claim
                      object: null
                    results:
                    - subject: Ben
                      object: repair
                      certainty: 100
                      factID: WA:RF:e1d3a2380a814cea00d5a1adf69b2cdafba0e0228192cd8014400925bb4422ea
                      relationship: can claim
                    - subject: Ben
                      object: new replacement
                      certainty: 97
                      factID: WA:RF:91d518b8314f29515304e3a2a98bbad9d35ba0c50171a65c3b6c27a01cb645d5
                      relationship: can claim
components:
  schemas:
    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
    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
    Prompt:
      description: User interaction required for further processing
      type: string
    CanAdd:
      description: Whether further objects can be added to the query
      type: boolean
    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.
    Object:
      description: The object side concept instance or value
      oneOf:
      - type: string
      - type: number
      - type: boolean
    Relationship:
      description: The relationship between subject and object
      type: string
    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
          example: c1bf18d7-d1f0-44bc-a639-8cd4ded56dce
        stats:
          type: object
          additionalProperties: true
          description: This has been deprecated
      required:
      - question
      - sid
      example:
        question:
          subject: Ben
          dataType: string
          relationship: suffered
          type: Second Form Object
          plural: true
          allowCF: true
          allowUnknown: false
          canAdd: true
          prompt: What type of loss has Ben suffered?
          knownAnswers: []
          concepts:
          - conceptType: loss
            name: cosmetic damage
            type: string
            value: cosmetic damage
          - conceptType: loss
            name: water damage
            type: string
            value: water damage
          - conceptType: loss
            name: loss
            type: string
            value: loss
          - conceptType: loss
            name: theft
            type: string
            value: theft
        sid: c1bf18d7-d1f0-44bc-a639-8cd4ded56dce
    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
      example:
        result:
        - subject: Ben
          relationshipType: can claim
          object: repair
          certainty: 100
          factID: WA:RF:82a7b990eb2fe491389f37de10b1cd752cbd692b8c2c0d3fb36b354491f68173
          relationship: can claim
          objectMetadata: {}
        - subject: Ben
          relationshipType: can claim
          object: new replacement
          certainty: 97
          factID: WA:RF:63bc5b884a9256bebd30fa0cd35c3735e8de61f7e34b7859cc9289f1349058ed
          relationship: can claim
          objectMetadata: {}
        queryProfile: []
        sid: c1bf18d7-d1f0-44bc-a639-8cd4ded56dce
    KnownAnswers:
      description: An array of objects that have been answered
      type: array
    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
  parameters:
    NLVersion:
      name: Version
      in: header
      description: Version of the natural language API
      required: true
      schema:
        type: string
        default: v1
  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
    evidenceKey:
      description: To access secured evidence, you should pass your evidence key
      in: header
      name: x-evidence-key
      type: apiKey
    interactionKey:
      description: To access secured interaction logs, you should pass your interaction key
      in: header
      name: x-interaction-key
      type: apiKey