#
# 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.
#

swagger: "2.0"
info:
  description: REST API for [Apache NLPCraft](https://nlpcraft.apache.org) - an open source library for adding Natural Language Interface to any applications. For Data Model APIs see [Javadoc](https://nlpcraft.apache.org/apis/latest/index.html) documentation.
  version: 0.5.0
  title: Apache NLPCraft API
host: localhost:8081
basePath: /api/v1
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
tags:
  - name: Authentication
    description: >-
      User signing in (getting access token), singing out and password reset.
  - name: Users
    description: >-
      Adding, removing and managing users.
  - name: Companies
    description: >-
      Adding, removing and managing companies.
  - name: Feedbacks
    description: >-
      Adding, removing and getting requests feedback.
  - name: Data Probe
    description: >-
      Managing data probes.
  - name: Asking
    description: >-
      Asking questions, checking results, clearing conversation and dialog context.
paths:
  /clear/conversation:
    post:
      tags:
        - Asking
      summary: Clears conversation STM.
      description: >-
        Clears conversation for given user and data model. Essentially makes NLPCraft forget
        about previously stored sentences and the next request will be processed as if at the start of the
        new conversation.
      operationId: clearConversation
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
              - mdlId
            properties:
              acsTok:
                type: string
                description: Access token obtain via '/signin' call
                maxLength: 256
              mdlId:
                type: string
                maxLength: 32
                description: Data model ID for which to clear conversation
              usrId:
                type: integer
                format: int64
                description: >-
                  User ID for which to clear conversation. Optional, caller user ID used by default.
                  Clearing conversation for other users from the same company requires administrative
                  privileges. If both user ID and external 'on-behalf-of' user ID are provided they have to
                  point to the same NLPCraft user.
              usrExtId:
                type: string
                description: >-
                  External 'on-behalf-of' user ID for which to clear conversation. Optional, caller
                  user ID used by default. Clearing conversation for other users from the same company
                  requires administrative privileges. If both user ID and external 'on-behalf-of' user ID are
                  provided they have to point to the same NLPCraft user. Note that if only external 'on-behalf-of'
                  user ID is provided and such user doesn't yet exist in NLPCraft - it will be created with this ID.
                maxLength: 64
      responses:
        '200':
          description: Successful operation.
          schema:
            $ref: '#/definitions/Ok'
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /clear/dialog:
    post:
      tags:
        - Asking
      summary: Clears dialog flow.
      description: >-
        Clears dialog flow for given user and data model by forgetting all previously matched intents. It is an
        important operation for intents that use dialog flow in their matching logic.
      operationId: clearDialog
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
              - mdlId
            properties:
              acsTok:
                type: string
                description: Access token obtain via '/signin' call
                maxLength: 256
              mdlId:
                type: string
                maxLength: 32
                description: Data model ID for which to clear dialog flow
              usrId:
                type: integer
                format: int64
                description: >-
                  User ID for which to clear dialog flow. Optional, caller user ID used by default.
                  Clearing dialog flow for other users from the same company requires administrative
                  privileges. If both user ID and external 'on-behalf-of' user ID are provided they
                  have to point to the same NLPCraft user.
              usrExtId:
                type: string
                description: >-
                  External 'on-behalf-of' user ID for which to clear dialog flow. Optional, caller
                  user ID used by default. Clearing dialog flow for other users from the same company
                  requires administrative privileges. If both user ID and external 'on-behalf-of' user
                  ID are provided they have to point to the same NLPCraft user. Note that if only external
                  'on-behalf-of' user ID is provided and such user doesn't yet exist in NLPCraft - it will
                  be created with this ID.
                maxLength: 64
      responses:
        '200':
          description: Successful operation.
          schema:
            $ref: '#/definitions/Ok'
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /check:
    post:
      tags:
        - Asking
      summary: Gets status and result of submitted requests.
      description: >-
          Gets the status and result (OK or failure) of the previously submitted requests.
          Request statuses returned sorted by their registration time, starting from newest.
      operationId: check
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
            properties:
              acsTok:
                type: string
                description: Access token obtain via '/signin' call
                maxLength: 256
              usrId:
                type: integer
                format: int64
                description: >-
                  User ID for which to check the results. Optional, caller user ID used by default.
                  Checking results for other users from the same company requires administrative privileges. If
                  both user ID and external 'on-behalf-of' user ID are provided they have to point to the
                  same NLPCraft user.
              usrExtId:
                type: string
                description: >-
                  External 'on-behalf-of' user ID for which to check the results. Optional, caller
                  user ID used by default. Checking results for other users from the same company requires
                  administrative privileges. If both user ID and external 'on-behalf-of' user ID are provided
                  they have to point to the same NLPCraft user. Note that if only external 'on-behalf-of'
                  user ID is provided and such user doesn't yet exist in NLPCraft - it will be created with this ID.
                maxLength: 64
              srvReqIds:
                type: array
                items:
                  type: string
                description: >-
                  Optional list of server request IDs to check - by default, all current user requests will be returned.
                  Note, there won't be any errors if invalid server requests IDs are provided (safely ignored instead).
              maxRows:
                type: integer
                format: int64
                description: Optional maximum number of returned items - by default all items will be returned
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - states
            properties:
              status:
                type: string
                description: Status code of this operation
                enum:
                  - API_OK
              states:
                type: array
                items:
                  type: object
                  required:
                    - srvReqId
                    - txt
                    - usrId
                    - mdlId
                    - status
                    - error
                    - errorCode
                  properties:
                    srvReqId:
                      type: string
                      description: Server request ID
                    txt:
                      type: string
                      description: Original request text
                    usrId:
                      type: integer
                      format: int64
                      description: ID of the user that submitted the request
                    mdlId:
                      type: string
                      description: ID of the model
                    probeId:
                      type: string
                      description: ID of the data probe
                    status:
                      type: string
                      description: >-
                        Current status of this request (QRY_READY indicates that
                        result - error or ok - is ready)
                      enum:
                        - QRY_ENLISTED
                        - QRY_READY
                    resType:
                      type: string
                      description: >-
                        Optional result type if returned by model (provided only
                        if status is QRY_READY and processing was not rejected
                        or terminated due to an exception)
                    resBody:
                      type: object
                      description: >-
                        Optional body (string or JSON object) of the result if returned by model
                        (provided only if status is QRY_READY and processing was
                        not rejected or terminated due to an exception)
                    error:
                      type: string
                      description: >-
                        Optional error if returned by model (provided only if
                        status is QRY_READY and processing was rejected or
                        terminated due to an exception)
                    errorCode:
                      type: integer
                      format: int32
                      description: >-
                        Optional error code indicating a type of error. Only present
                        of 'error' field is present. One of the following values:
                        1 - Rejection by the data model.
                        100 - Unexpected system error.
                        101 - Model's result is too big.
                        102 - Recoverable system error.
                        10001 - Too many unknown words.
                        10002 - Sentence is too complex (too many free words).
                        10003 - Too many suspicious or unrelated words.
                        10004 - Swear words found and are not allowed.
                        10005 - Sentence contains no nouns.
                        10006 - Only latin charset is supported.
                        10007 - Only english language is supported.
                        10008 - Sentence seems unrelated to data model.
                        10009 - Sentence is too short (before processing).
                        10010 - Sentence is ambiguous.
                        10011 - Sentence is too short (after processing).
                        10012 - Sentence is too long.
                    logHolder:
                      type: object
                      description: Optional logger data holder as JSON object
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /cancel:
    post:
      tags:
        - Asking
      summary: Cancels a question.
      description: >-
        Cancels the previously submitted sentence and removes its result, if any, from the server storage.
        Must be called when query result is no longer needed (i.e. downloaded by all client apps) to release the server memory.
        Note that query results will auto-expire on server after a certain period of time. Note also that even
        when the embedded probe is used the results are still stored on the server and have to be cancelled or
        otherwise will be timed out.
      operationId: cancel
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
            properties:
              acsTok:
                type: string
                description: Access token obtain via '/signin' call
                maxLength: 256
              usrId:
                type: integer
                format: int64
                description: >-
                  ID of the user whose requests to cancel. Optional, caller user ID used by default.
                  Cancelling requests for other users from the same company requires administrative privileges. If
                  both user ID and external 'on-behalf-of' user ID are provided they have to point to the
                  same NLPCraft user.
              usrExtId:
                type: string
                description: >-
                  External 'on-behalf-of' ID of the user whose requests to cancel. Optional, caller
                  user ID used by default. Cancelling requests for other users from the same company requires
                  administrative privileges. If both user ID and external 'on-behalf-of' user ID are provided
                  they have to point to the same NLPCraft user. Note that if only external 'on-behalf-of'
                  user ID is provided and such user doesn't yet exist in NLPCraft - it will be created with this ID.
                maxLength: 64
              srvReqIds:
                type: array
                items:
                  type: string
                description: >-
                  Server IDs of the requests to cancel. Optional, all current user requests will be cancelled by default.
                  Note, there aren't errors even if invalid server requests identifiers provided as arguments.
      responses:
        '200':
          description: Successful operation.
          schema:
            $ref: '#/definitions/Ok'
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /ask:
    post:
      tags:
        - Asking
      summary: Asks a question.
      description: >-
        Submits the sentence to be processed asynchronously. Use '/check' call to get status and result, and '/cancel'
        call to discard the result from the server storage without waiting for auto-expiration.
      operationId: ask
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
              - txt
              - mdlId
            properties:
              acsTok:
                type: string
                description: Access token obtain via '/signin' call
                maxLength: 256
              usrId:
                type: integer
                format: int64
                description: >-
                  ID of the user submitting the question. Optional, caller user ID used by default.
                  Submitting questions for other users from the same company requires administrative privileges. If
                  both user ID and external 'on-behalf-of' user ID are provided they have to point to the
                  same NLPCraft user.
              usrExtId:
                type: string
                description: >-
                  External 'on-behalf-of' ID of the user submitting the question. Optional, caller
                  user ID used by default. Submitting questions for other users from the same company requires
                  administrative privileges. If both user ID and external 'on-behalf-of' user ID are provided
                  they have to point to the same NLPCraft user. Note that if only external 'on-behalf-of' user ID
                  is provided and such user doesn't yet exist in NLPCraft - it will be created with this ID.
                maxLength: 64
              txt:
                type: string
                description: Text of the question
                maxLength: 1024
              mdlId:
                type: string
                description: >-
                  Model ID.
                maxLength: 32
              data:
                type: object
                description: >-
                  Additional user-defined JSON data to be passed along with the request with maximum
                  JSON length of 512000 bytes
              enableLog:
                description: Flag to enable detailed processing log to be returned with the result
                type: boolean
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - srvReqId
            properties:
              status:
                type: string
                description: Status code of this operation
                enum:
                  - API_OK
              srvReqId:
                type: string
                description: Server ID assigned to the new processing request
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /ask/sync:
    post:
      tags:
        - Asking
      summary: Asks a question in synchronous mode.
      description: >-
        Submits the sentence to be processed synchronously and returns the result immediately.
        This call will block until the result is ready or the waiting is timed out.
      operationId: askSync
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
              - txt
              - mdlId
            properties:
              acsTok:
                type: string
                description: Access token obtain via '/signin' call
                maxLength: 256
              usrId:
                type: integer
                format: int64
                description: >-
                  ID of the user submitting the question. Optional, caller user ID used by default.
                  Submitting questions for other users from the same company requires administrative privileges. If
                  both user ID and external 'on-behalf-of' user ID are provided they have to point to the
                  same NLPCraft user.
              usrExtId:
                type: string
                description: >-
                  External 'on-behalf-of' ID of the user submitting the question. Optional, caller
                  user ID used by default. Submitting questions for other users from the same company requires
                  administrative privileges. If both user ID and external 'on-behalf-of' user ID are provided
                  they have to point to the same NLPCraft user. Note that if only external 'on-behalf-of' user ID
                  is provided and such user doesn't yet exist in NLPCraft - it will be created with this ID.
                maxLength: 64
              txt:
                type: string
                description: Text of the question
                maxLength: 1024
              mdlId:
                type: string
                description: >-
                  Model ID.
                maxLength: 32
              data:
                type: object
                description: >-
                  Additional sentence JSON data with maximum JSON length of 512000 bytes
              enableLog:
                description: Flag to enable detailed processing log to be returned with the result
                type: boolean
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - state
            properties:
              status:
                type: string
                description: Status code of this operation
                enum:
                  - API_OK
              state:
                type: object
                required:
                  - srvReqId
                  - txt
                  - usrId
                  - mdlId
                  - status
                  - error
                  - errorCode
                properties:
                  srvReqId:
                    type: string
                    description: Server request ID
                  txt:
                    type: string
                    description: Original request text
                  usrId:
                    type: integer
                    format: int64
                    description: ID of the user that submitted the request
                  mdlId:
                    type: string
                    description: ID of the model
                  probeId:
                    type: string
                    description: ID of the data probe
                  status:
                    type: string
                    description: >-
                      Current status of this request (QRY_READY indicates that
                      result - error or ok - is ready)
                    enum:
                      - QRY_ENLISTED
                      - QRY_READY
                  resType:
                    type: string
                    description: >-
                      Optional result type if returned by model (provided only
                      if status is QRY_READY and processing was not rejected
                      or terminated due to an exception)
                  resBody:
                    type: object
                    description: >-
                      Optional body (string or JSON object) of the result if returned by model
                      (provided only if status is QRY_READY and processing was
                      not rejected or terminated due to an exception)
                  error:
                    type: string
                    description: >-
                      Optional error if returned by model (provided only if
                      status is QRY_READY and processing was rejected or
                      terminated due to an exception)
                  errorCode:
                    type: integer
                    format: int32
                    description: >-
                      Optional error code indicating a type of error. Only present
                      of 'error' field is present.
                  logHolder:
                    type: object
                    description: Optional logger data holder as JSON object
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /user/get:
    post:
      tags:
        - Users
      summary: Gets current user information.
      description: Gets current user information.
      operationId: getUser
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
            properties:
              acsTok:
                maxLength: 256
                description: Access token obtain via '/signin' call
                type: string
              id:
                type: integer
                format: int64
                description: >-
                  ID of the user. Optional, caller user ID used by default.
                  Getting information about other users from the same company requires administrative privileges. If
                  both user ID and external 'on-behalf-of' user ID are provided they have to point to the
                  same NLPCraft user.
              extId:
                type: string
                description: >-
                  External 'on-behalf-of' ID of the user. Optional, caller
                  user ID used by default. Getting information for other users from the same company requires
                  administrative privileges. If both user ID and external 'on-behalf-of' user ID are provided
                  they have to point to the same NLPCraft user. F
                maxLength: 64
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - id
              - isAdmin
            properties:
              status:
                type: string
                description: Status code of this operation
                enum:
                  - API_OK
              id:
                description: User ID
                type: integer
                format: int64
              email:
                description: User email
                type: string
              extId:
                description: User external ID
                type: string
              firstName:
                description: User first or given name
                type: string
              lastName:
                description: User last name
                type: string
              avatarUrl:
                description: User avatar URL
                type: string
              isAdmin:
                description: Whether or not user has Administrative privileges
                type: boolean
              properties:
                type: object
                description: Additional user properties
                additionalProperties:
                  type: string
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /user/all:
    post:
      tags:
        - Users
      summary: Gets all users.
      description: Gets all users for the current user company. Administrative privileges required.
      operationId: getAllUsers
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
            properties:
              acsTok:
                maxLength: 256
                description: Access token obtain via '/signin' call
                type: string
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - users
            properties:
              status:
                type: string
                description: Status code of this operation
                enum:
                  - API_OK
              users:
                type: array
                items:
                  type: object
                  required:
                    - id
                    - isAdmin
                  properties:
                    id:
                      description: User ID
                      type: integer
                      format: int64
                    email:
                      description: User email
                      type: string
                    extId:
                      description: User external 'on-behalf-of' ID
                      type: string
                    firstName:
                      description: User first or given name
                      type: string
                    lastName:
                      description: User last name
                      type: string
                    avatarUrl:
                      description: User avatar URL
                      type: string
                    isAdmin:
                      description: Whether or not user has Administrative privileges
                      type: boolean
                    properties:
                      type: object
                      description: Additional user properties
                      additionalProperties:
                        type: string
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /user/update:
    post:
      tags:
        - Users
      summary: Updates regular user.
      description: >-
        Updates user with given ID or the current user with given parameters.
        Administrative privileges required for updating other user.
      operationId: updateUser
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
              - firstName
              - lastName
            properties:
              acsTok:
                type: string
                description: Access token obtain via '/signin' call
                maxLength: 256
              id:
                description: >-
                  Optional ID of the user to update. Only administrators can
                  provide this parameter. Current user ID is used by default.
                type: integer
                format: int64
              firstName:
                type: string
                description: User first or given name
                maxLength: 64
              lastName:
                type: string
                description: User last name
                maxLength: 64
              avatarUrl:
                type: string
                description: Optional user avatar URL
                maxLength: 512000
              properties:
                type: object
                description: Additional user properties
                additionalProperties:
                  type: string
      responses:
        '200':
          description: Successful operation.
          schema:
            $ref: '#/definitions/Ok'
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /user/delete:
    post:
      tags:
        - Users
      summary: Deletes user.
      description: >-
        Deletes user with given ID or the current user.
        Administrative privileges required for deleting other user.
      operationId: deleteUser
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
            properties:
              acsTok:
                maxLength: 256
                description: Access token obtain via '/signin' call
                type: string
              id:
                description: >-
                  Optional ID of the user to delete. Only administrators can
                  provide this parameter. Current user ID is used by default. If both user ID
                  and external 'on-behalf-of' user ID are provided they have to point to the same NLPCraft user.
                type: integer
                format: int64
              extId:
                maxLength: 64
                description: >-
                  External 'on-behalf-of' ID of the user to delete. Optional, caller
                  user ID used by default. Administrative privileges are required to delete
                  other users from the same company. If both user ID and external 'on-behalf-of' user ID
                  are provided they have to point to the same NLPCraft user.
                type: string
      responses:
        '200':
          description: Successful operation.
          schema:
            $ref: '#/definitions/Ok'
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /user/admin:
    post:
      tags:
        - Users
      summary: Updates user admin permissions.
      description: >-
        Updates user's permissions with given ID or the current user.
        Administrative privileges required for this operation.
      operationId: adminUser
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
              - isAdmin
            properties:
              acsTok:
                maxLength: 256
                description: Access token obtain via '/signin' call
                type: string
              id:
                description: >-
                  Optional ID of the user to update - current user ID is used by default.
                type: integer
                format: int64
              isAdmin:
                description: Administrative privileges flag to update to
                type: boolean
      responses:
        '200':
          description: Successful operation.
          schema:
            $ref: '#/definitions/Ok'
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /user/passwd/reset:
    post:
      tags:
        - Users
      summary: Resets password for the user.
      description: >-
        Resets the password for the user. Note that NLPCraft doesn't store password in reversible way
        and there is no way to retrieve the current password - user can only reset the password.
      operationId: passwdReset
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
              - newPasswd
            properties:
              acsTok:
                maxLength: 256
                description: Previously obtained access token to release.
                type: string
              id:
                description: >-
                  Optional ID of the user to reset password. Only admins
                  can provide this parameter. Current user ID is used by default.
                type: integer
                format: int64
              newPasswd:
                type: string
                description: New user password
                maxLength: 64
      responses:
        '200':
          description: Successful operation.
          schema:
            $ref: '#/definitions/Ok'
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /user/add:
    post:
      tags:
        - Users
      summary: Adds new user.
      description: Adds new user with given parameters to the company of the admin caller. Administrative privileges required.
      operationId: addUser
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
              - email
              - passwd
              - firstName
              - lastName
              - isAdmin
            properties:
              acsTok:
                type: string
                description: Access token obtain via '/signin' call
                maxLength: 256
              email:
                type: string
                description: User email
                maxLength: 64
              passwd:
                type: string
                description: User password
              firstName:
                type: string
                description: User first or given name
                maxLength: 64
              lastName:
                type: string
                description: User last name
                maxLength: 64
              avatarUrl:
                type: string
                description: Optional user avatar URL
                maxLength: 512000
              isAdmin:
                type: boolean
                description: Admin flag
              properties:
                type: object
                description: Additional user properties
                additionalProperties:
                  type: string
              extId:
                type: string
                description: Optional user external ID. If this field defined, method tries to find and update existed technical user.
                maxLength: 64
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - id
            properties:
              status:
                type: string
                description: Status code of this operation
                enum:
                  - API_OK
              id:
                type: integer
                format: int64
                description: ID of the newly created user
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /company/get:
    post:
      tags:
        - Companies
      summary: Gets current user company information.
      description: Gets current user company information.
      operationId: getCompany
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
            properties:
              acsTok:
                type: string
                description: Access token obtain via '/signin' call
                maxLength: 256
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - id
              - name
            properties:
              status:
                type: string
                description: Status code of this operation
                enum:
                  - API_OK
              id:
                description: Company ID
                type: integer
                format: int64
              name:
                description: Company name
                type: string
              website:
                description: Copmany website
                type: string
              country:
                description: Company country
                type: string
              region:
                description: Company region
                type: string
              city:
                description: Company city
                type: string
              address:
                description: Company address
                type: string
              postalCode:
                description: Company postal code
                type: string
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /company/add:
    post:
      tags:
        - Companies
      summary: Adds new company.
      description: >-
        Adds new company with given parameters.
        Administrative privileges required.
      operationId: addCompany
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
              - name
              - adminEmail
              - adminPasswd
              - adminFirstName
              - adminLastName
            properties:
              acsTok:
                type: string
                description: Access token obtain via '/signin' call
                maxLength: 256
              name:
                type: string
                description: Company name
                maxLength: 64
              website:
                type: string
                description: Optional company website address
                maxLength: 256
              country:
                type: string
                description: Optional company country
                maxLength: 32
              region:
                type: string
                description: Optional company region
                maxLength: 512
              city:
                type: string
                description: Optional company city
                maxLength: 512
              address:
                type: string
                description: Optional company address
                maxLength: 512
              postalCode:
                type: string
                description: Optional company postal code
                maxLength: 512
              adminEmail:
                type: string
                description: Admin user email
                maxLength: 64
              adminPasswd:
                type: string
                description: Admin user password
              adminFirstName:
                type: string
                description: Admin user first or given name
                maxLength: 64
              adminLastName:
                type: string
                description: Admin user last name
                maxLength: 64
              adminAvatarUrl:
                type: string
                description: Optional admin user avatar URL
                maxLength: 512000
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - token
              - adminId
            properties:
              status:
                type: string
                description: Status code of this operation
                enum:
                  - API_OK
              token:
                type: string
                description: Company probes authentication token
              adminId:
                type: integer
                format: int64
                description: ID of the newly created admin user
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /company/update:
    post:
      tags:
        - Companies
      summary: Updates company data.
      description: >-
        Updates company data with given parameters.
        Administrative privileges required.
      operationId: updateCompany
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
              - name
            properties:
              acsTok:
                type: string
                description: Access token obtain via '/signin' call
                maxLength: 256
              name:
                type: string
                description: Company name
                maxLength: 64
              website:
                type: string
                description: Optional company website address
                maxLength: 256
              country:
                type: string
                description: Optional company country
                maxLength: 32
              region:
                type: string
                description: Optional company region
                maxLength: 512
              city:
                type: string
                description: Optional company city
                maxLength: 512
              address:
                type: string
                description: Optional company address
                maxLength: 512
              postalCode:
                type: string
                description: Optional company postal code
                maxLength: 512
      responses:
        '200':
          description: Successful operation.
          schema:
            $ref: '#/definitions/Ok'
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /company/delete:
    post:
      tags:
        - Companies
      summary: Deletes company.
      description: >-
        Deletes company.
        Administrative privileges required.
      operationId: deleteCompany
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
            properties:
              acsTok:
                type: string
                description: Access token obtain via '/signin' call
                maxLength: 256
      responses:
        '200':
          description: Successful operation.
          schema:
            $ref: '#/definitions/Ok'
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /company/token/reset:
    post:
      tags:
        - Companies
      summary: Resets company probe authentication token.
      description: >-
        Sets and returns new company probe authentication token.
        Administrative privileges required for resetting company token.
      operationId: resetCompanyToken
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
            properties:
              acsTok:
                type: string
                description: Access token obtain via '/signin' call
                maxLength: 256
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - token
            properties:
              status:
                type: string
                description: Status code of this operation
                enum:
                  - API_OK
              token:
                type: string
                description: Newly reset company probes authentication token
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /feedback/add:
    post:
      tags:
        - Feedbacks
      summary: Adds feedback.
      description: Adds feedback for processed user request.
      operationId: addFeedback
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
              - srvReqId
              - score
            properties:
              acsTok:
                maxLength: 256
                description: Access token obtain via '/signin' call
                type: string
              userId:
                description: User ID.
                type: integer
                format: int64
              userExtId:
                maxLength: 64
                description: External user ID. Note user with given ID will be created if missing
                type: string
              srvReqId:
                maxLength: 64
                description: Server request ID
                type: string
              score:
                description: Score. Valid range is between 0 and 1, inclusive
                type: number
                format: double
              comment:
                maxLength: 1024
                description: Optional feedback comment
                type: string
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - id
            properties:
              status:
                type: string
                description: Status code of this operation
                enum:
                  - API_OK
              id:
                type: integer
                format: int64
                description: ID of the newly created feedback record
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /feedback/delete:
    post:
      tags:
        - Feedbacks
      summary: Deletes feedback.
      description: >-
        Deletes feedback for given record ID.
        Administrative privileges required for deleting feedback from other users.
      operationId: deleteFeedback
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
              - id
            properties:
              acsTok:
                maxLength: 256
                description: Access token obtain via '/signin' call
                type: string
              id:
                description: Feedback record ID to delete.
                type: integer
                format: int64
      responses:
        '200':
          description: Successful operation.
          schema:
            $ref: '#/definitions/Ok'
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /feedback/all:
    post:
      tags:
        - Feedbacks
      summary: Gets feedback.
      description:  >-
        Gets all request feedback records.
        Administrative privileges required for getting feedback from other users.
      operationId: getFeedbacks
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
            properties:
              acsTok:
                maxLength: 256
                description: Access token obtain via '/signin' call
                type: string
              usrId:
                type: integer
                format: int64
                description: >-
                  ID of the user to get feedback records for. Optional, caller user ID used by default.
                  Getting feedback for other users requires administrative privileges. If
                  both user ID and external 'on-behalf-of' user ID are provided they have to point to the
                  same NLPCraft user.
              usrExtId:
                type: string
                description: >-
                  External 'on-behalf-of' ID of the user to get feedback records for. Optional, caller
                  user ID used by default. Getting feedback for other users from the same company requires
                  administrative privileges. If both user ID and external 'on-behalf-of' user ID are provided
                  they have to point to the same NLPCraft user. Note that if only external 'on-behalf-of'
                  user ID is provided and such user doesn't yet exist in NLPCraft - it will be created with this ID.
                maxLength: 64
              srvReqId:
                maxLength: 256
                description: Server request ID
                type: string
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - feedbacks
            properties:
              status:
                type: string
                description: Status code of this operation
                enum:
                  - API_OK
              feedbacks:
                type: array
                items:
                  type: object
                  required:
                    - id
                    - srvReqId
                    - usrId
                    - score
                    - createTstamp
                  properties:
                    id:
                      description: Feedback ID
                      type: integer
                      format: int64
                    srvReqId:
                      description: Server request ID
                      type: string
                    usrId:
                      description: User ID
                      type: integer
                      format: int64
                    score:
                      description: Feedback score
                      type: number
                      format: double
                    comment:
                      description: Feedback comment
                      type: string
                    createTstamp:
                      type: integer
                      format: int64
                      description: Creation UTC/GMT timestamp of the request
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /signin:
    post:
      tags:
        - Authentication
      summary: Signs in and obtains new access token.
      description: >-
        Accepts user's email and password and returns a new access token
        that should be used in all subsequent API calls. An access token can
        expire or be invalidated on the server side and this call should be used
        to obtain it again in such cases.
      operationId: signIn
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - email
              - passwd
            properties:
              email:
                maxLength: 64
                description: User sign in email.
                type: string
              passwd:
                maxLength: 64
                description: User password.
                type: string
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - acsTok
            properties:
              status:
                type: string
                description: Status code of this operation
                enum:
                  - API_OK
              acsTok:
                type: string
                description: >-
                  Temporary (session) access token that should be used for
                  further REST calls
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /signout:
    post:
      tags:
        - Authentication
      summary: Signs out and releases access token.
      description: >-
        Releases previously obtained access token. After this call given access
        token is no longer valid for authentication.
      operationId: signOut
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
            properties:
              acsTok:
                maxLength: 256
                description: Previously obtained access token to release.
                type: string
      responses:
        '200':
          description: Successful operation.
          schema:
            $ref: '#/definitions/Ok'
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /probe/all:
    post:
      tags:
        - Data Probes
      summary: Gets all probes.
      description: >-
        Gets metadata for all active (currently connected) probes. Administrative privileges required.
      operationId: getAllProbes
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
            properties:
              acsTok:
                maxLength: 256
                description: Access token obtain via '/signin' call
                type: string
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - probes
            properties:
              status:
                type: string
                description: Status code of this operation
                enum:
                  - API_OK
              probes:
                type: array
                items:
                  type: object
                  required:
                    - probeToken
                    - probeId
                    - probeGuid
                    - probeApiVersion
                    - probeApiDate
                    - osVersion
                    - osName
                    - osArch
                    - startTstamp
                    - tmzId
                    - tmzAbbr
                    - tmzName
                    - userName
                    - javaVersion
                    - javaVendor
                    - hostName
                    - hostAddr
                    - macAddr
                    - models
                  properties:
                    probeToken:
                      description: Probe token
                      type: string
                    probeId:
                      description: Probe ID (user defined ID)
                      type: string
                    probeGuid:
                      description: Probe GUID (globally unique internal ID)
                      type: string
                    probeApiVersion:
                      description: Probe API version
                      type: string
                    probeApiDate:
                      description: Probe API date
                      type: string
                    osVersion:
                      description: OS version
                      type: string
                    osName:
                      description: OS name
                      type: string
                    osArch:
                      description: OS architecture
                      type: string
                    startTstamp:
                      description: Start time in UTC.
                      type: integer
                      format: int64
                    tmzId:
                      description: Timezone ID
                      type: string
                    tmzAbbr:
                      description: Timezone abbreviation
                      type: string
                    tmzName:
                      description: Timezone name
                      type: string
                    userName:
                      description: User name
                      type: string
                    javaVersion:
                      description: Java version
                      type: string
                    javaVendor:
                      description: Java vendor
                      type: string
                    hostName:
                      description: Host name
                      type: string
                    hostAddr:
                      description: Host address
                      type: string
                    macAddr:
                      description: MAC address
                      type: string
                    models:
                      description: Models
                      type: array
                      items:
                        type: object
                        required:
                          - id
                          - name
                          - version
                        properties:
                          id:
                            description: Model ID (unique, immutable ID)
                            type: string
                          name:
                            description: Model name (descriptive name of this model)
                            type: string
                          version:
                            description: Model version
                            type: string
                          enabledBuiltInTokens:
                            description: Built-in tokens enabled (requested) for this data model
                            type: array
                            items:
                              type: string
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
definitions:
  Ok:
    type: object
    required:
      - status
    properties:
      status:
        type: string
        description: Status code of this operation
        enum:
          - API_OK
  Error:
    type: object
    required:
      - status
    properties:
      status:
        type: string
        description: Status code of this error
        enum:
          - NC_INVALID_ACCESS_TOKEN
          - NC_SIGNIN_FAILURE
          - NC_NOT_IMPLEMENTED
          - NC_INVALID_FIELD
          - NC_ADMIN_REQUIRED
          - NC_INVALID_OPERATION
          - NC_ERROR
      reason:
        type: string
        description: Reason for this error