using-rest.html

---
active_crumb: REST API
layout: documentation
id: rest
---

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<div class="col-md-8 second-column">
    <section id="overview">
        <h2 class="section-title">Overview</h2>
        <p>
            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.
        </p>
        <p>
            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.
        </p>
        <div class="bq info">
            <p>
                If you downloaded ZIP archive the REST API specification is also available in
                <code>openapi/nlpcraft_swagger.yml</code> file
                or on <a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml">GitHub</a>.
            </p>
        </div>
    </section>
    <section id="java-client">
        <h3 class="section-title">Java Client <i class="fab fa-java"></i></h3>
        <p>
            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:
        </p>
        <ul>
            <li>Maven/Grape/Gradle/SBT <a href="download.html#java-client">instructions</a></li>
            <li>Latest <a target=_ href="https://nlpcraft.apache.org/apis/java-client/latest/index.html">Javadoc</a></li>
            <li>Watch, star or fork <a target="github" href="https://github.com/apache/incubator-nlpcraft-java-client">GitHub Project</a></li>
        </ul>

    </section>
    <section id="format">
        <h3 class="section-title">REST URL</h3>
        <p>
            REST API accepts only <code>POST</code> HTTP calls and <code>application/json</code> content type
            for JSON payload and responses. When issuing a REST call you will be using the following URL:
        </p>
        <pre class="brush: plain">
            https://localhost:8081/api/v1/signin
        </pre>
        <p>
        where:
        <dl>
            <dt><code>http</code></dt>
                <dd>Either <code>http</code> or <code>https</code> protocol.</dd>
            <dt><code>localhost:8081</code></dt>
                <dd>Host and port on which REST server is started. <code>localhost:8081</code> is the default configuration and can be <a href="server-and-probe.html">changed</a>.</dd>
            <dt><code>/api/v1</code></dt>
                <dd>Mandatory prefix indicating API version.</dd>
            <dt><code>/signin</code></dt>
                <dd>Specific REST call.</dd>
        </dl>
        <div class="bq info">
            <p>
                <b>bin/nccurl.sh</b>
            </p>
            <p>
                <a target="wiki" href="https://en.wikipedia.org/wiki/CURL">cURL</a> is an excellent utility for testing REST services from the command line and scripts.
                NLPCraft comes with a convenient wrapper script <code>bin/nccurl.sh</code> that shortens
                command line of the standard cURL. We recommend adding <code>bin/nccurl.sh</code> to your
                <code>$PATH</code> environment variable.
            </p>
        </div>
        <p>
            REST API is divided into five functional groups:
        </p>
        <ul>
            <li><a href="#auth">Authentication</a></li>
            <li><a href="#asking">Asking</a></li>
            <li><a href="#company">Company Management</a></li>
            <li><a href="#user">User Management</a></li>
            <li><a href="#data_probe">Data Probe Management</a></li>
        </ul>
        <div class="bq info">
            <b>Admins</b>
            <p>
                Note that 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.
            </p>
        </div>
        <div class="bq info">
            <b>External User ID</b>
            <p>
                Many calls on REST API accept external "on-behalf-of" user ID (<code>usrExtId</code>) additionally to the regular
                user ID (<code>usrID</code>). 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.
            </p>
            <p>
                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.
            </p>
        </div>
    </section>
    <section id="auth">
        <h3 class="section-title">Authentication</h3>
        <p>
            Before performing any REST calls a registered user needs to sign in to receive
            an <b>access token</b> that will be used in all subsequent operations:
        </p>
        <table class="gradient-table">
            <thead>
            <tr>
                <th>REST call</th>
                <th>Description</th>
            </tr>
            </thead>
            <tbody>
                <tr>
                    <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/signin</code></nobr></a></td>
                    <td>Sign in and obtain <b>access token</b>.</td>
                </tr>
                <tr>
                    <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/signout</code></nobr></a></td>
                    <td>Sign out and invalidate previously obtained <b>access token</b>.</td>
                </tr>
            </tbody>
        </table>
        <div class="bq info">
            <b>Default User</b>
            <p>
                NLPCraft comes with a default built-in credentials that you can use when signing in for the
                first time:
            </p>
            <ul>
                <li>Email: <code>admin@admin.com</code></li>
                <li>Password: <code>admin</code></li>
            </ul>
        </div>
        <div class="bq warn">
            <p>
                In production environment make sure to delete this default user once you add at least one of your
                own users with administrative privileges.
            </p>
        </div>
    </section>
    <section id="asking">
        <h3 class="section-title">Asking</h3>
        <p>
            This is the main group of operation that allows to ask questions, check the status and get
            result:
        </p>
        <table class="gradient-table">
            <thead>
            <tr>
                <th>REST call</th>
                <th>Description</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/ask</code></nobr></a></td>
                <td>Submit the sentence to be processed <b>asynchronously</b>.</td>
            </tr>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/ask/sync</code></nobr></a></td>
                <td>Submit the sentence to be processed <b>synchronously</b>. </td>
            </tr>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/check</code></nobr></a></td>
                <td>Get statuses and results for previously submitted <code>/ask</code> requests.</td>
            </tr>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/cancel</code></nobr></a></td>
                <td>
                    Remove results from the server memory.
                </td>
            </tr>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/clear/conversation</code></nobr></a></td>
                <td>
                    Clear the conversation STM for current user and data model.
                </td>
            </tr>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/clear/dialog</code></nobr></a></td>
                <td>
                    Clear the dialog flow for current user and data model.
                </td>
            </tr>
            </tbody>
        </table>
    </section>
    <section id="company">
        <h3 class="section-title">Company Management</h3>
        <p>
            This group of operations allows to add, update and remove companies in the systems.
        </p>
        <table class="gradient-table">
            <thead>
            <tr>
                <th>REST call</th>
                <th>Description</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/company/get</code></nobr></a></td>
                <td>Gets current user company.</td>
            </tr>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/company/add</code></nobr></a></td>
                <td>Add new company.</td>
            </tr>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/company/update</code></nobr></a></td>
                <td>Update company information.</td>
            </tr>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/company/delete</code></nobr></a></td>
                <td>Delete company.</td>
            </tr>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/company/token/reset</code></nobr></a></td>
                <td>Reset company's authentication token.</td>
            </tr>
            </tbody>
        </table>
    </section>
    <section id="user">
        <h3 class="section-title">User Management</h3>
        <p>
            This group of operations allows to add, update and remove users in the systems:
        </p>
        <table class="gradient-table">
            <thead>
            <tr>
                <th>REST call</th>
                <th>Description</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/user/get</code></nobr></a></td>
                <td>Get current user information.</td>
            </tr>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/user/all</code></nobr></a></td>
                <td>Get all users.</td>
            </tr>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/user/add</code></nobr></a></td>
                <td>Add new user.</td>
            </tr>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/user/update</code></nobr></a></td>
                <td>Update user information.</td>
            </tr>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/user/delete</code></nobr></a></td>
                <td>Delete user.</td>
            </tr>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/user/admin</code></nobr></a></td>
                <td>Change user administrative privileges.</td>
            </tr>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/user/passwd/reset</code></nobr></a></td>
                <td>
                    Reset the current user password.
                </td>
            </tr>
            </tbody>
        </table>
    </section>
    <section id="data_probe">
        <h3 class="section-title">Data Probe Management</h3>
        <p>
            This group of operations allows to get the information about connected data probes:
        </p>
        <table class="gradient-table">
            <thead>
            <tr>
                <th>REST call</th>
                <th>Description</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td><a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml"><nobr><code>/probes/all</code></nobr></a></td>
                <td>Get information about connected probes.</td>
            </tr>
            </tbody>
        </table>
    </section>
    <section id="server_errors">
        <h2 class="section-title">Server Errors</h2>
        <p>
            When REST server returns HTTP error the response body contains JSON object (<code>Content-Type → application/json</code>)
            with two fields <code>code</code> and <code>msg</code>:
        </p>
        <pre class="brush: js">
        {
            "code": "NC_INVALID_ACCESS_TOKEN",
            "msg": "Unknown access token: PPdxjwXBOIMpAWNgpKq1"
        }
        </pre>
        <p>
            Following tables shows all possible <code>code</code> values for these server errors:
        </p>
        <table class="gradient-table">
            <thead>
            <tr>
                <th>Code</th>
                <th>Description</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td><code>NC_INVALID_ACCESS_TOKEN</code></td>
                <td>
                    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.
                </td>
            </tr>
            <tr>
                <td><code>NC_SIGNIN_FAILURE</code></td>
                <td>
                    Invalid or unknown user email and/or user password during <code>/signin</code> 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.
                </td>
            </tr>
            <tr>
                <td><code>NC_NOT_IMPLEMENTED</code></td>
                <td>
                    Particular feature is not implemented yet or not available. This is reserved for API extensions and
                    future backward compatibility.
                </td>
            </tr>
            <tr>
                <td><code>NC_INVALID_FIELD</code></td>
                <td>
                    This indicated a problem with a field. It's either too bit, too small, empty or otherwise invalid.
                    See <code>msg</code> field in the error response for details.
                </td>
            </tr>
            <tr>
                <td><code>NC_ADMIN_REQUIRED</code></td>
                <td>
                    Calling user is required to have admin privileges to execute given call.
                </td>
            </tr>
            <tr>
                <td><code>NC_INVALID_OPERATION</code></td>
                <td>
                    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.
                </td>
            </tr>
            <tr>
                <td><code>NC_ERROR</code></td>
                <td>Indicates a general server error.</td>
            </tr>
            </tbody>
        </table>
    </section>
</div>
<div class="col-md-2 third-column">
    <ul class="side-nav">
        <li class="side-nav-title">On This Page</li>
        <li><a href="#format">REST URL</a></li>
        <li><a href="#auth">Authentication</a></li>
        <li><a href="#company">Company</a></li>
        <li><a href="#user">Users</a></li>
        <li><a href="#asking">Asking</a></li>
        <li><a href="#data_probe">Data Probes</a></li>
        <li><a href="#server_errors">Server Errors</a></li>
        {% include quick-links.html %}
    </ul>
</div>