开放 API 文档
| 项目 | 说明 |
|---|---|
| 适用场景 | 资源管理、文件上传、网页收藏、搜索、标签和 AI 对话集成 |
| 当前限制 | 基础版空间每 24 小时最多调用 10 次；高级版空间最多调用 1,000 次 |
小黑 OmniBox Open API 是一组使用 Bearer Token 鉴权的 REST API，适用于插件、自动化、系统集成和 Agent 工作流。API Key 可以限制可访问的资源范围和操作权限。
根据部署方式使用对应的 API 地址和 Swagger 文档：
| 地址 | Swagger 文档 | |
|---|---|---|
| 云服务 | api.omnibox.pro | OmniBox Open API Docs |
| 本地部署 | <your-server>/open/api/ | <your-server>/open/api/docs |
获取 API Key
参见：如何创建 API Key
创建 API Key 时可以添加备注，建议记录用途、调用方或关联助手，方便后续管理和清理。
API Key 权限与范围
创建 API Key 时，需要设置 权限范围 和具体权限。
权限范围 决定这个 API Key 可以访问知识库中的哪一部分。新建 API Key 默认选择「个人」，已有密钥不会自动扩大权限范围。也可以选择某个文件或文件夹，仅授权该资源及其子内容。
拥有或加入团队时，可以主动选择「个人 + 团队」。同一把密钥即可访问当前空间内自己的「个人」资源及「团队」中有权限的资源，不包含其他成员的「个人」资源。选项与知识库中的团队入口保持一致：仅剩自己且团队内没有内容时，不显示团队相关选项。
权限范围与保存位置分别处理：新建内容、收藏链接和上传文件时，显式指定的保存目录优先；没有指定时，保留助手已有的明确保存位置，否则默认保存到「个人」。指定位置不可用或没有权限时直接报错，不会自动改存「个人」。修改、删除已有资源仍作用于原资源，不转存或创建副本。
在 API 密钥列表中，系统会展示具体的资源权限范围；点击资源名称可以进入对应资源详情，方便确认 API Key 的可访问范围。
目前支持的权限包括：
| 权限 | 可选操作 | 说明 |
|---|---|---|
资源权限 | 创建、读取、更新、删除 | 管理文件、文件夹、资源内容、资源标签关联、网页收藏和文件上传 |
对话权限 | 创建 | 调用 AI 对话能力 |
标签权限 | 创建、读取 | 创建标签、查询标签 |
搜索权限 | 读取 | 在 API Key 的权限范围内搜索资源 |
如果 API Key 没有所需权限，接口会返回权限不足。建议只勾选当前集成真正需要的权限，避免给自动化脚本过大的访问范围。
在外部 Agent 中使用 Open API Skill
如果你希望让外部 Agent、自动化脚本或内部工具调用小黑 Open API，建议先让 Agent 读取小黑提供的 SKILL.md。该文件会说明 Open API 地址、认证方式、权限范围、额度规则和常用调用流程。
加载 Open API Skill 后，Agent 可以识别小黑资源链接、空间链接和分享链接，并根据链接上下文调用对应的 Open API 能力。
云服务地址：
https://api.omnibox.pro/v1/SKILL.md自部署场景请使用你的 Open API 访问地址，例如：
https://<your-domain>/open/api/v1/SKILL.md调用次数限制：
- 基础版空间：每 24 小时 10 次
- 高级版空间：每 24 小时 1000 次
调用 Open API 时请使用 Bearer Token：
Authorization: Bearer <api-key>安全建议：不要把 API Key 写入日志、文档、URL 或聊天上下文。完整接口参数和响应结构请以 Swagger 文档 以及 SKILL.md 为准。