API の概要

このプラグインのインストール手順と完全なMarkdownガイドを含むセットアッププロンプトをコピー

これはCapgo cloudの公開APIのドキュメントです。APIを使うと、組織、デバイス、チャンネル、bundleなどのCapgoリソースをプログラムから管理できます。RESTfulに設計されており、標準のHTTPメソッドを使用します。

認証

すべてのAPIエンドポイントには認証が必要です。リクエストを認証するには、APIキーを以下に追加してください: x-api-key ヘッダー、または Authorization: Bearer YOUR_API_KEY.

例:

curl -H "x-api-key: YOUR_API_KEY" https://api.capgo.app/organization/

API キーを取得 Capgo ダッシュボードで API キーを生成します

この authorization ヘッダーに生のキーを（ Bearer プレフィックスなし）含める方法も、レガシーな統合では引き続き利用可能ですが、 x-api-key は、セキュアなハッシュ化キーを含むすべてのキータイプにおいて推奨されるヘッダーです。

AIエージェントやその他のOAuthクライアントは、OAuth 2.0（PKCEを使用した認可 code および動的クライアント登録）を通じてキーを取得できます。発行元は https://capgo.app、メタデータ付き： https://capgo.app/.well-known/oauth-authorization-server。ユーザーは権限を付与する組織を選択します。アクセストークンは、Bearerトークンとして送信される Capgo API キーです。

バージョニング

API は日付によってバージョン管理されています。以下の capgo_api リクエストヘッダーを使用することで、特定のバージョンを固定できます：

curl -H "x-api-key: YOUR_API_KEY" -H "capgo_api: 2025-10-01" https://api.capgo.app/organization/

ヘッダーを指定しない場合はデフォルトのバージョンが取得されます。現在のバージョンは 2025-10-01。同一バージョン内での変更は、新しいエンドポイント、新しいオプションパラメータ、新しいレスポンスフィールドの追加といった非破壊的なものに限られます。破壊的変更は新しい日付のバージョンとしてリリースされるため、古い日付に固定しているクライアントは以前の挙動を維持できます。不明なバージョンや不正な形式のバージョンが指定された場合は、 400 unsupported_capgo_api_version または 400 invalid_capgo_api_version.

操作やフィールドの削除は破壊的変更となるため、新しい日付のバージョンでのみ行われます。現在、非推奨（deprecated）となっているものはありません。将来的に非推奨となった場合は、その操作に deprecated: true の OpenAPI仕様、そのレスポンスには Deprecation ヘッダー（RFC 9745）と Sunset ヘッダー（RFC 8594）に旧動作の終了日が含まれ、変更はリリースノート.

レート制限

API は、公平な利用を確保するためにレート制限を実装しています。現在の制限は次のとおりです：

API キーごとに毎分 2,000 リクエスト
bundle upload ルートでは API キーごとに毎分 20,000 リクエスト
IP アドレスごとに 15 分間で 20 個の無効な API キーが使われると、その IP は 15 分間ブロックされます

すべてのレスポンスは、クォータを次の RateLimit-Policy と RateLimit ヘッダー（IETFドラフト):

RateLimit-Policy: "apikey";q=2000;w=60
RateLimit: "apikey";r=1995;t=42

q がクォータ、 w が秒単位のウィンドウ、 r が残りのリクエスト数、 t ウィンドウがリセットされるまでの秒数です。制限を超えると、429 (Too Many Requests) レスポンスが返され、ヘッダーに Retry-After 秒単位の時間が表示されます。

デバイスのチャンネル変更

デバイスのチャンネル変更には API プラグインを使用しており、トライアルを含むすべてのプランに適用される個別の不正防止制限があります：

各チャンネル操作において、1デバイスあたり最大5リクエスト/秒まで可能です（set, get, delete、または list）。この制限は、アプリ、デバイス、および操作ごとに適用されます。
60秒以内に同じデバイスを同じチャンネルに複数回設定しようとすると、429レスポンスが返されます。秒単位の制限がリセットされた後は、別のチャンネルへの切り替えが可能です。
さらに、各アプリおよびIPアドレスに対して、1分あたり1,000リクエストのチャンネルリクエスト制限が適用されます。

これらの制限はアカウント全体に適用されるものではありません。チャンネルスイッチャーが最近選択したチャンネルに戻れる場合は、429レスポンスに含まれる retryAfterSeconds の時間が経過してから再試行してください。

レスポンス形式

すべてのレスポンスはJSON形式です。成功時のレスポンスには、通常以下のいずれかが含まれます。 data オブジェクト、または status フィールド。エラーレスポンスには、マシンリーダブルな error code と、人間が読みやすい message、およびオプションの moreInfo が含まれます。

成功時のレスポンス例:

{
  "status": "ok",
  "data": { ... }
}

エラー時のレスポンス例:

{
  "error": "invalid_apikey",
  "message": "Invalid apikey",
  "moreInfo": {}
}

利用可能なエンドポイント

組織組織の作成・管理、設定の更新、および組織レベルの構成管理

API キー Capgo API への安全なアクセスのための API キーの生成、一覧表示、および失効

メンバー組織メンバー、ロール、および権限の管理

統計アプリの使用状況、ストレージ、および帯域幅消費に関する詳細な分析へのアクセス

チャネルアプリのアップデートチャネル、bundle（バージョン）、およびアップデートポリシーの制御

デバイスアプリを実行しているデバイスを、bundle（バージョン）やchannelの割り当てを含めて追跡・管理します。

バンドル app bundleのアップロード、一覧表示、bundle（バージョン）の管理を行います。

ベストプラクティス

エラーハンドリング: エラーレスポンスを常に確認し、適切に処理してください。
レート制限: レート制限に達した場合は、exponential backoffを実装してください。
キャッシュ: API の呼び出し回数を減らすため、必要に応じてレスポンスをキャッシュしてください。
バージョニング: changelogでAPIの変更を確認できます

API Overviewから次へ進む

以下を使用している場合： API の概要 認証とアカウントフローを計画するには、以下と連携させてください @capgo/capacitor-social-login @capgo/capacitor-social-login の実装詳細については、 @capgo/capacitor-passkey @capgo/capacitor-passkey の実装詳細については、 @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric の実装詳細については、二要素認証 2要素認証の実装詳細については、 SSO (エンタープライズ) SSO (Enterprise) の実装詳細については、