mirror of
https://github.com/infiniflow/ragflow.git
synced 2025-12-19 12:06:42 +08:00
Docs: Enhance API reference for file management (#11827)
### What problem does this PR solve? The SDK documentation is lacking in file management sections. ### Type of change - [x] Documentation Update
This commit is contained in:
changkeke
@ -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 <YOUR_API_KEY>'`
|
||||
- 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 <YOUR_API_KEY>' \
|
||||
--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 <YOUR_API_KEY>'`
|
||||
- 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 <YOUR_API_KEY>' \
|
||||
--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 <YOUR_API_KEY>'`
|
||||
|
||||
##### 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 <YOUR_API_KEY>'
|
||||
```
|
||||
|
||||
##### 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 <YOUR_API_KEY>'`
|
||||
|
||||
##### Request example
|
||||
|
||||
```bash
|
||||
curl --request GET \
|
||||
--url http://{address}/api/v1/file/root_folder \
|
||||
--header 'Authorization: Bearer <YOUR_API_KEY>'
|
||||
```
|
||||
|
||||
##### 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 <YOUR_API_KEY>'`
|
||||
|
||||
##### Request example
|
||||
|
||||
```bash
|
||||
curl --request GET \
|
||||
--url 'http://{address}/api/v1/file/parent_folder?file_id={file_id}' \
|
||||
--header 'Authorization: Bearer <YOUR_API_KEY>'
|
||||
```
|
||||
|
||||
##### 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 <YOUR_API_KEY>'`
|
||||
|
||||
##### Request example
|
||||
|
||||
```bash
|
||||
curl --request GET \
|
||||
--url 'http://{address}/api/v1/file/all_parent_folder?file_id={file_id}' \
|
||||
--header 'Authorization: Bearer <YOUR_API_KEY>'
|
||||
```
|
||||
|
||||
##### 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 <YOUR_API_KEY>'`
|
||||
- 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 <YOUR_API_KEY>' \
|
||||
--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 <YOUR_API_KEY>'`
|
||||
- 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 <YOUR_API_KEY>' \
|
||||
--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 <YOUR_API_KEY>'`
|
||||
|
||||
##### Request example
|
||||
|
||||
```bash
|
||||
curl --request GET \
|
||||
--url http://{address}/api/v1/file/get/{file_id} \
|
||||
--header 'Authorization: Bearer <YOUR_API_KEY>' \
|
||||
--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 <YOUR_API_KEY>'`
|
||||
- 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 <YOUR_API_KEY>' \
|
||||
--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 <YOUR_API_KEY>'`
|
||||
- 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 <YOUR_API_KEY>' \
|
||||
--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!"
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user