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: true の OpenAPI 仕様、そのレスポンスには Deprecation ヘッダー（RFC 9745）と Sunset ヘッダー（RFC 8594）に旧動作の終了日が記載され、変更はリリースノート.

レート制限

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

API キーあたり毎分 2,000 リクエスト
バンドルアップロードルートでは、API キーあたり毎分 20,000 リクエスト
IP アドレスあたり 15 分以内に無効な API キーが 20 回を超えると、その 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 秒以内に同じデバイスを同じチャンネルに 2 回以上設定すると、429 レスポンスが返されます。1 秒あたりの制限がリセットされた後は、別のチャンネルへの切り替えが可能です。
さらに、アプリと IP アドレスごとに 1 分あたり 1000 回のチャンネルリクエストという制限が適用されます。

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

レスポンス形式

すべてのレスポンスは JSON 形式です。成功したレスポンスには通常、 data オブジェクトまたは status フィールドが含まれます。エラーのレスポンスには機械可読な error code、人間が読める message、および任意の moreInfo 参照してください。

成功レスポンスの例:

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

エラーレスポンスの例:

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

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

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

API キー Capgo API に安全にアクセスするための API キーの生成、一覧表示、失効

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

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

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

デバイスアプリを実行中のデバイスをトラッキング・管理します。bundle（バージョン）と channel の割り当てを含む

Bundle アプリの bundle を処理します。bundle（バージョン）のアップロード、一覧表示、管理を含む

ベストプラクティス

エラーハンドリング: エラーレスポンスを常にチェックし、適切に処理してください
レート制限レート制限に達した場合は、指数バックオフを実装してください
キャッシュ適切に応じてレスポンスをキャッシュし、API の呼び出しを減らしてください
バージョニング変更履歴を通じて API の変更を追跡してください

API の概要から先に進む

使用している場合 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) の実装の詳細については。

リリースの健全性、エラー、ネイティブビルド

以下の API の監視ネイティブおよびアップdaterの診断、メタデータ付きログ、ライブリリースダッシュボードの統計、ネイティブビルドのステータスとログスナップショット。これらの読み取りは、両方のアカウントMCPサーバーでも公開されています。