Nubbo API 是一个 REST API,让你用自己的代码操作存储桶:文件、文件夹、链接、文件请求、相册、标签、项目和自动化。在本指南中,你将创建一个密钥,并用 curl 发出最初的几个请求。
你将获得什么
- 通过你的程序管理 Nubbo 空间,密钥只能看到你选择的内容。
- 在你的代码和存储服务商之间直接上传和下载。
- 通过触发器响应新文件、文件请求上传和活动。
开始之前
你需要一个使用 Pro 或团队套餐的 Nubbo 账号,以及一个装有 curl 的终端。在团队中,API 密钥由所有者或管理员创建。
第 1 步:创建密钥
在 Nubbo 中打开 设置 › API(在团队中为 团队 › API),点击 创建 API 密钥。
输入名称并选择:
- 权限:只读 或 读写。
- 范围:整个空间 或 选定的存储桶和项目。密钥只能看到你在这里选择的内容。
- 有效期:30 天、90 天、1 年或 永不过期。Nubbo 会提前 7 天提醒你。
点击 创建密钥。Nubbo 会要求输入密码,确认是你本人。 如果启用了双重验证,还需要输入验证码。

复制密钥并点击 我已保存。密钥以
nbk_开头,这是你唯一一次看到完整密钥。请把它保存在服务器或将要使用它的工具中,切勿放在网页里。

第 2 步:第一个请求
在每个请求的 Authorization 请求头中携带密钥。先从 GET /v1/me 开始,它不计入请求数:
curl https://api.nubbo.app/v1/me \
-H "Authorization: Bearer nbk_your_key"
响应包含你的空间、套餐、本月配额,以及密钥的权限和范围。以下是节选:
{
"workspace": { "id": "…", "name": "北方工作室", "kind": "PERSONAL" },
"plan": "PRO",
"key": {
"name": "我的第一个密钥",
"prefix": "nbk_3jKF3m",
"access": "READ",
"allResources": true
},
"quota": {
"requests": { "used": 0, "limit": 50000, "remaining": 50000 },
"events": { "used": 0, "limit": 20000, "remaining": 20000 },
"ratePerMinute": 60
}
}
然后列出你的存储桶和某个文件夹中的文件:
curl https://api.nubbo.app/v1/buckets \
-H "Authorization: Bearer nbk_your_key"
curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=invoices/" \
-H "Authorization: Bearer nbk_your_key"
列表返回 data 和 nextCursor。要获取下一页,在 cursor 中发送该值。当 nextCursor 为 null 时,就没有更多内容了。

第 3 步:参考文档
在 设置 › API 中点击 查看文档,或打开 api.nubbo.app/v1/docs。那里列出了每个资源及其字段和示例。OpenAPI 文档位于 api.nubbo.app/v1/openapi.json。

上传和下载
文件不经过 Nubbo。要上传文件,先用 POST /v1/buckets/{bucketId}/uploads 发起上传,把文件发送到返回的预签名地址,再用 POST /v1/uploads/{uploadId}/complete 完成。要下载文件,用 POST /v1/files/{fileId}/download-link 获取链接,然后从你的服务商下载。
限额
| Pro | 团队 | |
|---|---|---|
| 每个密钥每分钟请求数 | 60 | 120 |
| 每月请求数 | 50,000 | 100,000 + 每个席位 10,000 |
| 每月触发事件数 | 20,000 | 50,000 + 每个席位 5,000 |
配额属于空间,并在每个计费周期重置。GET /v1/me、触发器的轮询以及 401、429 和 5xx 响应不计为请求。触发器每投递一个事件,计为一个触发事件。每个响应都带有 X-RateLimit-Remaining 和 X-Nubbo-Quota-Requests-Remaining 响应头,设置 › API 会显示本周期的用量。

如果出现问题
API_KEY_INVALID、API_KEY_REVOKED或API_KEY_EXPIRED:密钥无效、已被撤销或已过期。检查请求头或创建新密钥。API_PLAN_REQUIRED:密钥所属空间不包含 API。API 包含在 Pro 和团队套餐中。API_KEY_READ_ONLY:密钥为只读。请创建一个读写密钥。API_RATE_LIMITED:此密钥的请求过多。等待Retry-After中的秒数后再试。API_QUOTA_EXCEEDED:空间已用完本月限额。details.resetsAt会告诉你何时重置。
每个错误都带有 requestId。联系我们时请附上它。
了解更多关于 Nubbo API 的信息。如果不想写代码,请按照 Zapier、n8n 或 Make 指南操作。如果想在 AI 助手中使用,请查看如何 将 Nubbo 连接到 Claude、ChatGPT 或 Cursor。
常见问题
哪些套餐包含 API?
Pro 和团队。使用免费或 Personal 套餐时,请求会返回 API_PLAN_REQUIRED。
我能用 API 读取加密文件吗?
不能。加密内容显示时没有名称、路径、大小或类型,对它的任何更改都会被拒绝并返回 API_ENCRYPTED_CONTENT。
如果网络故障后我重复发送请求,会怎样?
在 POST 和 PATCH 请求中发送 Idempotency-Key 请求头。24 小时内重复同一请求会返回第一次的响应,不会重复创建任何内容。
API 会在不通知的情况下变更吗?
不会。不兼容的变更会以 /v2 发布,/v1 至少保留 12 个月,并带有 Deprecation 和 Sunset 响应头。
来源
步骤已对照以下页面核实。