SysAid Copilot REST API Guide

Middleware

JSON Parser

The JSON parser is used as a middleware to parse the body of incoming requests.

URL Rewriter

A middleware that rewrites the URL of the incoming request if it begins with SPACES_UI_PREFIX or SPACES_API_PREFIX.

Login Middleware

The login middleware provides authentication and organization mapping functionality for your application. It uses cookies and header information from the request to authenticate the user and assign them to the correct organization.

The login middleware expects the following inputs:

1. Cookies: Two cookies, JSESSIONID and SERVERID, are expected in the request headers. These cookies are used to identify and authenticate the user. Absence of either of these cookies will result in an UnauthorizedError.

2. Header: The middleware also checks for the x-sysaid-hostname header in the request. This header should contain the hostname of the SysAid server used for authentication. Absence of this header will also result in an UnauthorizedError.

The login middleware performs the following actions:

1. Authentication: The middleware uses the cookies to authenticate the user. If the user is not authenticated, an UnauthorizedError is thrown.

2. Organization Mapping: The middleware uses the x-sysaid-hostname header to map the user to the correct organization. If the user is not mapped to an organization, an UnauthorizedError is thrown.

3. User Details: The middleware fetches the user details from the SysAid server and adds them to the request object that is passed to the endpoints.

Endpoints

All endpoints are protected by the login middleware unless otherwise specified.

GET /api/health

Returns the status of the server. This endpoint is used by the load balancer to check the health of the server. This endpoint is not protected by the login middleware.

GET /api/kobi

Return a few details on the server. This endpoint is not protected by the login middleware.

GET /api/stream/:sid

Streams chat for a given sid (Session ID). This endpoint is not protected by the login middleware. Howeever it protected by the sid parameter, which is a random string generated by the server that is passed to the client when the chat is initiated using the /api/chat endpoint.

POST /api/login

Logs in the user and returns the user details.

The endpoint expects a request object with cookies and headers as required by the login middleware (please refer to the login middleware documentation for more details).

Upon successful authentication, the endpoint returns a JSON object with the following properties:

• status: A string indicating the status of the operation. On successful login, it will be "ok".

• message: A string providing additional information about the operation. On successful login, it will be "Login successful".

• fullname: A string containing the full name of the authenticated user.

• isAdministrator: A boolean indicating whether the user has administrator privileges.

• orgConf: The configuration object associated with the user’s organization.

POST /api/org

Updates an organization’s configuration. Requires a JSON body with the organization’s details. Only accessible by admin users.

The endpoint expects a request object with the following properties:

• orgName: (string) The new name for the organization. If not provided, the existing organization name is kept.

• logoURL: (string) The new URL for the organization’s logo. If not provided, the existing logo URL is kept.

• assistantName: (string) The new name for the organization’s assistant. If not provided, the existing assistant name is kept.

• chatSystemMessage: (string) The new system message for the organization’s chat. If not provided, the existing system message is kept.

• chatbotName: (string) The new name for the organization’s chatbot. If not provided, the existing chatbot name is kept.

• userRole: (string) The new role for the organization’s user. If not provided, the existing user role is kept.

• srTimeRangeValue: (integer) The new value for the service request time range. It should be an integer between 1 and 100. If not provided, the existing value is kept.

• srTimeRangeUnit: (string) The new unit for the service request time range. It should be one of the following: ‘weeks’, ‘months’, ‘years’. If not provided, the existing unit is kept.

• welcomeMessage: (string) The new welcome message for the organization. If not provided, the existing welcome message is kept.

• starterMessage: (string) The new starter message for the organization. If not provided, the existing starter message is kept.

• errorMessage: (string) The new error message for the organization. If not provided, the existing error message is kept.

Upon successful update, the endpoint returns a JSON object with the following properties:

• status: A string indicating the status of the operation. On successful update, it will be “ok”.

• message: A string providing additional information about the operation. On successful update, it will be “Org {org.name} updated”.

If an error occurs, the endpoint returns a JSON object with the following properties:

• status: A string indicating the status of the operation. On error, it will be “error”.

• message: A string providing additional information about the operation. On error, it will be the error message.

