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 標頭。
資料來源
步驟已對照以下頁面核實。