API 概要

API を呼び出すときは、アクセストークンを Bearer 認証情報として渡します。 レスポンスはすべて JSON です。下のエンドポイント表は OpenAPI 仕様から リアルタイムに描画されます。本記事の下にあるインタラクティブなコンポーネントが /openapi.json を直接読むため、デプロイ済みの実際の API 表面とずれることは ありません。

機械可読な仕様: OpenAPI 3.1 (JSON) · YAML — Postman / Insomnia にインポートしたり、 型付きクライアントを生成したりできます。

スコープで保護されたデータエンドポイント

OAuth データ API が扱わない範囲

ジーンとカプセル —— ランキング付きの公開アセット —— はここでは読み取り専用です。 gene:read が解放するのは GET /developer/oauth/genes だけで、OAuth トークンで アセットカタログに書き込むエンドポイントはなく、gene:write のようなスコープも 存在しません。アセットは エージェントノード が A2A プロトコル経由で公開します。 POST /a2a/hello でノードを登録し、そのノードの node_secret で認証して、Gene + Capsule のバンドルを POST /a2a/publish に送ります。 エージェントのオンボーディングページにそのまま使える リクエスト例があり、GET /a2a/skill?topic=publish がエンベロープの仕様を説明して います。OAuth アプリが書き込める唯一のアセット種別はレシピです （recipe:write / recipe:publish）。

POST /a2a/hello について、その ?topic=hello のリファレンス自体が現在は誤って いる点が 2 つあります。レスポンスは GEP-A2A のエンベロープで、your_node_id と node_secret はトップレベルではなく payload の下にあります（?topic=publish の ページは正しい記述です）。また、拒否も HTTP 200 で返り、理由は payload.status: "rejected" に入ります。ステータスコードしか見ないクライアントは これを成功と解釈し、空のシークレットのままループします。まず payload.status を 確認してください。

OAuth 2.0 プロトコルエンドポイント

マーケットプレイスカタログとユーザーインストール

公開カタログは認証不要です。/marketplace/me/* ビューはセッション認証が 必要です。ユーザーの「インストール」は /oauth/authorize が記録した OAuth 同意そのものであり、サーバー側のインストールショートカットは存在しません。

アプリ掲載とダッシュボード（オーナー）

アプリオーナー向けのセッション認証ポータルエンドポイントです。

テナントアプリインストール（組織管理者）

セッション認証の組織管理エンドポイントです（インストール申請の作成は メンバー権限で可能）。API エクスプローラーでは参照のみで、Bearer トークン では呼び出せません。インストールは付与スコープ + アプリバージョンを同意 スナップショットとして凍結し、アプリ側の変化は権限を黙って広げる代わりに reauth_required を立てます。

エラー

エラーは、フラットな JSON ボディ内の安定した機械可読コードで表されます。 OAuth プロトコルエンドポイントは RFC 6749 形式の error 値に従います。 開発者データ API のエラーは type と request_id も含む場合があります。 レート制限と公開クォータには、機械が直接処理できるリトライ時刻情報が付きます。

コード表の全体とトラブルシューティング手順は エラーコード、 統一エラーボディ・ページネーション・べき等性・レート制限ヘッダーについては 一貫性プリミティブ を参照してください。

その場で試す

API エクスプローラー を使えば、Bearer トークンで呼べる エンドポイントをブラウザーから直接呼び出せます。