Please note that the endpoint requires the request to be made by an admin user. If a non-admin user attempts to update the organization’s details, an error will be thrown.

GET /api/longOperation/:id

This endpoint retrieves the status of a long-running operation. It requires a unique identifier (ID) for the specific operation.

URL Parameters

• id (required): The unique identifier of the long operation. Must be a valid UUID.

Responses

• 200 OK: If the request is successful, the response will be in JSON format containing the status of the operation, an optional message, and any additional data related to the operation.

• status: The current status of the long operation.

• message: An optional message providing additional information about the operation.

• Additional data (if available) specific to the long operation.

• 400 Bad Request: Returned if the request is invalid, typically due to an invalid ID format. The response will be a plain text message ‘Invalid request’.

• 404 Not Found: Returned if there is no long operation associated with the provided ID. The response will be a plain text message indicating the operation was not found.

• 500 Internal Server Error: Returned in case of an internal server error. The response will be a plain text message ‘Internal error’.

POST /api/chat

Initiates a chat. Requires a JSON body with the chat details.

Request Body:

• chatuid: (string) A unique identifier for the chat thread. If not provided, a new chatuid will be generated.

• text: (string) The chat message text. If not provided, an error is thrown.

• stream: (boolean) A flag indicating whether the chat should be streamed. If not provided, defaults to false.

Response:

Depending on the scenario, the endpoint will return one of the following responses:

1. If the chat is successfully initiated and a response is generated:

{

"status": "ok",

"response": "{chat response}",

"chatuid": "{chatuid}",

"system": "{system text info}"

}

Note: The system field will only be included in the response if the user initiating the chat is an admin.

2. If the chat is successfully initiated but no response is generated:

{

"status": "error",

"error": "No Answer",

"chatuid": "{chatuid}"

}

3. If the chat is successfully initiated and is being streamed:

{

"status": "stream",

"sid": "{sid}",

"chatuid": "{chatuid}"

}

4. If an error occurs while initiating the chat:

{

"status": "error",

"error": "{error message}"

}

The {chat response}, {system text info}, {chatuid}, {sid}, and {error message} placeholders in the above examples will be replaced with actual values in the real responses.

POST /api/chat/fromEmail

This endpoint initiates a chat session based on a service request (SR) in SysAid, utilizing the email information associated with the SR.

Request Body Parameters

• accountId (required): The account identifier. Must be a string.

• srId (required): The service request identifier. Must be numeric.

Responses

• 200 OK: Indicates the chat initiation was successful. The response will be in JSON format containing the status and a message.

• status: Indicates the success of the chat initiation.

• response: A message stating “Chat started”.

• Error Response: In case of an error, the response will be in JSON format containing the status ‘error’ and the error message.

• status: Indicates an error occurred.

• error: A descriptive message about the error.

Sample Request

POST /api/chat/fromEmail

{

"accountId": "exampleAccountId",

"srId": 12345

}

Sample Response

{

"status": "ok",

"response": "Chat started"

}

Implementation Details

• The endpoint return a 200 OK response immediately after initiating the chat. The chat will continue in the background.

• When the chat is completed the code evaluate the chat response quality an relevanc and update SysAid accordingly using the /api/v1/srnotification/sendainotification endpoint.

GET /api/chat/stream/:sid

This endpoint retrieves the current chat messages from a specific chat stream identified by the stream ID (sid).

URL Parameters

• sid (required): The stream ID. It is used to identify the specific chat stream from which messages are to be retrieved.

Responses

• 200 OK: Indicates that messages were successfully retrieved. The response will be in JSON format containing the status and an array of messages.

• status: Indicates the success of the message retrieval.

• messages: An array of chat messages. It can be an empty array if there are no messages in the queue.

• 400 Bad Request: Returned if there is an error in retrieving messages. The response will be a plain text message describing the error.

Sample Request

GET /api/chat/stream/12345

Sample Response

{

"status": "ok",

"messages": [

// Array of chat messages

]

}

POST /api/chat/rate

This endpoint allows a user to rate a chat answer. It is used to provide feedback on the effectiveness and relevance of a particular chat response.

Request Body Parameters

• chatuid (required): The unique identifier of the chat session. Must be a valid UUID.

• index (required): The index of the chat message being rated.

