knowledge-platform/docs/api/API_CONTRACT.md
2026-09-01 16:10:14 +08:00

57 lines
2.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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` 信息,不回显凭证、请求正文或厂商响应。