#
# 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 <a href="https://nlpcraft.apache.org">Apache NLPCraft</a> - an open source library for
    adding Natural Language Interface to any applications. For Data Model APIs see
    <a href="https://nlpcraft.apache.org/apis/latest/index.html">Javadoc</a> documentation.
  version: 0.9.0
  title: Apache NLPCraft API
host: localhost:8081
basePath: /api/v1
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/json
tags:
  - name: Authentication
    description: >-
      Signing in, singing out and password reset.
  - name: Asking
    description: >-
      Asking questions, checking results, clearing context.
  - name: User
    description: >-
      Managing users.
  - name: Company
    description: >-
      Managing companies.
  - name: Feedback
    description: >-
      Managing feedback.
  - name: Probe
    description: >-
      Managing data probes.
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: >-
                  <em>Optional.</em> 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: >-
                  <em>Optional.</em> 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: >-
                  <em>Optional.</em> 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: >-
                  <em>Optional.</em> 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'
  /health:
    get:
      tags:
        - Tools
      summary: Health ping.
      description: >-
        Pings server for HTTP 200 code.
      operationId: health
      responses:
        '200':
          description: Successful operation.
          schema:
            $ref: '#/definitions/Ok'
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /model/sugsyn:
    post:
      tags:
        - Tools
      summary: Runs model synonym suggestion tool.
      description: >-
        Runs model synonym suggestion tool that is based on BERT models and uses @NCIntentSample or @NCIntentSampleRef annotations.
        Administrative privileges required.
      operationId: sugsyn
      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: ID of the model to run synonym suggestion on.
              minScore:
                type: number
                format: double
                description: >-
                  <em>Optional.</em> Minimal score to include into the result (from 0 to 1, default is 0).
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - result
            properties:
              status:
                type: string
                description: Status code of this operation.
                enum:
                  - API_OK
              result:
                type: object
                description: Synonym suggestion result.

        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /model/syns:
    post:
      tags:
        - Tools
      summary: Gets model element expanded synonyms and values.
      description: >-
        Gets model element expanded synonyms and values.
        Administrative privileges required.
      operationId: syns
      parameters:
        - in: body
          name: Payload body
          description: JSON request.
          required: true
          schema:
            type: object
            required:
              - acsTok
              - mdlId
              - elmId
            properties:
              acsTok:
                type: string
                description: Access token obtain via '/signin' call.
                maxLength: 256
              mdlId:
                type: string
                maxLength: 32
                description: ID of the model to run get elements synonyms and values.
              elmId:
                type: string
                maxLength: 64
                description: ID of the model element to get its synonyms and values.
              pattern :
                type: string
                maxLength: 256
                description: Optional JDK-compatible regex to filter returned synonyms on.
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - synonyms
              - values
              - synonymsExp
              - valuesExp
            properties:
              status:
                type: string
                description: Status code of this operation.
                enum:
                  - API_OK
              synonyms:
                type: object
                description: List of individual synomyms as they are specified in the model.
              synonymsExp:
                type: object
                description: List of expanded synomyms as the model uses them (before stemmatization).
              values:
                type: object
                description: >-
                  Map of element values, if any, as they are specified in the model.
                  Map key is the value name.
                  Map value is a list of synonyms for that value.
                  Empty if element doesn't have values.
              valuesExp:
                type: object
                description: >-
                  Map of element values, if any, as the model uses them (before stemmatization).
                  Map key is the value name.
                  Map value is a list of expanded
                  synonyms for that value.
                  Empty if element doesn't have values.
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /model/info:
    post:
      tags:
        - Tools
      summary: Gets model information.
      description: >-
        Gets model configuration properties and elements.
        Administrative privileges required.
      operationId: syns
      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: ID of the model to get information for.
      responses:
        '200':
          description: Successful operation.
          schema:
            type: object
            required:
              - status
              - model
            properties:
              status:
                type: string
                description: Status code of this operation.
                enum:
                  - API_OK
              model:
                type: object
                description: Object representing model configuration properties and elements.
        '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: >-
                  <em>Optional.</em> 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: >-
                  <em>Optional.</em> 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: >-
                  <em>Optional.</em> 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: >-
                  <em>Optional.</em> 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.
                    intentId:
                      type: string
                      description: ID of the intent.
                    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 (<code>QRY_READY</code> indicates that
                        the result - successful or not - is ready).
                      enum:
                        - QRY_ENLISTED
                        - <code>QRY_READY</code>
                    resType:
                      type: string
                      description: >-
                        Optional result type if returned by model (provided only
                        if status is <code>QRY_READY</code> 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 <code>QRY_READY</code> and processing was
                        not rejected or terminated due to an exception).
                    resMeta:
                      type: object
                      description: >-
                        Optional result metadata as JSON object (provided only if status is
                        <code>QRY_READY</code> 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 <code>QRY_READY</code> 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: >-
                  <em>Optional.</em> 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: >-
                  <em>Optional.</em> 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: >-
                  <em>Optional.</em> 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: >-
                  <em>Optional.</em> 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: >-
                  <em>Optional.</em> 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: >-
                  <em>Optional.</em> Additional user-defined JSON data to be passed along with the request with maximum
                  JSON length of 512000 bytes.
              enableLog:
                description: >-
                  <em>Optional.</em> 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: >-
                  <em>Optional.</em> 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: >-
                  <em>Optional.</em> 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: >-
                  <em>Optional.</em> Additional sentence JSON data with maximum JSON length of 512000 bytes.
              enableLog:
                description: >-
                  <em>Optional.</em> 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.
                  intentId:
                    type: string
                    description: ID of the intent.
                  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 (<code>QRY_READY</code> indicates that
                      result - error or ok - is ready).
                    enum:
                      - QRY_ENLISTED
                      - <code>QRY_READY</code>
                  resType:
                    type: string
                    description: >-
                      Optional result type if returned by model (provided only
                      if status is <code>QRY_READY</code> 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 <code>QRY_READY</code> and processing was
                      not rejected or terminated due to an exception).
                  resMeta:
                    type: object
                    description: >-
                      Optional meta JSON object. TODO:
                  error:
                    type: string
                    description: >-
                      Optional error if returned by model (provided only if
                      status is <code>QRY_READY</code> 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:
        - User
      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: >-
                  <em>Optional.</em> 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.
              usrExtId:
                type: string
                description: >-
                  <em>Optional.</em> 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.
                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
              usrExtId:
                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/all:
    post:
      tags:
        - User
      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
              - User
            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
                    usrExtId:
                      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:
        - User
      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: >-
                  <em>Optional.</em> 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: <em>Optional.</em> User avatar URL.
                maxLength: 512000
              properties:
                type: object
                description: <em>Optional.</em> Additional user properties with maximum JSON length of 512000 bytes.
                additionalProperties:
                  type: string
      responses:
        '200':
          description: Successful operation.
          schema:
            $ref: '#/definitions/Ok'
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /user/delete:
    post:
      tags:
        - User
      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: >-
                  <em>Optional.</em> 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
              usrExtId:
                maxLength: 64
                description: >-
                  <em>Optional.</em> 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:
        - User
      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: >-
                  <em>Optional.</em> 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:
        - User
      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: >-
                  <em>Optional.</em> 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:
        - User
      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: <em>Optional.</em> User avatar URL.
                maxLength: 512000
              isAdmin:
                type: boolean
                description: Admin flag.
              properties:
                type: object
                description: <em>Optional.</em> Additional user properties with maximum JSON length of 512000 bytes.
                additionalProperties:
                  type: string
              usrExtId:
                type: string
                description: <em>Optional.</em> User external 'on-behalf-of' ID. If this field defined, method tries to find and update existing 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:
        - Company
      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
              properties:
                type: object
                description: Additional company properties.
                additionalProperties:
                  type: string
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /company/add:
    post:
      tags:
        - Company
      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: <em>Optional.</em> Company website address.
                maxLength: 256
              country:
                type: string
                description: <em>Optional.</em> Company country.
                maxLength: 32
              region:
                type: string
                description: <em>Optional.</em> Company region.
                maxLength: 512
              city:
                type: string
                description: <em>Optional.</em> Company city.
                maxLength: 512
              address:
                type: string
                description: <em>Optional.</em> Company address.
                maxLength: 512
              postalCode:
                type: string
                description: <em>Optional.</em> 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: <em>Optional.</em> Admin user avatar URL.
                maxLength: 512000
              properties:
                type: object
                description: <em>Optional.</em> Additional company properties with maximum JSON length of 512000 bytes.
                additionalProperties:
                  type: string
      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:
        - Company
      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: <em>Optional.</em> Company website address.
                maxLength: 256
              country:
                type: string
                description: <em>Optional.</em> Company country.
                maxLength: 32
              region:
                type: string
                description: <em>Optional.</em> Company region.
                maxLength: 512
              city:
                type: string
                description: <em>Optional.</em> Company city.
                maxLength: 512
              address:
                type: string
                description: <em>Optional.</em> Company address.
                maxLength: 512
              postalCode:
                type: string
                description: <em>Optional.</em> Company postal code.
                maxLength: 512
              properties:
                type: object
                description: <em>Optional.</em> Additional company properties with maximum JSON length of 512000 bytes.
                additionalProperties:
                  type: string
      responses:
        '200':
          description: Successful operation.
          schema:
            $ref: '#/definitions/Ok'
        '400':
          description: Failed operation.
          schema:
            $ref: '#/definitions/Error'
  /company/delete:
    post:
      tags:
        - Company
      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:
        - Company
      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:
        - Feedback
      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
              usrId:
                description: <em>Optional.</em> User ID.
                type: integer
                format: int64
              usrExtId:
                maxLength: 64
                description: <em>Optional.</em> 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: <em>Optional.</em> 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:
        - Feedback
      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:
        - Feedback
      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: >-
                  <em>Optional.</em> 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: >-
                  <em>Optional.</em> 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: <em>Optional.</em> 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:
        - Probe
      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.