• rate (required): The user’s rating for the chat message. Valid values are -1, 0, or 1.

Responses

• 200 OK: Indicates that the rating was successfully recorded. The response will be in JSON format containing the status ‘ok’.

• Error Response: In case of an error, the response will be in JSON format containing the status ‘error’ and the error message.

• status: Indicates an error occurred.

• error: A descriptive message about the error.

Sample Request

POST /api/chat/rate

{

"chatuid": "123e4567-e89b-12d3-a456-426614174000",

"index": 5,

"rate": 1

}

Sample Response

{

"status": "ok"

}

GET /api/chat/:chatuid

Retrieves the chat thread for a given chatuid (Chat Unique ID).

Path Parameters:

• chatuid: (string) The unique identifier for the chat. This parameter is required.

Response:

The endpoint will return one of the following responses:

1. If the chat is found and the user has permission to view it:

{

"status": "ok",

"messages": [

{

"role": "{role}",

"content": "{content}",

"createdAt": "{createdAt}",

"info": "{info}"

},

...

]

}

Note: The info field in each message will only be included if the user requesting the chat is an admin.

The {role}, {content}, {createdAt}, and {info} placeholders will be replaced with actual values in the real response.

2. If the chat is not found, the chatuid is not provided, the user is not logged in, or the user does not have permission to view the chat:

{

"status": "error",

"error": "{error message}"

}

The {error message} placeholder will be replaced with an actual error message in the real response. Possible error messages include “User not logged in”, “chatuid not provided”, “Chat not found”, and “Chat belongs to another user”.

POST /api/chat/resolve

This endpoint is used to close the service request (SR) associated with a specific chat session, effectively resolving the chat.

Request Body Parameters

• chatuid (required): The unique identifier of the chat session. Must be a valid UUID.

Responses

• 200 OK: Indicates that the chat session was successfully resolved. The response will be in JSON format containing the status ‘ok’.

• Error Response: In case of an error, the response will be in JSON format containing the status ‘error’ and the error message.

• status: Indicates an error occurred.

• error: A descriptive message about the error.

Sample Request

POST /api/chat/resolve

{

"chatuid": "123e4567-e89b-12d3-a456-426614174000"

}

DELETE /api/chat/:chatuid

This endpoint deletes a chat identified by its unique chat session ID (chatuid). It is used to remove all records and messages associated with a specific chat.

URL Parameters

• chatuid (required): The unique identifier of the chat session. It is used to specify the chat to be deleted.

Responses

• 200 OK: Indicates that the chat was successfully deleted. The response will be in JSON format containing the status ‘ok’.

• Error Response: In case of an error, the response will be in JSON format containing the status ‘error’ and the error message.

• status: Indicates an error occurred.

• error: A descriptive message about the error.

GET /api/chat

Retrieves all recent chat threads for a specific user. If the user is an admin, they can retrieve chats for any user by specifying a username query parameter.

Query Parameters:

• username: (string) The username for which to retrieve chat threads. This parameter is optional and only available to admin users. If not provided or the user is not an admin, the endpoint retrieves chats for the logged-in user.

Response:

The endpoint will return one of the following responses:

1. If the chats are found:

{

"status": "ok",

"chats": [

{

"chatuid": "{chatuid}",

"summary": "{summary}"

},

...

]

}

Note: The {chatuid} and {summary} placeholders will be replaced with actual values in the real response. Each object in the chats array represents a chat thread.

2. If the user is not logged in or an error occurs during retrieval:

{

"status": "error",

"error": "{error message}"

}

The {error message} placeholder will be replaced with an actual error message in the real response. Possible error messages include “User not logged in” and specific error messages related to the retrieval process.

PUT /api/sr/:chatuid

This endpoint creates a service request (SR) from a chat transcript, using the chat session identified by the chat UID (chatuid). It is designed to escalate a chat conversation to a formal service request in SysAid.

URL Parameters

• chatuid (required): The unique identifier of the chat session. It is used to specify the chat session from which the service request will be created.

Responses

• 200 OK: Indicates that the process of creating a service request is in progress. The response will be in JSON format containing the status ‘in-progress’ and the ID of the long operation.

• status: The current status of the operation (‘in-progress’).

