# API
For integration with external systems (if necessary), Sherpa AI Server offers a set of tools for data exchange via API.
The "API" section serves as a reference for available API methods in Swagger format. This section includes the following tabs:
1. [Key](#id-1.-key-api-key)
2. [Storage](#id-2.-storage)
3. [Log](#id-3.-log)
4. [Accounts](#id-4.-accounts)
5. [AI Server](#id-5.-ai-server)
## 1. Key (API Key)
In this section, the user can see their unique API access key in the Key field. Also, when changing this field, it is necessary to confirm the action by pressing one of the buttons:
(Assignment) - Assign a new key;
 (Refresh) - Refresh the current key.
Below is the information field "Authorization," which is used to provide the access token confirming that the User has the right to perform the requested action.
Example:
“Bearer” — token type,
“Y2Y5M2U3OGUtMDk1ZC00MGNjLTkwNWUtZTYyNjUwM\_\_\_\_\_\_\_” — the token itself, which the server will use to identify the User.
API requests are made with the mandatory transmission of the API Key, which is stored in the Account settings. Detailed examples of requests are provided in the section for each block separately.
Response codes:
## 2. Storage
Allows managing the Storage. The user can create new folders and files, retrieve information about folders and files, update information about folders and files, and delete folders and files.
This page contains tabs with methods:
By clicking on the icon  to the right of the desired method, the corresponding page opens:
### 1. Creating a New Folder
* Endpoint: /api/folders/create
* Method: POST;
* Authorization: required;
* Parameters:
* Name: Name of the new folder;
* Description: Description for the new folder.
* Example:
Request
Response
```json
{
"Name": "New Folder 1",
}
```
[
"guid": "16f94238-ede9-435b-a001-1489b32e7dc2",
]
### 2. Retrieving Information About a Folder by GUID
* Endpoint: /api/folders/read/{guid}
* Method: GET;
* Authorization: required;
* Parameters:
* Guid (required): Guid of the new folder.
* Example:
| Request | Response |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| /api/folders/read/4dd6abf4-daa3-45d0-9347-6780c2b46b0c | `json
{
"id": 1,
"guid": "4dd6abf4-daa3-45d0-9347-6780c2b46b0c",
"name": "Test Folder 1",
"description": "My new test Folder",
"created": "2023-01-29 10:29:25",
"updated": "2023-01-29 10:44:09",
"is_deleted": 0,
"account_id": 1,
}
` |
### 3. Retrieving a List of Folders Associated with GUID
* Endpoint: /api/folders/list
* Method: GET;
* Authorization: required;
* Parameters: none;
* Example:
Request
Response
/api/folders/list
```json
[
{
"id": 1,
"guid": "4dd6abf4-daa3-45d0-9347-6780c2b46b0c",
"name": "Test Folder 1",
"description": "My new test Folder",
"created": "2023-01-29 10:29:25",
"updated": "2023-01-29 10:44:09",
"is_deleted": 0,
"account_id": 1,
},
{
"id": 2,
"guid": "4dd6abf4-daa3-45d0-9347-6780c2b46a3c",
"name": "Test Folder 2",
"description": "My another new test Folder",
"created": "2023-10-05 10:59:41",
"updated": "2023-10-05 10:59:41",
"is_deleted": 0,
"account_id": 1,
}
]
```
### 4. Updating Information About a Folder by GUID
* Endpoint: /api/folders/update
* Method: PUT;
* Authorization: required;
* Parameters:
* Guid (required): Guid of the folder;
* Name: Name of the new folder;
* Description: Description for the new folder.
* Example:
Request
Response
```json
{
"Guid": "554ab883-1f82-48e1-bb12-5049002e7d70",
"Name": "New Folder Name",
}
```
[]
### 5. Creating a New File
* Endpoint: /api/files/create
* Method: POST;
* Authorization: required;
* Parameters:
* name (required): File name;
* name\_new (required): New file name;
* description (required): File description;
* folder\_id (required): GUID or path to the folder where the file will be added;
* Metadata (required): File metadata;
* file (required): File in binary format, or in Base16 / Base32 encodings.
* Example:
### 6. Retrieving Information About a File by GUID
* Endpoint: /api/files/read/{guid}
* Method: GET;
* Authorization: required;
* Parameters:
* Name (required): Name of the new file.
* Example:
| Request | Response |
| ------------------------------------------------------------- | -------- |
| `json
{
"Name": "example.txt",
}
` | \[] |
### 7. Updating Information About a File by GUID
* Endpoint: /api/files/update
* Method: PUT;
* Authorization: required;
* Parameters:
* Name (required): Name of the new file;
* folder\_guid: ID of the folder to which the file needs to be added;
* file: File in binary format, or in Base16 / Base32 encodings;
* Example:
| Request | Response |
| ------------------------------------------------------------- | -------- |
| `json
{
"Name": "example.txt",
}
` | \[] |
### 8. Deleting a File/Folder
* Endpoint: /api/files/delete
* Method: DELETE;
* Authorization: required;
* Parameters:
* file\_folder\_guid (required): GUID or path to the file or folder;
* type\_processing (required): Type of processing. Possible values:\
0 = Auto, 1 = File, 2 = Directory.
* Example:
### 9. Uploading a File
* Endpoint: /api/files/uploadfile
* Method: POST;
* Authorization: required;
* Parameters:
* file (required): File to upload;
* folder\_id: ID of the folder to which the file needs to be added;
* metadata: File metadata.
* Example:
` |
## 3. Log
Allows managing Logs. The user can create a new Log, retrieve information about the Log, update information about the Log, and delete the Log.
At the top of the page, there is a table with all logging levels:
At the bottom, there are tabs with methods:
By clicking on the icon  to the right of the desired method, the corresponding page opens:
### 1. Creating a Log
* Endpoint: /api/log/create
* Method: POST;
* Authorization: required;
* Parameters:
* RobotGUID: GUID of the Robot;
* ProcessVersionGUID: GUID of the Process version;
* JobGUID: GUID of the Job;
* Level: logging level;
Message (required): log text.
* Example:
### 2. Retrieving Information About a Log by GUID
* Endpoint: /api/log/read/{guid}
* Method: GET;
* Authorization: required;
* Parameters:
* Guid (required): Guid of the Log.
* Example:
### 3. Retrieving a List of Files Associated with GUID
* Endpoint: /api/log/list
* Method: POST;
* Authorization: required;
* Parameters: none.
* Example:
| Request | Response |
| ------------- | -------- |
| /api/log/list | \[] |
### 4. Deleting Logs Belonging to the Current Account Created Before the Selected Time
* Endpoint: /api/log/purge
* Method: DELETE;
* Authorization: required;
* Parameters:
* Time (required): timestamp in Unix format (Unix timestamp);
* Example:
| Request | Response |
| ------------------------------------------------------------ | -------- |
| `json
{
"Time": "1590481487",
}
` | \[] |
## 4. Accounts
Allows managing Accounts. The user can create a new Account, retrieve information about the Account, update information about the Account, and delete the Account.
This page contains tabs with methods:
By clicking on the icon  to the right of the desired method, the corresponding page opens:
* Endpoint: /api/account/create
* Method: POST;
* Authorization: required;
* Parameters:
* Login (required) — Login for the new Account;
* Password (required) — Password for the new Account;
* FirstName — First name for the new Account;
* LastName — Last name for the new Account;
* Email — Email for the new Account;
* Phone — Phone for the new Account;
* Company — Company for the new Account;
* Department — Department for the new Account.
* Example:
| Request | Response |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `json
{
"Login": "New Test Account",
"Password": "newPassword123",
}
` | \["guid": "c39713ea-d8b9-4669-976e-5ff39677dc64"] |
### 2. Retrieving Information About an Account by GUID
* Endpoint: /api/account/read/{guid}
* Method: GET;
* Authorization: required;
* Parameters:
* GUID (required): GUID of the Account.
* Example:
| Request | Response |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| /api/account/read/c39713ea-d8b9-4669-976e-5ff39677dc64 | `json
{
"id": "5",
"guid": "554ab883-1f82-48e1-bb12-5049002e7d70",
"login": "new Account",
"password": "123455678",
"first name": "Vasya",
"last name": "Ivanov",
}
` |
### 3. Updating Information About an Account by GUID
* Endpoint: /api/account/update
* Method: PUT;
* Authorization: required;
* Parameters:
* Guid (required) — GUID of the Account to update;
* Login — Login of the Account to update;
* Password — Password of the Account to update;
* FirstName — First name in the Account to update;
* LastName — Last name of the Account to update;
* Email — Email of the Account to update;
* Phone — Phone in the Account to update;
* Company — Company of the Account to update;
* Department — Department of the Account to update.
* Example:
| Request | Response |
| ----------------------------------------------------------------------------------------------------------------------- | -------- |
| `json
{
"Guid": "554ab883-1f82-48e1-bb12-5049002e7d70",
"Login": "Test Account",
}
` | \[] |
### 4. Deleting an Account by GUID
* Endpoint: /api/account/delete/{guid}
* Method: DELETE;
* Authorization: required;
* Parameters:
* Guid (required): Guid of the Account;
* Example:
| Request | Response |
| -------------------------------------------------------- | -------- |
| /api/account/delete/554ab883-1f82-48e1-bb12-5049002e7d70 | \[] |
## 5. AI Server
Allows managing neural networks. The user can accept a JSON object and return a response from the neural network, retrieve information about the currently used model, get a response from the Assistant, or send a message in the chat.
By clicking on the icon  to the right of the desired method, the corresponding page opens:
### 1. Adding Text Chunks to an Existing File
* Endpoint: /api/files/addchunk
* Method: POST;
* Authorization: required;
* Parameters:
* text\_chunk (required): Text chunk;
* guid\_file (required): GUID of the file or path to the file;
* metadata (required): Metadata of the chunk.
* Example:
### 2. Finding Embeddings by Given Text
* Endpoint: /api/files/search
* Method: GET;
* Authorization: required;
* Parameters:
* text\_for\_search (required): Text for search;
* n\_top (required): Number of top results;
* files\_ids (required): JSON string with a list of GUIDs or paths to files;
* folder\_ids (required): JSON string with a list of GUIDs or paths to folders;
* enable\_subfolders (required): Enable subfolders. Possible values: 0 = False, 1 = True.
* Example:
### 3. Retrieving a Response from the Neural Network
* Endpoint: /api/threads/message
* Method: POST;
* Authorization: required;
* Parameters:
* messages (required): Array of objects, each representing a message;
* content: Text of the message;
* role: Role of the message sender. Possible values: system, user;
* name: Name of the message sender;
* temperature: Floating-point number determining the degree of randomness in the neural network's responses. Default value: 0.7;
* model (required): String indicating the path to the model, e.g., /model-store/meta-llama/Meta-Llama-3-8B-Instruct;
* assistant\_id: Identifier of the assistant;
* thread\_id: Identifier of the chat;
* info: System information.
* Example:
### 4. Retrieving Information About the Currently Used Model
* Endpoint: /api/threads/models
* Method: GET;
* Authorization: required;
* Parameters: none.
* Example:
### 5. Retrieving a Message from the Assistant
* Endpoint: /api/threads/getUpdates
* Method: GET;
* Authorization: required;
* Parameters:
* assistant\_id (required): Identifier of the assistant;
* offset: Identifier of the message from which to retrieve the list of messages;
* thread\_id (required): Identifier of the chat.
* Example:
"content": "{\"type\":\"text\",\"text\":{\"value\":\"Hello! Glad to see you! How can I help you today?\",\"annotations\":[]}}",
"role": "assistant",
"account_id": "1",
"is_deleted": "0",
"folder_id": null,
"file_id": null,
"update_id": null
}
]
}
```
### 6. Sending a Message in the Chat
* Endpoint: /api/threads/chat
* Method: POST;
* Authorization: required;
* Parameters:
* thread\_id (required): Identifier of the chat;
* role (required): Role of the message sender (e.g., assistant);
* content (required): Text of the message;
* assistant\_id: Identifier of the assistant;
* model\_id: Identifier of the model group;
* temperature: Floating-point number determining the degree of randomness in the neural network's responses. Default value: 0.7;
* prompt: Initial context or instruction for the model;
* title: Title of the chat;
* file\_id: List of file IDs attached to the message (JSON array);
* folder\_id: List of folder IDs (or objects with id) attached to the message (JSON array),
* info: System information.
* Example:
| Request | Response |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `json
{ "thread_id": 200, "role": "assistant", "content": "Hello! How can I help you today?", "file_id": [101, 102], "folder_id": [201, 202],
` |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.sherparpa.ru/en/sherpa-ai/sherpa-ai-server/rabota-v-sherpa-ai-server/api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
.png?alt=media)
