# 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` 信息,不回显凭证、请求正文或厂商响应。 ## Demo Admin 客户端路由 DEMO-010 提供 `/admin/upload`、`/admin/documents` 和 `/admin/search` 三个客户端路由, `/admin` 默认展示上传页。它们是同源静态页面,不是新增业务 API,也不改变上述公开 REST 契约;所有业务操作仍调用 `/api/v1`。