• longOperationId: The ID of the long-running operation.

• Error Response: In case of an error, the response will be in JSON format containing the status ‘error’ and the error message.

• status: Indicates an error occurred.

• error: A descriptive message about the error.

Sample Request

PUT /api/sr/123e4567-e89b-12d3-a456-426614174000

Sample Response

{

"status": "in-progress",

"longOperationId": "456f7890-g12h-34i5-j678-90kl12345678"

}

Dataset API Endpoints

1. GET /api/dataset

Lists all datasets available.

Response:

The endpoint will return one of the following responses:

1. If the datasets are found:

{

"status": "ok",

"datasets": [

{

...  (dataset  details)  ...

},

...

]

}

2. In case of an error:

{

"status": "error",

"error": "Failed to retrieve datasets"

}

2. PUT /api/dataset

Creates a new dataset.

Body:

• title: (string) Title of the dataset.

• datasetType: (number) Type of the dataset.

• enabled: (boolean) Indicates if the dataset is enabled.

• maxDistance: (number) Maximum distance parameter for the dataset.

• gueranteeItems: (number) Guaranteed items count.

• configuration: (string) Configuration JSON for the dataset.

Response:

1. If the dataset is successfully created:

{

"status": "ok",

"dataset": {

"id": (number)  ID  of  the  newly  created  dataset,

"title": (string)  Title  of  the  dataset,

"datasetType": (number)  Type  of  the  dataset,

"builtIn": (boolean)  Whether  the  dataset  is  built-in  or  not,

"enabled": (boolean)  Whether  the  dataset  is  enabled  or  not,

"maxDistance": (number)  Maximum  distance  parameter  for  the  dataset,

"gueranteeItems": (number)  Guaranteed  items  for  the  dataset,

"configuration": (string)  JSON  string  of  the  dataset  configuration

}

}

2. In case of an error:

{

"status": "error",

"error": "Failed to create dataset"

}

3. POST /api/dataset/{datasetId}

Updates a specific dataset.

Path Parameters:

• datasetId: (number) ID of the dataset to update.

Body:

• title: (string) Updated title of the dataset.

• enabled: (boolean) Indicates if the dataset is enabled.

• maxDistance: (number) Updated maximum distance parameter.

• gueranteeItems: (number) Updated guaranteed items count.

• configuration: (string) Updated configuration JSON.

Response:

The endpoint will return:

{

"status": "ok"

}

Or in case of an error:

{

"status": "error",

"error": "Failed to update dataset"

}

4. GET /api/dataset/{datasetId}

Retrieves a specific dataset.

Path Parameters:

• datasetId: (number) ID of the dataset to retrieve.

Response:

1. If the dataset is found:

{

"status": "ok",

"dataset": {

"id": (number)  ID  of  the  dataset,

"title": (string)  Title  of  the  dataset,

"datasetType": (number)  Type  of  the  dataset,

"builtIn": (boolean)  Whether  the  dataset  is  built-in  or  not,

"enabled": (boolean)  Whether  the  dataset  is  enabled  or  not,

"maxDistance": (number)  Maximum  distance  parameter  for  the  dataset,

"gueranteeItems": (number)  Guaranteed  items  for  the  dataset,

"configuration": (string)  JSON  string  of  the  dataset  configuration

},

"statusSummary": [

{

"status": (number)  Status  code  of  the  dataset  summary,

"count": (number)  Count  of  items  with  the  status,

"caption": (string)  Caption  describing  the  status

}

],

"fetchStatus": {

"lastSucccessfulFetch": (string)  Timestamp  of  the  last  successful  fetch,

"lastFetchAttempt": (string)  Timestamp  of  the  last  fetch  attempt,

"lastFetchError": (string)  Description  of  the  last  fetch  error

}

}

2. In case of an error:

{

"status": "error",

"error": "Failed to retrieve specified dataset"

}

5. DELETE /api/dataset/{datasetId}

Deletes a specific dataset.

Path Parameters:

• datasetId: (number) ID of the dataset to delete.

Response:

The endpoint will return:

{

"status": "ok"

}

Or in case of an error:

{

"status": "error",

"error": "Failed to delete dataset"

}

