API 集成

ASP 后端提供实时生成的 OpenAPI 文档，适合外部系统集成、脚本自动化和接口调试。完整 HTTP API 清单以后端运行时生成的 Swagger UI / Redoc 为准，文档站只维护入口、认证方式和实时通道说明，避免重复维护接口清单。

文档入口

部署后可以访问以下入口：

入口	路径	用途
Swagger UI	/api/docs/	交互式接口文档，支持直接发起请求。
Redoc	/api/redoc/	只读接口文档，适合阅读和检索。
OpenAPI Schema	/api/schema/	OpenAPI 3 schema，适合生成 SDK 或导入第三方工具。

认证

自动化集成推荐使用 API Key。请求头格式如下：

Authorization: Api-Key <key>

交互式用户或前端登录流程可以使用 JWT：

Authorization: Bearer <access_token>

Swagger UI 的 Authorize 面板同时支持以上两种认证方式。外部系统长期集成时优先使用 API Key，因为它不依赖用户登录会话，也更适合脚本和服务账号管理。

API 版本

当前主 HTTP API 使用 /api/... 路径，暂未全局引入 /api/v1/...。Agent / CLI 集成接口已使用 /api/agent/v1/...，用于需要更稳定契约的自动化场景。

Realtime API

OpenAPI 只描述 HTTP API。实时事件使用 WebSocket，路径为：

/ws/events/

连接成功后服务端会发送：

{"type": "realtime.connected"}

客户端可以发送以下消息订阅或取消订阅评论事件：

{"type": "comments.subscribe", "content_type": "case", "object_id": "CASE-000001"}

{"type": "comments.unsubscribe", "content_type": "case", "object_id": "CASE-000001"}

服务端可能返回：

事件类型	说明
comments.subscribed	已订阅指定记录的评论事件。
comments.unsubscribed	已取消订阅指定记录的评论事件。
realtime.error	请求无法处理或消息类型未知。

Inbox 和评论变更也会通过该连接推送给已认证用户。