You are viewing the documentation for Blueriq 17. Documentation for other versions is available in our documentation directory.

Introduction

The Blueriq Runtime provides a Conversation REST API for the following operations

  • Search for decision trees
  • Executing a decision tree


When the runtime is installed, API documentation is also available as Swagger feed: 

http://<server>:<port>/runtime/server/api/v2/dtree/docs

Tip: use an (online) Swagger UI tool to visualize this API documentation.

Searching decision trees

There are 2 endpoints available to search for decision trees: 

  1. http://localhost/runtime/server/api/v2/dtree/search/{shortcut}
  2. http://localhost/runtime/server/api/v2/dtree/search/{project}/{version}

The first endpoint needs a shortcut. Please refer to Create a shortcut in the Runtime on how to configure a shortcut. It is also possible to secure the shortcut and when doing so, please refer to Runtime Authentication for how to configure authentication on your Runtime.  

The second endpoint is only available when blueriq.production.shortcuts-only is set to false in the application.properties file.

Example search

In the example below, in the Search request body the symptom text contains keywords that are modelled for the Decision Tree, like the word "coffee". 

Example Search request
POST http://localhost/runtime/server/api/v2/dtree/search/coffee HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic YWRtaW46d2VsY29tZQ==
Accept-Language: en-GB # header used in Blueriq to show the texts. If not set, the default language in the model is used
{
	"symptomText": "What coffee should I drink?", # Search query
	"maximumResults": 5, # Maximum number of results which will be returned. Default: 5
	"threshold": 15.0 # The threshold match percentage. Only match results greater or equal to the threshold are shown. Default: 0
}

The response will contain the list of all decision trees that are exposed in the flow started by the shortcut (or by project / version). Each decision tree has 3 properties: 

  • name - the name of the DecisionTree as defined in Studio
  • description - the display name of the DecisionTree as defined in Studio
  • score - indicates matching score between the symptomText from the request with the decision tree's symptoms. 

Example :

The Decision Tree "WhatCoffeeShouldIDrink" has the following symptoms: Coffee, Drink, Help, Sleepy, Stressed.  The decision tree returns a score of 20, as one of the 5 words in the symptom text matches with one symptom of the decision tree. 

The Decision Tree "DecisionTreeTest" has the following symptoms: keyword1, keyword2, keyword3. The decision tree returns a score of 0, as none of the words in the symptom text matches with the symptoms of the decision tree, 

Example Search response
{
    "trees": [
        {
            "name": "WhatCoffeeShouldIDrink",
            "description": "What coffee should I drink?",
            "score": 20
        },
        {
            "name": "DecisionTreeTest",
            "description": "This is a test",
            "score": 0
        }
    ]
}

Error Messages

When the search fails, the endpoints respond with a status code and a JSON error object detailing the encountered error. The following table summarizes the possible error messages:

Status CodeStatus MessageError Description
400Bad RequestRequest body is empty or symptomText is empty, unable to search
401UnauthorizedShortcut is secured.
403Forbidden

Production mode: shortcut access only

404Not Found

Unknown shortcut, project or version

500Internal Server ErrorInternal error

Executing a decision tree

There are 2 endpoints available to execute a decision tree:

  1. http://localhost/runtime/server/api/v2/dtree/execute/{shortcut}/{name}
  2. http://localhost/runtime/server/api/v2/dtree/execute/{project}/{version}/{name}

The first endpoint needs a shortcut.Please refer to Create a shortcut in the Runtime on how to configure a shortcut. It is also possible to secure the shortcut and when doing so, please refer to Runtime Authentication for how to configure authentication on your Runtime.  

The second endpoint is only available when the development tools profile is enabled and blueriq.production.shortcuts-only=false.

Both endpoints are stateless. This means the request body should contain all the already submitted answers. 

Example search

Example Execute request
POST http://localhost/runtime/server/api/v2/dtree/execute/coffee/WhatCoffeeShouldIDrink HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic YWRtaW46d2VsY29tZQ==
Accept-Language: en-GB # header used in Blueriq to show the texts. If not set, the default language in the model is used
{
    "answers": [
        {
            "key": "Person.DateOfBirth",            
            "value": "1986-04-03"            
        },
        {
            "key": "Person.Mood",            
            "value": "Excited"            
        }
    ],
	"showAttributeSolutions": true, # The attributes used as action in the tree are returned. Default: true
	"showImplicitAnswers": false, # The response contains derived values. When false, the response does not contain derived values. Default: false
	"skipFilledQuestions": true # The tree will skip questions where the answer is known or can be derived. Default: true
}
Example Execute response
{
    "answers": [
        {
            "key": "Person.DateOfBirth",
            "type": "date",
            "value": "1986-04-03",
            "questionText": "When where you born?",
            "domain": false,
            "answered": true,
            "domainValues": []
        },
        {
            "key": "Person.Age",
            "type": "integer",
            "value": "33",
            "questionText": "Age",
            "domain": false,
            "answered": true,
            "domainValues": []
        },
        {
            "key": "Person.Mood",
            "type": "text",
            "value": "Excited",
            "questionText": "How are you feeling today?",
            "domain": true,
            "answered": true,
            "domainValues": [
                {
                    "key": "Excited",
                    "description": "I'm excited"
                },
                {
                    "key": "Peaceful",
                    "description": "I'm peaceful"
                },
                {
                    "key": "Sleepy",
                    "description": "I'm sleepy"
                },
                {
                    "key": "Cranky",
                    "description": "I'm cranky"
                },
                {
                    "key": "Depressed",
                    "description": "I'm depressed"
                },
                {
                    "key": "Stressed",
                    "description": "I'm stressed"
                }
            ]
        }
    ],
    "questions": [],
    "solutions": [
        {
            "parts": [
                {
                    "value": "In your state of mind a nice cup of chamomile tea to calm you down."
                }
            ]
        }
    ]
}

Since Blueriq 12, when a solution part contains an attribute with a value list it returns additional information in the following JSON structure:

"solutions": [
	{
		"parts": [
			{
				"value": "Excited",
				"key": "Person.Mood",
				"questionText": "How are you feeling today?",
				"displayValue": "I'm excited"
			}
		]
	}
]


The key and questionText in the JSON response correspond to the fully qualified attribute name and the Question modelled in Studio. When then attribute does not have a Value list, the value in the JSON response contains the actual value of the attribute and the displayValue is null.

When the attribute has a Value list, the value and displayValue in the JSON response correspond to the value and displayValue of the Value list modelled in Studio.

Error Messages

When the execution fails, the endpoints respond with a status code and a JSON error object detailing the encountered error. The following table summarizes the possible error messages:

Status CodeStatus MessageError Description
401UnauthorizedShortcut is secured. Security: Blueriq as a Service
403Forbidden

Production mode: shortcut access only

404Not Found

Unknown shortcut, project or version

500Internal Server ErrorInternal error