6. POST /api/dataset/:datasetid/query

Queries records from a specific dataset.

Path Parameters:

• datasetid: (number) ID of the dataset to query.

Body:

• limit: (number, optional) Number of records to return. Default is 100. Valid range is 1-1000.

• offset: (number, optional) Number of records to skip before returning results. Default is 0.

• order: (array, optional) An array of arrays to define the order of the records. The inner arrays should have 2 elements: field and order direction (either ‘ASC’ or ‘DESC’). Valid fields are id, createdAt, and updatedAt. Default order is [[‘id’, ‘DESC’]].

• text: (string, optional) Searches for records with a text field containing the given value.

• status: (string, optional) Filters records by status.

• resourceLocator: (string, optional) Filters records by resource locator.

Request Prerequisites:

• User must be logged in.

• User must be an admin.

Response:

1. If the records are successfully retrieved:

{

"status": "ok",

"total": (number)  Total  number  of  matching  records,

"records": (array)  Array  of  dataset  records  with  fields:  dataset, id,  text,  summary,  status,  resourceLocator,  resourceUpdatedAt,  createdAt,  updatedAt. If the dataset type is Q&A, the records will also include the files isVerifiedAnswer.

"limit": (number)  The  limit  used  in  the  query,

"offset": (number)  The  offset  used  in  the  query

}

2. In case of an error:

{

"status": "error",

"error": (string)  Error  message  describing  the  failure

}

7. PUT /api/dataset/:datasetid

Adds a new dataset record.

Path Parameters:

• datasetid: (number) ID of the dataset where the record will be added.

Body:

• text: (string) Text for the dataset record. This field is required.

• status: (string, optional) Status of the dataset record. If not provided during creation, it will default to FETCHED.

• summary: (string, optional) Summary of the dataset record.

• resourceLocator: (string, optional) Resource locator for the dataset record.

• resourceUpdatedAt: (string, optional) Timestamp when the resource was last updated. Must be in a valid date format.

Request Prerequisites:

• User must be logged in.

• User must be an admin.

Response:

1. If the record is successfully added:

{

"status": "ok",

"record": {

...  (details  of  the  added  dataset  record)  ...

}

}

2. In case of an error:

{

"status": "error",

"error": (string)  Error  message  describing  the  failure

}

8. POST /api/dataset/:datasetid/:id

Updates an existing dataset record.

Path Parameters:

• datasetid: (number) ID of the dataset containing the record to be updated.

• id: (number) ID of the dataset record to be updated.

Body:

• text: (string) Text for the dataset record. This field is required.

• status: (string, optional) Updated status of the dataset record.

• summary: (string, optional) Updated summary of the dataset record.

• resourceLocator: (string, optional) Updated resource locator for the dataset record.

• resourceUpdatedAt: (string, optional) Updated timestamp when the resource was last updated. Must be in a valid date format.

Request Prerequisites:

• User must be logged in.

• User must be an admin.

Response:

1. If the record is successfully updated:

{

"status": "ok",

"record": {

...  (details  of  the  updated  dataset  record)  ...

}

}

2. In case of an error:

{

"status": "error",

"error": (string)  Error  message  describing  the  failure

}

9. DELETE /api/dataset/:datasetid/:id

Deletes an existing dataset record and its associated embeddings in Redis.

Path Parameters:

• datasetid: (number) ID of the dataset containing the record to be deleted.

• id: (number) ID of the dataset record to be deleted.

Request Prerequisites:

• User must be logged in.

• User must be an admin.

Response:

1. If the record is successfully deleted:

{

"status": "ok"

}

2. In case of an error:

{

"status": "error",

"error": (string)  Error  message  describing  the  failure

}

Document endpoints

POST /api/document/:datasetid/query

This endpoint queries documents within a specific dataset, identified by the dataset ID (datasetid). It allows for various filtering and ordering options to retrieve a customized set of dataset items.

URL Parameters

• datasetid (required): The dataset ID. Must be an integer. It specifies the dataset to be queried.

Request Body Parameters

• limit (optional): An integer specifying the maximum number of items to return. Defaults to 100 if not specified.

• offset (optional): An integer specifying the offset from which to start returning items. Defaults to 0 if not specified.

