diff --git a/docs/references/http_api_reference.md b/docs/references/http_api_reference.md index 12d9e5cd8..e33919c7e 100644 --- a/docs/references/http_api_reference.md +++ b/docs/references/http_api_reference.md @@ -4522,3 +4522,687 @@ Explanation: - Each service is reported as "ok" or "nok". - The top-level `status` reflects overall health. - If any service is "nok", detailed error info appears in `_meta`. + +--- + +## FILE MANAGEMENT + +--- + +### Upload file + +**POST** `/api/v1/file/upload` + +Uploads one or multiple files to the system. + +#### Request + +- Method: POST +- URL: `/api/v1/file/upload` +- Headers: + - `'Content-Type: multipart/form-data'` + - `'Authorization: Bearer '` +- Form: + - `'file=@{FILE_PATH}'` + - `'parent_id'`: `string` (optional) + +##### Request example + +```bash +curl --request POST \ + --url http://{address}/api/v1/file/upload \ + --header 'Content-Type: multipart/form-data' \ + --header 'Authorization: Bearer ' \ + --form 'file=@./test1.txt' \ + --form 'file=@./test2.pdf' \ + --form 'parent_id={folder_id}' +``` + +##### Request parameters + +- `'file'`: (*Form parameter*), `file`, *Required* + The file(s) to upload. Multiple files can be uploaded in a single request. +- `'parent_id'`: (*Form parameter*), `string` + The parent folder ID where the file will be uploaded. If not specified, files will be uploaded to the root folder. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": [ + { + "id": "b330ec2e91ec11efbc510242ac120004", + "name": "test1.txt", + "size": 17966, + "type": "doc", + "parent_id": "527fa74891e811ef9c650242ac120006", + "location": "test1.txt", + "create_time": 1729763127646 + } + ] +} +``` + +Failure: + +```json +{ + "code": 400, + "message": "No file part!" +} +``` + +--- + +### Create file or folder + +**POST** `/api/v1/file/create` + +Creates a new file or folder in the system. + +#### Request + +- Method: POST +- URL: `/api/v1/file/create` +- Headers: + - `'Content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"name"`: `string` + - `"parent_id"`: `string` (optional) + - `"type"`: `string` + +##### Request example + +```bash +curl --request POST \ + --url http://{address}/api/v1/file/create \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data '{ + "name": "New Folder", + "type": "FOLDER", + "parent_id": "{folder_id}" + }' +``` + +##### Request parameters + +- `"name"`: (*Body parameter*), `string`, *Required* + The name of the file or folder to create. +- `"parent_id"`: (*Body parameter*), `string` + The parent folder ID. If not specified, the file/folder will be created in the root folder. +- `"type"`: (*Body parameter*), `string` + The type of the file to create. Available options: + - `"FOLDER"`: Create a folder + - `"VIRTUAL"`: Create a virtual file + +#### Response + +Success: + +```json +{ + "code": 0, + "data": { + "id": "b330ec2e91ec11efbc510242ac120004", + "name": "New Folder", + "type": "FOLDER", + "parent_id": "527fa74891e811ef9c650242ac120006", + "size": 0, + "create_time": 1729763127646 + } +} +``` + +Failure: + +```json +{ + "code": 409, + "message": "Duplicated folder name in the same folder." +} +``` + +--- + +### List files + +**GET** `/api/v1/file/list?parent_id={parent_id}&keywords={keywords}&page={page}&page_size={page_size}&orderby={orderby}&desc={desc}` + +Lists files and folders under a specific folder. + +#### Request + +- Method: GET +- URL: `/api/v1/file/list?parent_id={parent_id}&keywords={keywords}&page={page}&page_size={page_size}&orderby={orderby}&desc={desc}` +- Headers: + - `'Authorization: Bearer '` + +##### Request example + +```bash +curl --request GET \ + --url 'http://{address}/api/v1/file/list?parent_id={folder_id}&page=1&page_size=15' \ + --header 'Authorization: Bearer ' +``` + +##### Request parameters + +- `parent_id`: (*Filter parameter*), `string` + The folder ID to list files from. If not specified, the root folder is used by default. +- `keywords`: (*Filter parameter*), `string` + Search keyword to filter files by name. +- `page`: (*Filter parameter*), `integer` + Specifies the page on which the files will be displayed. Defaults to `1`. +- `page_size`: (*Filter parameter*), `integer` + The number of files on each page. Defaults to `15`. +- `orderby`: (*Filter parameter*), `string` + The field by which files should be sorted. Available options: + - `create_time` (default) +- `desc`: (*Filter parameter*), `boolean` + Indicates whether the retrieved files should be sorted in descending order. Defaults to `true`. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": { + "total": 10, + "files": [ + { + "id": "b330ec2e91ec11efbc510242ac120004", + "name": "test1.txt", + "type": "doc", + "size": 17966, + "parent_id": "527fa74891e811ef9c650242ac120006", + "create_time": 1729763127646 + } + ], + "parent_folder": { + "id": "527fa74891e811ef9c650242ac120006", + "name": "Parent Folder" + } + } +} +``` + +Failure: + +```json +{ + "code": 404, + "message": "Folder not found!" +} +``` + +--- + +### Get root folder + +**GET** `/api/v1/file/root_folder` + +Retrieves the user's root folder information. + +#### Request + +- Method: GET +- URL: `/api/v1/file/root_folder` +- Headers: + - `'Authorization: Bearer '` + +##### Request example + +```bash +curl --request GET \ + --url http://{address}/api/v1/file/root_folder \ + --header 'Authorization: Bearer ' +``` + +##### Request parameters + +No parameters required. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": { + "root_folder": { + "id": "527fa74891e811ef9c650242ac120006", + "name": "root", + "type": "FOLDER" + } + } +} +``` + +--- + +### Get parent folder + +**GET** `/api/v1/file/parent_folder?file_id={file_id}` + +Retrieves the immediate parent folder information of a specified file. + +#### Request + +- Method: GET +- URL: `/api/v1/file/parent_folder?file_id={file_id}` +- Headers: + - `'Authorization: Bearer '` + +##### Request example + +```bash +curl --request GET \ + --url 'http://{address}/api/v1/file/parent_folder?file_id={file_id}' \ + --header 'Authorization: Bearer ' +``` + +##### Request parameters + +- `file_id`: (*Filter parameter*), `string`, *Required* + The ID of the file whose immediate parent folder to retrieve. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": { + "parent_folder": { + "id": "527fa74891e811ef9c650242ac120006", + "name": "Parent Folder" + } + } +} +``` + +Failure: + +```json +{ + "code": 404, + "message": "Folder not found!" +} +``` + +--- + +### Get all parent folders + +**GET** `/api/v1/file/all_parent_folder?file_id={file_id}` + +Retrieves all parent folders of a specified file in the folder hierarchy. + +#### Request + +- Method: GET +- URL: `/api/v1/file/all_parent_folder?file_id={file_id}` +- Headers: + - `'Authorization: Bearer '` + +##### Request example + +```bash +curl --request GET \ + --url 'http://{address}/api/v1/file/all_parent_folder?file_id={file_id}' \ + --header 'Authorization: Bearer ' +``` + +##### Request parameters + +- `file_id`: (*Filter parameter*), `string`, *Required* + The ID of the file whose parent folders to retrieve. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": { + "parent_folders": [ + { + "id": "527fa74891e811ef9c650242ac120006", + "name": "Parent Folder 1" + }, + { + "id": "627fa74891e811ef9c650242ac120007", + "name": "Parent Folder 2" + } + ] + } +} +``` + +Failure: + +```json +{ + "code": 404, + "message": "Folder not found!" +} +``` + +--- + +### Delete files + +**POST** `/api/v1/file/rm` + +Deletes one or multiple files or folders. + +#### Request + +- Method: POST +- URL: `/api/v1/file/rm` +- Headers: + - `'Content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"file_ids"`: `list[string]` + +##### Request example + +```bash +curl --request POST \ + --url http://{address}/api/v1/file/rm \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data '{ + "file_ids": ["file_id_1", "file_id_2"] + }' +``` + +##### Request parameters + +- `"file_ids"`: (*Body parameter*), `list[string]`, *Required* + The IDs of the files or folders to delete. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": true +} +``` + +Failure: + +```json +{ + "code": 404, + "message": "File or Folder not found!" +} +``` + +--- + +### Rename file + +**POST** `/api/v1/file/rename` + +Renames a file or folder. + +#### Request + +- Method: POST +- URL: `/api/v1/file/rename` +- Headers: + - `'Content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"file_id"`: `string` + - `"name"`: `string` + +##### Request example + +```bash +curl --request POST \ + --url http://{address}/api/v1/file/rename \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data '{ + "file_id": "{file_id}", + "name": "new_name.txt" + }' +``` + +##### Request parameters + +- `"file_id"`: (*Body parameter*), `string`, *Required* + The ID of the file or folder to rename. +- `"name"`: (*Body parameter*), `string`, *Required* + The new name for the file or folder. Note: Changing file extensions is *not* supported. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": true +} +``` + +Failure: + +```json +{ + "code": 400, + "message": "The extension of file can't be changed" +} +``` + +or + +```json +{ + "code": 409, + "message": "Duplicated file name in the same folder." +} +``` + +--- + +### Download file + +**GET** `/api/v1/file/get/{file_id}` + +Downloads a file from the system. + +#### Request + +- Method: GET +- URL: `/api/v1/file/get/{file_id}` +- Headers: + - `'Authorization: Bearer '` + +##### Request example + +```bash +curl --request GET \ + --url http://{address}/api/v1/file/get/{file_id} \ + --header 'Authorization: Bearer ' \ + --output ./downloaded_file.txt +``` + +##### Request parameters + +- `file_id`: (*Path parameter*), `string`, *Required* + The ID of the file to download. + +#### Response + +Success: + +Returns the file content as a binary stream with appropriate Content-Type headers. + +Failure: + +```json +{ + "code": 404, + "message": "Document not found!" +} +``` + +--- + +### Move files + +**POST** `/api/v1/file/mv` + +Moves one or multiple files or folders to a specified folder. + +#### Request + +- Method: POST +- URL: `/api/v1/file/mv` +- Headers: + - `'Content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"src_file_ids"`: `list[string]` + - `"dest_file_id"`: `string` + +##### Request example + +```bash +curl --request POST \ + --url http://{address}/api/v1/file/mv \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data '{ + "src_file_ids": ["file_id_1", "file_id_2"], + "dest_file_id": "{destination_folder_id}" + }' +``` + +##### Request parameters + +- `"src_file_ids"`: (*Body parameter*), `list[string]`, *Required* + The IDs of the files or folders to move. +- `"dest_file_id"`: (*Body parameter*), `string`, *Required* + The ID of the destination folder. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": true +} +``` + +Failure: + +```json +{ + "code": 404, + "message": "File or Folder not found!" +} +``` + +or + +```json +{ + "code": 404, + "message": "Parent Folder not found!" +} +``` + +--- + +### Convert files to documents and link them to datasets + +**POST** `/api/v1/file/convert` + +Converts files to documents and links them to specified datasets. + +#### Request + +- Method: POST +- URL: `/api/v1/file/convert` +- Headers: + - `'Content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"file_ids"`: `list[string]` + - `"kb_ids"`: `list[string]` + +##### Request example + +```bash +curl --request POST \ + --url http://{address}/api/v1/file/convert \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data '{ + "file_ids": ["file_id_1", "file_id_2"], + "kb_ids": ["dataset_id_1", "dataset_id_2"] + }' +``` + +##### Request parameters + +- `"file_ids"`: (*Body parameter*), `list[string]`, *Required* + The IDs of the files to convert. If a folder ID is provided, all files within that folder will be converted. +- `"kb_ids"`: (*Body parameter*), `list[string]`, *Required* + The IDs of the target datasets. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": [ + { + "id": "file2doc_id_1", + "file_id": "file_id_1", + "document_id": "document_id_1" + } + ] +} +``` + +Failure: + +```json +{ + "code": 404, + "message": "File not found!" +} +``` + +or + +```json +{ + "code": 404, + "message": "Can't find this knowledgebase!" +} +```