跳到主要内容

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": "..."}。

下一步​