• order (optional): An array specifying the order of the items. Each element should be an array of two elements, where the first is the field name and the second is the order direction (ASC or DESC).

• itemType (optional): An integer to filter items by their type.

• name (optional): A string to filter items by their name, using a LIKE pattern match.

• status (optional): An integer to filter items by their status.

• resourceLocator (optional): A string to filter items by their resource locator.

Responses

• 200 OK: Indicates successful retrieval of dataset items. The response will be in JSON format containing the status ‘ok’, dataset ID, total number of items, and an array of items.

• status: The status of the request.

• dataset: The dataset ID.

• total: The total number of items that match the query.

• items: An array of dataset items, each with selected fields.

• Error Response: In case of an error, the response will be in JSON format containing the status ‘error’ and the error message.

• status: Indicates an error occurred.

• error: A descriptive message about the error.

Sample Request

POST /api/document/123/query

{

"limit": 50,

"offset": 10,

"order": [["createdAt", "DESC"]],

"name": "Sample Document",

"status": 1,

"resourceLocator": "http://example.com/resource"

}

Sample Response

{

"status": "ok",

"dataset": 123,

"total": 200,

"items": [

// Array of dataset items

]

}

PUT /api/document/:datasetid

This endpoint creates a new dataset item within a specified dataset. It is primarily used to add a placeholder to a new documents to a dataset, which will be upload later by the upload endpoint.
If the itemType is URLMaster, the endpoint will start the process of crawling the URL and sub URLs and extracting the text from them.

URL Parameters

• datasetid (required): The dataset ID. Must be an integer. It specifies the dataset in which the new document will be created.

Request Body Parameters

• name (required): The name of the dataset item. Must be a string.

• itemType (required): The type of the dataset item. Valid values are integers representing specific types. Possible values:

  • 1: PDFDocument

  • 2: WordDocument

  • 3: CSVDocument

  • 4: URLMaster

• status (optional): The current status of the dataset item. Valid values are integers representing specific statuses. Possible values:

  • 0: PROCESSING

  • 1: COMPLETED

  • 2: FAILED

  • 3: UPLOADING Defaults to PROCESSING if not specified.

• statusMessage (optional): A message describing the current status of the dataset item. Defaults to “Processing document” if not specified.

• resourceLocator (optional): A string representing the location of the dataset item’s resource. Defaults to the name of the item if not specified. For a URLMaster document, it should be the URL of the master document. If not specified the resourceLocator will be the name of the item.

• resourceUpdatedAt (optional): The date and time when the resource was last updated. Defaults to the current date and time if not specified.

• maxLevels (optional): The maximum number of levels to crawl when processing a URLMaster document. Defaults to 1 if not specified.

Responses

• 200 OK: Indicates successful creation of the dataset item. The response will be in JSON format containing the status ‘ok’, dataset ID, the new item’s ID, item type, and status.

• status: The status of the request.

• dataset: The dataset ID.

• id: The ID of the newly created dataset item.

• itemType: The type of the newly created item.

• itemStatus: The status of the newly created item.

• Error Response: In case of an error, the response will be in JSON format containing the status ‘error’ and the error message.

• status: Indicates an error occurred.

• error: A descriptive message about the error.

Sample Request

PUT /api/document/123

{

"name": "Example Document",

"itemType": 1,

"status": 2,

"statusMessage": "Uploading document",

"resourceLocator": "http://example.com/resource",

"resourceUpdatedAt": "2023-04-01T12:00:00Z"

}

PUT /api/document/:datasetid/:id

This endpoint uploads a document to a specific dataset item identified by both dataset ID (datasetid) and item ID (id). It is primarily used to add document content to a previously created dataset item.

URL Parameters

• datasetid (required): The dataset ID. Must be an integer. Specifies the dataset to which the document belongs.

• id (required): The item ID. Must be an integer. Specifies the specific dataset item to which the document is being uploaded.

Query Parameters

• wait (optional): A boolean indicating whether to wait for processing to complete before sending a response. If false, the response is sent immediately after initiating the upload.

Request

• The document to be uploaded should be included in the request as a multipart/form-data under the file key.

Responses

