REST API

所有端点前缀 /api/atlas/v1。除 ready 与 openapi.json 外均需 Authorization: Bearer <API_KEY>。

端点总览

方法	路径	说明	鉴权
GET	/ready	就绪检查 + 包版本	公开
GET	/openapi.json	OpenAPI 契约（别名 /openapi.json）	公开
GET	/stats	知识包统计	Bearer
GET	/lookup?id= 或 ?slug=	精确查找	Bearer
POST	/search	全文检索	Bearer
POST	/graph	实体邻域图谱	Bearer
POST	/admin/reload	触发热更新	Bearer
GET	/admin/usage	用量报表	Bearer
GET	/admin/billing	月度账单	Bearer

完整字段契约见 API 参考（自动生成） 或直接拉取 GET /api/atlas/v1/openapi.json（可导入 Postman / Swagger / 代码生成）。

示例

查找

curl "https://atlas.halfwaylab.cn/api/atlas/v1/lookup?id=per_tadao-ando" \
  -H "Authorization: Bearer <API_KEY>"

检索

curl -X POST https://atlas.halfwaylab.cn/api/atlas/v1/search \
  -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \
  -d '{"q":"清水混凝土","scope":["work"],"limit":3}'

图谱

curl -X POST https://atlas.halfwaylab.cn/api/atlas/v1/graph \
  -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \
  -d '{"rootId":"per_tadao-ando","maxDepth":1,"maxNodes":10}'

错误格式

{ "error": { "code": "UNAUTHORIZED", "message": "missing or invalid API key" } }