knowledge-platform/docs/api/API_CONTRACT.md
2026-09-02 13:48:31 +08:00

2.2 KiB
Raw Blame History

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 请求:

{
  "query": "产品A退款周期是多少?",
  "top_k": 5
}

Search 响应:

{
  "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。