• 200 OK: Indicates successful upload and processing of the document. The response will be in JSON format containing the status ‘ok’, dataset ID, item ID, item type, and current status of the item.

• status: The status of the request.

• dataset: The dataset ID.

• id: The item ID.

• itemType: The type of the uploaded document (e.g., PDFDocument, WordDocument).

• itemStatus: The current status of the item (e.g., PROCESSING, COMPLETED).

• Error Response: In case of an error, the response will be in JSON format containing the status ‘error’ and the error message.

• status: Indicates an error occurred.

• error: A descriptive message about the error.

Sample Request

PUT /api/document/123/456

Content-Type: multipart/form-data;

Content-Disposition: form-data; name="file"; filename="example.pdf"

Sample Response

{

"status": "ok",

"dataset": 123,

"id": 456,

"itemType": 1,

"itemStatus": 2

}

GET /api/document/:datasetid/:id

This endpoint facilitates the downloading of a document from a specific dataset item, identified by both dataset ID (datasetid) and item ID (id). It is designed for admins to retrieve documents stored in the dataset.

URL Parameters

• datasetid (required): The dataset ID. Specifies the dataset from which the document is to be downloaded.

• id (required): The item ID. Specifies the specific dataset item from which the document is to be downloaded.

Responses

• 200 OK: Indicates successful retrieval and download of the document. The document’s content is sent as the response body with appropriate content type and disposition.

• Error Response: In case of an error, the response will be a JSON format containing the status ‘error’ and the error message, with a status code of 400.

• status: Indicates an error occurred.

• error: A descriptive message about the error.

Sample Request

GET /api/document/4/456

DELETE /api/document/:datasetid/:id

This endpoint deletes a specific dataset item, along with all associated records, within a dataset. It is identified by both the dataset ID (datasetid) and item ID (id).

URL Parameters

• datasetid (required): The dataset ID. Must be an integer. Specifies the dataset from which the item will be deleted.

• id (required): The item ID. Must be an integer. Specifies the specific dataset item to be deleted.

Responses

• 200 OK: Indicates successful deletion of the dataset item. The response will be in JSON format containing the status ‘ok’.

• status: The status of the request.

• Error Response: In case of an error, the response will be in JSON format containing the status ‘error’ and the error message.

• status: Indicates an error occurred.

• error: A descriptive message about the error.

Monitor & Fine-tune API Endpoints

POST /api/monitor/query

This endpoint queries chat items for monitoring purposes, offering various filters and ordering options.

Request Body Parameters

• limit (optional): An integer specifying the maximum number of items to return. Defaults to 100 if not specified. The range is between 1 and 1000.

• offset (optional): An integer specifying the offset from which to start returning items. Must be 0 or more.

• order (optional): An array specifying the order of the items. Each element should be an array of two elements, where the first is the field name (e.g., qualityRate, createdAt, verificationIndicator) and the second is the order direction (ASC or DESC).

• text (optional): A string to filter items by their question or answer content.

• verificationIndicator (optional): An integer to filter items by their verification indicator. Must be 0 or more.

Responses

• 200 OK: Indicates successful retrieval of chat monitoring items. The response will be in JSON format containing the status ‘ok’, total number of items, an array of records, and the applied limit and offset.

• status: The status of the request.

• total: The total number of items that match the query.

• records: An array of chat monitoring records.

• limit: The limit used in the query.

• offset: The offset used in the query.

• Error Response: In case of an error, the response will be in JSON format containing the status ‘error’ and the error message.

• status: Indicates an error occurred.

• error: A descriptive message about the error.

Sample Request

POST /api/monitor/query

{

"limit": 50,

"offset": 10,

"order": [["createdAt", "DESC"]],

"text": "example query",

"verificationIndicator": 1

}

PUT /api/monitor/:chatuid/:index

This endpoint updates chat monitoring records based on admin input. It can also modify verified answers datasets associated with the chat monitor.

URL Parameters

• chatuid (required): The unique identifier of the chat session. Must be a UUID.

• index (required): The index of the chat message being updated. Must be an integer, with a minimum value of 0.

Request Body Parameters

• readIndicator (optional): An integer indicating the read status. Must be 0 or higher.

• verifiedAnswerDataset (optional): An integer specifying the ID of the verified answer dataset. Must be 0 or higher.

• verifiedAnswerId (optional): An integer specifying the ID of the verified answer. Must be 0 or higher.

• answer (optional): A string containing the updated answer.

• question (optional): A string containing the updated question.

• verificationIndicator (optional): An integer indicating the verification status. Must be 0 or higher.

Responses

• 200 OK: Indicates successful update of the chat monitoring record. The response will be in JSON format containing the status ‘ok’.

• status: The status of the request.

• Error Response: In case of an error, the response will be in JSON format containing the status ‘error’ and the error message.

• status: Indicates an error occurred.

• error: A descriptive message about the error.

Sample Request

PUT /api/monitor/123e4567-e89b-12d3-a456-426614174000/5

{

"readIndicator": 1,

"verifiedAnswerDataset": 2,

"verifiedAnswerId": 10,

"answer": "Updated answer",

"question": "Updated question",

"verificationIndicator": 1

}

AI Admin assist API Endpoints

GET /summarize/:srid

Returns a summary for a given srid (Service Request ID). This endpoint can only be accessed by an admin user.

Path Parameters:

• srid: (string) The Service Request ID to summarize. If not provided, an error is thrown.

Response:

The endpoint will return one of the following responses:

1. If the summary is successfully generated:

{

"id": "{srid}",

"summary": "{summary}",

"sentiment": "{sentiment}",

"sentimentTextList": ["{text1}", "{text2}", "..."],

"title": "{title}"

}

Note: The {srid}, {summary}, {sentiment}, {text1}, {text2}, …, and {title} placeholders will be replaced with actual values in the real response. sentimentTextList is an array of strings.

2. If the user is not logged in, not an admin, or an error occurs during summarization:

HTTP status 400, with a message: Error in summarizeSR: {error message}

The {error message} placeholder will be replaced with an actual error message in the real response. Possible error messages include “User not logged in”, “User is not admin”, “srid not provided”, and specific error messages related to the summarization process.

POST /feedback

Submits feedback for a given summary. This endpoint can only be accessed by an admin user and requires a JSON body with the feedback details.

Request Body:

The request body should contain the following fields:

• accountId: (string) The ID of the account providing feedback. If not provided, an error is thrown.

• feedback: (string) The feedback text. If not provided, an error is thrown.

• userId: (string) The ID of the user providing feedback. If not provided, an error is thrown.

• srId: (string) The ID of the service request for which feedback is provided. If not provided, an error is thrown.

• summary: (string) The summary text. If not provided, a default message “Summary is not available” will be used.

Response:

The endpoint will return one of the following responses:

1. If the feedback is successfully submitted:

HTTP status 200

2. If the user is not logged in, not an admin, or one of the required fields (accountId, feedback, userId, srId) is not provided:

HTTP status 400, with a message: Missing one of accountId, feedback, userId, srId

3. If an error occurs during feedback submission:

HTTP status 500, with a message: Error in summarizeSRFeedback: {error message}

The {error message} placeholder will be replaced with an actual error message in the real response. Possible error messages include “User not logged in”, “User is not admin”, and specific error messages related to the feedback submission process.

Added endpoint: POST /api/sr/suggest_category_for_text

Body fields:
text - any description
srType - SR type number - 1 - incident, 10 - request, Change - 4, Problem - 6

enum SRType { INCIDENT = 1, CHANGE = 4, PROBLEM = 6, REQUEST = 10, }

Example:

https://spaces96.qa.sysaidit.com/spaces/api/sysai/api/sr/suggest_category_for_text

{
    "text": "VPN error 401. I cant connect. Please help",
    "srType": 1
}

Reponse:

{
    "status": "ok",
    "category": {
        "category_id": 361,
        "problem_type": "Network",
        "problem_sub_type": "VPN",
        "third_level_category": "Issues",
        "module_relevance": 83,
        "first_level_key": 298,
        "second_level_key": 299,
        "third_level_key": 300,
        "incident_template": -1,
        "request_template": -1,
        "srType": 1,
        "similarity": 0.8518417425289576
    },
    "template": -1,
    "srType": 1,
    "title": "VPN Error 401 Connection Issue",
    "updateInfo": []
}