In this section you can find a description of the novomind iAGENT Help REST API.
If you consider creating an external app that needs access to the resources of a novomind iAGENT Help installation you will want to use the novomind iAGENT Help REST API. The API can be used to embed the novomind iAGENT Help technology in a website or any other user interface.
By default, all requests to api/rest receive the latest version of the REST API. We recommend you to explicitly request this version via the Accept header.
Accept: application/vnd.novomind.iq-v3.0+json
The novomind iAGENT Help versions and the corresponding supported API versions are listed in the following table:
| novomind iAGENT Help Version | Supported API version |
|---|---|
| >= 8.5.46 | V1 |
| >= 10.0.16 | V1, V2 |
| >= 10.0.112 | V1, V2, V3 |
The API can be accesed over http or https, which depends on the web server configuration. The responses are send as JSON or in case of errors as plain text.
curl -i https://<hostname>/nmIQ/api/rest/ask?text=Hi
HTTP/1.1 200 OK
Date: Mon, 01 May 2017 00:00:00 GMT
p3p: This is not a P3P policy!
Vary: Accept-Encoding
Content-Type: application/vnd.novomind.iq-v3.0+json;charset=UTF-8
Content-Length: 249
{
"faqs" : [{"id":3672},{"id":3667},{"id":3720}],
"response" : "Hello and welcome, dear visitor! How can I help you? ",
"emotion" : "[02]",
"frame" : null,
"javascript" : null
Since version v3 blank fields are included as null instead of being omitted.
The json responses can be extended in future novomind iAGENT Help releases without a modification of the API version. We recommend you to disable strict validation in your json parser. The JSON library "jackson" supports this by using the JsonIgnoreProperties annotation:
@JsonIgnoreProperties(ignoreUnknown=true)
All timestamps return in ISO 8601 format:
YYYY-MM-DDTHH:MM:SSZ
The API supports Cross Origin Resource Sharing (CORS) for AJAX requests. The allowed origins have to be whitelisted in the novomind iAGENT Help configuration.
curl -i -H "Origin: http://example.com" https://<hostname>/nmIQ/api/rest/ask?text=Hi
HTTP/1.1 200 OK
Date: Mon, 01 MAy 2017 00:00:00 GMT
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, HEAD, POST, PUT, DELETE
Access-Control-Allow-Headers: origin, content-type, accept
Content-Type: application/json;charset=UTF-8
...
In case of errors the api returns a plain text response with the error message.
curl -i -X POST https://<hostname>/nmIQ/api/rest/evaluate
HTTP/1.1 400 Bad Request
Date: Mon, 29 May 2017 14:25:54 GMT
Content-Type: text/plain;charset=UTF-8
Content-Length: 25
Connection: close
session expired / invalid