ガイド

Nubbo APIを使い始める

ゼロから最初のリクエストまでわずか数分。APIキーを作成して、自分のコードからストレージの管理を始めましょう。

Nubbo APIは、自分のコードからバケットを扱うためのREST APIです。ファイル、フォルダ、リンク、ファイルリクエスト、ギャラリー、ラベル、プロジェクト、オートメーションを操作できます。このガイドでは、キーを作成し、curlで最初のリクエストを送ります。

できること

  • 自分のプログラムからNubboのスペースを管理。キーが参照できるのは、自分で選んだものだけです。
  • コードとストレージプロバイダーの間で直接アップロード、ダウンロード。
  • トリガーで新しいファイル、ファイルリクエストへのアップロード、アクティビティに反応。

始める前に

ProまたはチームプランのNubboアカウントと、curlを使えるターミナルが必要です。チームでは、APIキーを作成するのはオーナーまたは管理者です。

ステップ1: キーを作成する

  1. Nubboで 設定 › API(チームの場合は チーム › API)を開き、APIキーを作成 を押します。

  2. 名前を付けて、次を選びます。

    • アクセス: 読み取りのみ または 読み取りと書き込み。
    • 範囲: スペース全体 または 選択したバケットとプロジェクト。キーはここで選択したものだけを参照できます。
    • 有効期限: 30日、90日、1年、または 有効期限なし。期限の7日前にNubboからお知らせします。

    キーを作成 を押します。ご本人確認のため、Nubboがパスワードを求めます。2段階認証を有効にしている場合は、コードも求めます。

    アクセス、範囲、有効期限を設定するAPIキーを作成ウィンドウ アクセス、範囲、有効期限を設定するAPIキーを作成ウィンドウ
  3. キーをコピーして 保存しました を押します。キーは nbk_ で始まり、全体が表示されるのはこのときだけです。キーはサーバーや、キーを使うツールに保存してください。Webページには絶対に入れないでください。

    コピーできる状態のキーが表示されたAPIキーウィンドウ コピーできる状態のキーが表示されたAPIキーウィンドウ

ステップ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 なら、それ以上はありません。

GET /v1/meリクエストとそのレスポンスが表示されたターミナル GET /v1/meリクエストとそのレスポンスが表示されたターミナル

ステップ3: リファレンス

設定 › API で ドキュメントを見る を押すか、api.nubbo.app/v1/docs を開きます。各リソースのフィールドと例が載っています。OpenAPIドキュメントは api.nubbo.app/v1/openapi.json にあります。

curlの例が表示されたNubbo APIリファレンス curlの例が表示されたNubbo APIリファレンス

アップロードとダウンロード

ファイルはNubboを経由しません。アップロードするには、POST /v1/buckets/{bucketId}/uploads でアップロードをリクエストし、返された署名付きURLにファイルを送り、POST /v1/uploads/{uploadId}/complete で完了します。ダウンロードするには、POST /v1/files/{fileId}/download-link でリンクをリクエストし、プロバイダーから直接ダウンロードします。

上限

Proチーム
キーごとの1分あたりのリクエスト数60120
1か月あたりのリクエスト数50,000100,000 + 1席につき10,000
1か月あたりのトリガーイベント数20,00050,000 + 1席につき5,000

クォータはスペースごとで、請求期間ごとに更新されます。GET /v1/me、トリガーによる確認、401、429、5xxのレスポンスはリクエストとしてカウントされません。トリガーが届けるイベントは、1件ごとにイベントとしてカウントされます。各レスポンスには X-RateLimit-Remaining ヘッダーと X-Nubbo-Quota-Requests-Remaining ヘッダーが含まれ、設定 › API で期間中の使用量を確認できます。

Nubbo設定に表示された期間中のAPI使用量 Nubbo設定に表示された期間中の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ヘッダー付きで維持されます。

出典

手順は以下のページで確認しています。