REST API

TL;DR;

View Open API Specification in a separate window. 👌

...bit more details

REST API provides a universal integration path for any type of user application to connect to and use NLPCraft. By using REST API these applications can ask natural language questions, get results and perform many supporting operations such as user management.

REST server accepts the REST call, interprets and routes it to the appropriate data probe which in turn invokes one of its deployed data models. The result of data model processing travels all the way through the same chain of components back to the user application that made the original call.

Java Client

NLPCraft provide native Java client that enables easy-to-use Java-based API wrapping standard NLPCraft REST APIs. It can be used by any JVM language that provides Java interop such as Scala, Groovy, or Kotlin:

• Maven/Grape/Gradle/SBT instructions
• Latest Javadoc
• Watch, star or fork GitHub Project

REST URL

REST API accepts only POST HTTP calls and application/json content type for JSON payload and responses. When issuing a REST call you will be using the following URL:

            https://localhost:8081/api/v1/signin
        

where:

http

Either http or https protocol.

localhost:8081

Host and port on which REST server is started. localhost:8081 is the default configuration and can be changed.

/api/v1

Mandatory prefix indicating API version.

/signin

Specific REST path.

Users & Organizations

In NLPCraft most of the REST calls require ID of the user. Every user belongs to a company, and each user has administrative privileges flag. The notion of the user and company IDs additionally to the model ID provide necessary attributes for proper probe authentication, conversation maintenance, and security.

Default Account

NLPCraft comes with the default account:

• Email: admin@admin.com
• Password: admin

This account has administrative privileges and should be used as a bootstrap account to create other accounts. Make sure to delete this account when you go to production.

Admins

Many operations are only available to the users with administrative privileges. Note also that some operations will implicitly behave differently based on whether the currently signed in user have administrative privileges or not.

External User ID

Many calls on REST API accept external "on-behalf-of" user ID (usrExtId) additionally to the regular user ID (usrID). In these methods zero, one or both IDs must be provided. If none are provided the ID of the currently signed in user will be used. If both are provided they should point to the same user. External user ID allows to use user identification from the external systems without a need to import all the existing users into NLPCraft in the first place.

Typical usage pattern for integrating NLPCraft into existing system is to create a single administrative NLPCraft user, sign in with that account and then use external "on-behalf-of" user IDs in all the requests. This way you get the same functionality as if using ordinary user IDs but without a need to migrate and synchronize all user accounts from the existing system to NLPCraft.

Server Errors

When REST server returns HTTP error the response body contains JSON object (Content-Type → application/json) with two fields code and msg:

        {
            "code": "NC_INVALID_ACCESS_TOKEN",
            "msg": "Unknown access token: PPdxjwXBOIMpAWNgpKq1"
        }
        

Following tables shows all possible code values for these server errors: