nlpcraft.{sh|cmd}
View Open API Specification in a separate window. 👌
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.
If you downloaded ZIP archive the REST API specification is also available in openapi/nlpcraft_swagger.yml
file or on GitHub.
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:
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
http
or https
protocol.localhost:8081
localhost:8081
is the default configuration and can be changed./api/v1
/signin
Management Script
bin/nlpcraft.{sh|cmd}
script is a central management utility for NLPCraft. Among many commands it provides, there are two commands call
and rest
that allows for simple and effective REST API usage against local REST server.
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.
NLPCraft comes with the default account:
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.
âš Default Account âš
Make sure to delete the default account when you go to production or as soon as you have other secure administrative account that can act as a bootstrap account.
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.
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.
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:
Code | Description |
---|---|
NC_INVALID_ACCESS_TOKEN | The access token is invalid or no longer valid. Note that previously issued existing access tokens can expire or be otherwise invalidated and have to be obtained again. |
NC_SIGNIN_FAILURE | Invalid or unknown user email and/or user password during /signin call. This can indicate either the attempt to signin by the user that hasn't been added yet, or the invalid password for the existing user. |
NC_NOT_IMPLEMENTED | Particular feature is not implemented yet or not available. This is reserved for API extensions and future backward compatibility. |
NC_INVALID_FIELD | This indicated a problem with a field. It's either too bit, too small, empty or otherwise invalid. See msg field in the error response for details. |
NC_ADMIN_REQUIRED | Calling user is required to have admin privileges to execute given call. |
NC_INVALID_OPERATION | Indicates that a given operation cannot be performed as specified. For example, this error is returned when you attempt to remove or revoke admin privileges from the last admin user. |
NC_ERROR | Indicates a general server error. |