API 文档导读
巴克励步
概述
本篇为 操作手册导读：说明如何获取密钥、API 基址与文档入口，不替代官方接口明细。参数、字段与示例以 Baklib Max API 正式文档为准。
操作步骤
步骤一：创建并保管 API 密钥
- 登录工作台 → 个人中心 → API密钥（
/my/access_keys）。 - 创建密钥，保存
<key>:<secret>（Secret 仅展示一次）。 - 通过环境变量或密钥管理服务注入调用方，勿写入 Git。
操作细节见 API 密钥。
预期结果：持有一对可用于 HTTP 鉴权的密钥。
步骤二：确认 API 基址与鉴权方式
- 官方 SaaS 默认主机：
https://open.baklib.com（CLI 在此基础上请求/api/v1/...） - 鉴权：请求头携带 API 密钥（具体 Header 名称与格式以 Baklib Max API 文档 为准；MCP/CLI 使用
<key>:<secret>单行 Token 封装） - 权限与审计：密钥绑定 当前成员账号；组织可在 API 请求日志（
/admin/api_requests）查看调用记录
预期结果：调用方配置好 base URL 与 Token。
步骤三：查阅官方 API 文档
- 打开帮助中心 [API 接口调用操作指南][1]。
- 按页面指引下载或在线阅读 Baklib Max API 文档（PDF / 在线版以该页为准）。
- 按模块查找接口：知识库空间与文章、站点与页面、DAM 上传、成员与组织等。
说明：操作手册暂不内嵌完整 OpenAPI/Swagger；若您的组织提供独立 API 文档或私有化网关地址，请以组织交付文档为准。
预期结果：能定位到目标接口的路径、必填参数与响应结构。
步骤四：选择调用方式
| 方式 | 适合场景 |
|---|---|
| MCP 教程 | AI 对话中 list/get/写入；须声明 Markdown body_type |
| CLI 教程 | 终端脚本、kb pull/push、theme dev、CI |
| HTTP 客户端 | 自有系统深度集成、非 Node 技术栈 |
| Webhooks | 事件推送（非 REST 拉取）；见 Webhooks |
多数客户管理员日常 不必直接调 HTTP；优先 MCP 或 CLI 即可覆盖常见内容运维。
预期结果：按场景选用工具，减少重复封装。
步骤五：用量与配额
API 调用计入组织 配额 与 API 用量包；超限处理见 充值与加购包。
预期结果：集成前评估调用频率，避免触顶。
常见问题
Q：API 密钥能否代表「服务账号」？
A：当前密钥绑定个人成员；建议用专用成员账号创建密钥，避免绑定即将离职个人。
A：当前密钥绑定个人成员；建议用专用成员账号创建密钥，避免绑定即将离职个人。
Q：与 Webhooks 有何区别？
A：API 为客户端 主动请求；Webhooks 为 Baklib 事件回调 到您的 URL。二者互补。
A：API 为客户端 主动请求；Webhooks 为 Baklib 事件回调 到您的 URL。二者互补。
Q：是否有公开 OpenAPI JSON？
A：以 www.baklib.com/docs 当前提供的 Baklib Max API 文档为准；若需机器可读 OpenAPI，请联系 Baklib 支持或查阅文档更新。
A：以 www.baklib.com/docs 当前提供的 Baklib Max API 文档为准；若需机器可读 OpenAPI，请联系 Baklib 支持或查阅文档更新。
Q：写入知识库正文要注意什么？
A：与 MCP 相同：Markdown 来源正文须声明
A：与 MCP 相同：Markdown 来源正文须声明
content_type / body_type: markdown；扩展语法遵循 文档编辑器 Markdown 与 baklib-bke-markdown 技能。