API 概览

基础信息

• Base URL：你的服务地址，形如 http://<your-server>:8668
• 接口前缀：/api/v1
• 数据格式：请求/响应均为 JSON，文件上传用 multipart/form-data
• 唯一免鉴权端点：GET /api/v1/health 与首个 token 引导

本章所有 curl 示例统一用 $HOST 表示服务地址，先设置环境变量即可原样复制运行：

export HOST=http://<your-server>:8668   # 替换为你的服务地址
export TOKEN=sk-memex-XXXXXXXX          # 你的 API token

认证

除引导外，所有 /api/v1/* 请求均需携带 Bearer Token：

Authorization: Bearer sk-memex-XXXXXXXX...

SSE 流式接口（EventSource 无法设置 header）改用查询参数：

GET /api/v1/jobs/42/stream?access_token=sk-memex-XXXX

核心流程

上传文档 → job 入队(queued) → 调度器自动运行
  → egg → boot → grow → ready → 可预览/发布
                               → butler 持续维护

上传即排队，无需手动启动。 调度器在并发额度内自动拾取 queued job，客户端轮询 GET /jobs/{id} 或订阅 SSE 查看进度。

错误约定

状态码	含义
200	成功，体含 "ok": true
400	参数错误（非法 slug、无法识别文件类型等）
401	缺失 / 无效 / 已吊销 token
403	越权（访问他人 job / wiki）
404	资源不存在

错误响应格式：{"error": "..."} 或 FastAPI 标准格式 {"detail": "..."}。

完整端点清单

认证 POST/GET /auth/tokens · POST /auth/tokens/revoke · GET /auth/me

任务 POST /upload · POST /upload-url · GET /jobs · GET /jobs/{id} · GET /jobs/{id}/log · GET /jobs/{id}/stream · POST /jobs/{id}/start · POST /jobs/{id}/reset · DELETE /jobs/{id} · GET /queue

Wiki GET /wikis-overview · POST /wiki/{slug}/serve · POST /wiki/{slug}/serve/stop · POST /wiki/{slug}/serve/restart · POST /wiki/{slug}/butler · POST /wiki/{slug}/butler/stop · GET /wiki/{slug}/butler/log · PUT /wiki/{slug}/butler/config · GET /wiki/{slug}/reviews · GET /wiki/{slug}/growth · GET /wiki/{slug}/search

内容 GET /pages · GET /pages/{id} · POST /search · GET /graph · GET /stats · GET /genes

系统 GET /health