57 lines
2.0 KiB
Markdown
57 lines
2.0 KiB
Markdown
# REST API Contract
|
||
|
||
Version all public APIs under `/api/v1`.
|
||
|
||
Initial domains: auth, users/groups, knowledge-bases, documents, compiled-knowledge, search, evaluations, jobs, audit-logs, providers and MCP administration.
|
||
|
||
Use OpenAPI as executable source of truth once implementation starts. Provider-specific concepts must not leak into public contracts.
|
||
|
||
## Demo v0.1 P0
|
||
|
||
DEMO-009 公开以下最小接口。`docs/demo/DEMO_SCOPE.md` 中的 `/api/*` 逻辑路径按本契约统一
|
||
版本化为 `/api/v1/*`。
|
||
|
||
| Method | Path | 行为 |
|
||
|---|---|---|
|
||
| `POST` | `/api/v1/documents` | multipart 单文件上传并同步执行完整入库流水线 |
|
||
| `GET` | `/api/v1/documents` | 按创建时间倒序返回文档列表 |
|
||
| `GET` | `/api/v1/documents/{document_id}` | 返回单个文档状态与安全错误信息 |
|
||
| `DELETE` | `/api/v1/documents/{document_id}` | 直接删除向量、Metadata、解析产物和原始文件 |
|
||
| `POST` | `/api/v1/search` | Dense Top20、Reranker、TopK、来源补全 |
|
||
|
||
上传字段名为 `file`,支持 PDF、DOCX、TXT 和 Markdown。成功返回 `201` 和 Document;
|
||
Demo 同步流水线完成后状态为 `ready`。Document 响应不暴露 `storage_key`、Provider 配置或
|
||
索引实现。
|
||
|
||
Search 请求:
|
||
|
||
```json
|
||
{
|
||
"query": "产品A退款周期是多少?",
|
||
"top_k": 5
|
||
}
|
||
```
|
||
|
||
Search 响应:
|
||
|
||
```json
|
||
{
|
||
"results": [
|
||
{
|
||
"document_id": "6e5ec370-5a45-4eb7-95d7-e84267ad8752",
|
||
"filename": "产品A说明书.pdf",
|
||
"page": 12,
|
||
"section": "退款政策",
|
||
"chunk_id": "76ba1c30-bff7-44e5-9989-fb8372f54f46",
|
||
"content": "……",
|
||
"score": 0.82,
|
||
"rerank_score": 0.94
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
公开错误语义:请求校验失败返回 `422`,不支持的上传类型返回 `415`,文件过大返回 `413`,
|
||
文档不存在返回 `404`,运行时 Provider 未配置返回 `503`。上游 Provider 或持久化异常只返回
|
||
经过收敛的 `5xx` 信息,不回显凭证、请求正文或厂商响应。
|