| # |
| # 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.8.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' |
| /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. |
