cecilia-uu
commited on
Commit
·
b134064
1
Parent(s):
f43283a
Doc: added doc for three doc methods (#1336)
Browse files### What problem does this PR solve?
Adds the documentation for three newly added API methods for content
management.
### Type of change
- [x] Documentation Update
- docs/references/ragflow_api.md +256 -0
docs/references/ragflow_api.md
CHANGED
|
@@ -276,4 +276,260 @@ You are required to input at least one parameter.
|
|
| 276 |
}
|
| 277 |
```
|
| 278 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 279 |
|
|
|
|
| 276 |
}
|
| 277 |
```
|
| 278 |
|
| 279 |
+
------------------------------------------------------------------------------------------------------------------------------
|
| 280 |
+
|
| 281 |
+
## Upload documents
|
| 282 |
+
|
| 283 |
+
This method uploads documents for a specific user.
|
| 284 |
+
|
| 285 |
+
### Request
|
| 286 |
+
|
| 287 |
+
#### Request URI
|
| 288 |
+
|
| 289 |
+
| Method | Request URI |
|
| 290 |
+
|--------|-----------------------------------|
|
| 291 |
+
| POST | `/dataset/{dataset_id}/documents` |
|
| 292 |
+
|
| 293 |
+
|
| 294 |
+
#### Request parameter
|
| 295 |
+
|
| 296 |
+
| Name | Type | Required | Description |
|
| 297 |
+
|--------------|--------|----------|------------------------------------------------------------|
|
| 298 |
+
| `dataset_id` | string | Yes | The ID of the dataset. Call ['GET' /dataset](#create-dataset) to retrieve the ID. |
|
| 299 |
+
|
| 300 |
+
### Response
|
| 301 |
+
|
| 302 |
+
### Successful response
|
| 303 |
+
|
| 304 |
+
```json
|
| 305 |
+
{
|
| 306 |
+
"code": 0,
|
| 307 |
+
"data": [
|
| 308 |
+
{
|
| 309 |
+
"created_by": "b48110a0286411ef994a3043d7ee537e",
|
| 310 |
+
"id": "859584a0379211efb1a23043d7ee537e",
|
| 311 |
+
"kb_id": "8591349a379211ef92213043d7ee537e",
|
| 312 |
+
"location": "test.txt",
|
| 313 |
+
"name": "test.txt",
|
| 314 |
+
"parser_config": {
|
| 315 |
+
"pages": [
|
| 316 |
+
[1, 1000000]
|
| 317 |
+
]
|
| 318 |
+
},
|
| 319 |
+
"parser_id": "naive",
|
| 320 |
+
"size": 0,
|
| 321 |
+
"thumbnail": null,
|
| 322 |
+
"type": "doc"
|
| 323 |
+
},
|
| 324 |
+
{
|
| 325 |
+
"created_by": "b48110a0286411ef994a3043d7ee537e",
|
| 326 |
+
"id": "8596f18c379211efb1a23043d7ee537e",
|
| 327 |
+
"kb_id": "8591349a379211ef92213043d7ee537e",
|
| 328 |
+
"location": "test1.txt",
|
| 329 |
+
"name": "test1.txt",
|
| 330 |
+
"parser_config": {
|
| 331 |
+
"pages": [
|
| 332 |
+
[1, 1000000]
|
| 333 |
+
]
|
| 334 |
+
},
|
| 335 |
+
"parser_id": "naive",
|
| 336 |
+
"size": 0,
|
| 337 |
+
"thumbnail": null,
|
| 338 |
+
"type": "doc"
|
| 339 |
+
}
|
| 340 |
+
],
|
| 341 |
+
"message": "success"
|
| 342 |
+
}
|
| 343 |
+
```
|
| 344 |
+
|
| 345 |
+
### Response for nonexistent files
|
| 346 |
+
|
| 347 |
+
```json
|
| 348 |
+
{
|
| 349 |
+
"code": "RetCode.DATA_ERROR",
|
| 350 |
+
"message": "The file test_data/imagination.txt does not exist"
|
| 351 |
+
}
|
| 352 |
+
```
|
| 353 |
+
|
| 354 |
+
### Response for nonexistent dataset
|
| 355 |
+
|
| 356 |
+
```json
|
| 357 |
+
{
|
| 358 |
+
"code": 102,
|
| 359 |
+
"message": "Can't find this dataset"
|
| 360 |
+
}
|
| 361 |
+
```
|
| 362 |
+
|
| 363 |
+
### Response for the number of files exceeding the limit
|
| 364 |
+
|
| 365 |
+
```json
|
| 366 |
+
{
|
| 367 |
+
"code": 102,
|
| 368 |
+
"message": "You try to upload 512 files, which exceeds the maximum number of uploading files: 256"
|
| 369 |
+
}
|
| 370 |
+
```
|
| 371 |
+
### Response for uploading without files.
|
| 372 |
+
|
| 373 |
+
```json
|
| 374 |
+
{
|
| 375 |
+
"code": 101,
|
| 376 |
+
"message": "None is not string."
|
| 377 |
+
}
|
| 378 |
+
```
|
| 379 |
+
|
| 380 |
+
## Delete documents
|
| 381 |
+
|
| 382 |
+
This method deletes documents for a specific user.
|
| 383 |
+
|
| 384 |
+
### Request
|
| 385 |
+
|
| 386 |
+
#### Request URI
|
| 387 |
+
|
| 388 |
+
| Method | Request URI |
|
| 389 |
+
|--------|-----------------------------------|
|
| 390 |
+
| DELETE | `/dataset/{dataset_id}/documents/{document_id}` |
|
| 391 |
+
|
| 392 |
+
|
| 393 |
+
#### Request parameter
|
| 394 |
+
|
| 395 |
+
| Name | Type | Required | Description |
|
| 396 |
+
|---------------|--------|----------|-------------------------------------------------------------------------------------|
|
| 397 |
+
| `dataset_id` | string | Yes | The ID of the dataset. Call ['GET' /dataset](#create-dataset) to retrieve the ID. |
|
| 398 |
+
| `document_id` | string | Yes | The ID of the document. Call ['GET' /document](#list-documents) to retrieve the ID. |
|
| 399 |
+
|
| 400 |
+
### Response
|
| 401 |
+
|
| 402 |
+
### Successful response
|
| 403 |
+
|
| 404 |
+
```json
|
| 405 |
+
{
|
| 406 |
+
"code": 0,
|
| 407 |
+
"data": true,
|
| 408 |
+
"message": "success"
|
| 409 |
+
}
|
| 410 |
+
```
|
| 411 |
+
|
| 412 |
+
### Response for deleting a document that does not exist
|
| 413 |
+
|
| 414 |
+
```json
|
| 415 |
+
{
|
| 416 |
+
"code": 102,
|
| 417 |
+
"message": "Document 111 not found!"
|
| 418 |
+
}
|
| 419 |
+
```
|
| 420 |
+
### Response for deleting documents from a non-existent dataset
|
| 421 |
+
|
| 422 |
+
```json
|
| 423 |
+
{
|
| 424 |
+
"code": 101,
|
| 425 |
+
"message": "The document f7aba1ec379b11ef8e853043d7ee537e is not in the dataset: 000, but in the dataset: f7a7ccf2379b11ef83223043d7ee537e."
|
| 426 |
+
}
|
| 427 |
+
```
|
| 428 |
+
|
| 429 |
+
## List documents
|
| 430 |
+
|
| 431 |
+
This method deletes documents for a specific user.
|
| 432 |
+
|
| 433 |
+
### Request
|
| 434 |
+
|
| 435 |
+
#### Request URI
|
| 436 |
+
|
| 437 |
+
| Method | Request URI |
|
| 438 |
+
|--------|-----------------------------------|
|
| 439 |
+
| GET | `/dataset/{dataset_id}/documents` |
|
| 440 |
+
|
| 441 |
+
|
| 442 |
+
#### Request parameter
|
| 443 |
+
|
| 444 |
+
| Name | Type | Required | Description |
|
| 445 |
+
|--------------|--------|----------|------------------------------------------------------------------------------------------------------------|
|
| 446 |
+
| `dataset_id` | string | Yes | The ID of the dataset. Call ['GET' /dataset](#create-dataset) to retrieve the ID. |
|
| 447 |
+
| `offset` | int | No | The start of the listed documents. Default: 0 |
|
| 448 |
+
| `count` | int | No | The total count of the listed documents. Default: -1, meaning all the later part of documents from the start. |
|
| 449 |
+
| `order_by` | string | No | Default: `create_time` |
|
| 450 |
+
| `descend` | bool | No | The order of listing documents. Default: True |
|
| 451 |
+
| `keywords` | string | No | The searching keywords of listing documents. Default: "" |
|
| 452 |
+
|
| 453 |
+
### Response
|
| 454 |
+
|
| 455 |
+
### Successful Response
|
| 456 |
+
|
| 457 |
+
```json
|
| 458 |
+
{
|
| 459 |
+
"code": 0,
|
| 460 |
+
"data": {
|
| 461 |
+
"docs": [
|
| 462 |
+
{
|
| 463 |
+
"chunk_num": 0,
|
| 464 |
+
"create_date": "Mon, 01 Jul 2024 19:24:10 GMT",
|
| 465 |
+
"create_time": 1719833050046,
|
| 466 |
+
"created_by": "b48110a0286411ef994a3043d7ee537e",
|
| 467 |
+
"id": "6fb6f588379c11ef87023043d7ee537e",
|
| 468 |
+
"kb_id": "6fb1c9e6379c11efa3523043d7ee537e",
|
| 469 |
+
"location": "empty.txt",
|
| 470 |
+
"name": "empty.txt",
|
| 471 |
+
"parser_config": {
|
| 472 |
+
"pages": [
|
| 473 |
+
[1, 1000000]
|
| 474 |
+
]
|
| 475 |
+
},
|
| 476 |
+
"parser_id": "naive",
|
| 477 |
+
"process_begin_at": null,
|
| 478 |
+
"process_duation": 0.0,
|
| 479 |
+
"progress": 0.0,
|
| 480 |
+
"progress_msg": "",
|
| 481 |
+
"run": "0",
|
| 482 |
+
"size": 0,
|
| 483 |
+
"source_type": "local",
|
| 484 |
+
"status": "1",
|
| 485 |
+
"thumbnail": null,
|
| 486 |
+
"token_num": 0,
|
| 487 |
+
"type": "doc",
|
| 488 |
+
"update_date": "Mon, 01 Jul 2024 19:24:10 GMT",
|
| 489 |
+
"update_time": 1719833050046
|
| 490 |
+
},
|
| 491 |
+
{
|
| 492 |
+
"chunk_num": 0,
|
| 493 |
+
"create_date": "Mon, 01 Jul 2024 19:24:10 GMT",
|
| 494 |
+
"create_time": 1719833050037,
|
| 495 |
+
"created_by": "b48110a0286411ef994a3043d7ee537e",
|
| 496 |
+
"id": "6fb59c60379c11ef87023043d7ee537e",
|
| 497 |
+
"kb_id": "6fb1c9e6379c11efa3523043d7ee537e",
|
| 498 |
+
"location": "test.txt",
|
| 499 |
+
"name": "test.txt",
|
| 500 |
+
"parser_config": {
|
| 501 |
+
"pages": [
|
| 502 |
+
[1, 1000000]
|
| 503 |
+
]
|
| 504 |
+
},
|
| 505 |
+
"parser_id": "naive",
|
| 506 |
+
"process_begin_at": null,
|
| 507 |
+
"process_duation": 0.0,
|
| 508 |
+
"progress": 0.0,
|
| 509 |
+
"progress_msg": "",
|
| 510 |
+
"run": "0",
|
| 511 |
+
"size": 0,
|
| 512 |
+
"source_type": "local",
|
| 513 |
+
"status": "1",
|
| 514 |
+
"thumbnail": null,
|
| 515 |
+
"token_num": 0,
|
| 516 |
+
"type": "doc",
|
| 517 |
+
"update_date": "Mon, 01 Jul 2024 19:24:10 GMT",
|
| 518 |
+
"update_time": 1719833050037
|
| 519 |
+
}
|
| 520 |
+
],
|
| 521 |
+
"total": 2
|
| 522 |
+
},
|
| 523 |
+
"message": "success"
|
| 524 |
+
}
|
| 525 |
+
```
|
| 526 |
+
|
| 527 |
+
### Response for listing documents with IndexError
|
| 528 |
+
|
| 529 |
+
```json
|
| 530 |
+
{
|
| 531 |
+
"code": 100,
|
| 532 |
+
"message": "IndexError('Offset is out of the valid range.')"
|
| 533 |
+
}
|
| 534 |
+
```
|
| 535 |
|