Plugins APIでClaude Enterpriseのプラグイン配布を管理する

Plugins APIは、Claude Enterpriseの組織にあるプラグインを一覧し、CIからアップロードし、メンバーに配るバージョンを選び、誰に使わせるかを決めるためのAPIです。claude.aiの管理画面でやっていた操作を、パイプラインから呼べる形にしたものと考えると掴みやすくなります。

この記事では、先にエンドポイントとスコープの全体像を押さえ、次に配布版の「固定(ピン留め)」と切り替え、グループ別の提供設定、リリースパイプラインとセキュリティ棚卸しの組み方へ進みます。プラグイン自体の作り方はClaude Codeプラグイン完全ガイド、claude.ai側の機能はClaude.aiのプラグイン機能が扱っています。

Plugins APIで何ができて、何ができないか

Plugins APIは18のエンドポイントを5つのリソースに分けています。

対象外もはっきりしています。claude.aiのスキルエディタで作る単体のスキルは、このAPIの一覧に出ず、作成もできません。Anthropicが公開しているプラグインも一覧の対象外で、その利用状況はAnalytics APIで見ます。マーケットプレイスそのものの作成・Gitリポジトリとの接続・削除は、APIではなくclaude.aiで行います。

利用条件は次のとおりです。

• Claude Enterpriseプランの組織であること。Claude Platform(Console)の組織と、HIPAA対応を有効にした組織では使えません
• ベータ版であり、全リクエストにanthropic-beta: ce-plugins-2026-09-01ヘッダーが必要です。付け忘れると、エンドポイントが存在しないときと同じ404が返ります
• x-api-keyにはAdmin APIキーを渡し、anthropic-version: 2023-06-01も付けます。キーは組織のプライマリオーナーが作成します

Python、TypeScript、C#、Go、Java、PHP、Rubyの各SDKはclient.beta.organization配下にこれらを持ち、antCLIではant beta:organizationで呼べます。SDKとCLIはanthropic-versionとanthropic-betaを自動で付けるため、ヘッダーの付け忘れによる404が起きるのは素のHTTPで呼ぶときです。

スコープの選び方 — 読みと書きは別のキー

スコープは4種類あり、write:pluginsは読み取りを含みません。アップロードして中身を読み戻す連携なら、両方を持つキーが要ります。

運用では、CIのアップロード用にwrite:pluginsとread:plugins、棚卸しジョブには読み取りだけのキーを分けておくと、漏えい時の影響を小さくできます。監査ツールにread:org_auditを渡す場合は、マーケットプレイス検証が使えない点に注意が必要です。

もうひとつの特徴は、組織の境界です。read:pluginsとwrite:pluginsのキーは、作成した組織しか読み書きできません。親組織の下に複数のClaude組織がぶら下がる企業では、親のプライマリオーナーが全リンク組織向けに作ったread:org_auditまたはread:compliance_org_dataのキーだけが、organization_idクエリパラメーターで配下の組織を読めます。書き込みはorganization_idを受け付けません。

メンバー個人のマーケットプレイスにあるプラグインのファイルは、読み取り系のスコープであればダウンロードできます。管理画面に表示されないファイルも含まれます。このダウンロードはCompliance APIのActivity Feedにclaude_plugin_archive_accessedとして記録され、キー・プラグイン・バージョン・メンバーが特定されます。組織所有のプラグインのダウンロードは記録されません。

所有者で変わる操作範囲

プラグインにはowner.typeがあり、organizationかuserのどちらかです。操作できる範囲はここで分かれます。

マーケットプレイスのsourceがmanualなら、プラグインはアップロードで入ります。github・gitlab・public_gitはリポジトリから同期されるため、APIで足したり消したりしても次の同期で元に戻ります。変えたいときはリポジトリ側を変更します。

メンバーが組織を抜けても、そのメンバーのプラグインは一覧に残ります。owner_user_idで絞り込めるので、退職者のコンテンツを確認して削除する手順を組めます。アカウントが削除されると一覧から消えます。

配布版の仕組み — latestとservedは別物

運用で最も混乱しやすいのが、バージョンの2つのポインターです。

• latest_version_id: 最新のバージョン
• served_version_id: メンバーに配られているバージョン

アップロードのたびに、不変のバージョンが1つ増えます。claude.aiからでも、API経由でも、Git同期でも同じです。ピン留め前の既定(served_version_pinned: false)では、配布版は最新版に追従します。

POST /v1/organizations/plugins/{plugin_id}でserved_version_idを指定すると、そのプラグインはピン留めされます。以降は新しいバージョンをアップロードしてもlatest_version_idだけが進み、メンバーはピンしたバージョンのままです。ロールバックなら古いバージョンのID、ロールフォワードなら新しいバージョンのIDを指定します。手順はどちらも同じです。

注意点が2つあります。

1. ピン留めは今のところ解除できません。APIでもclaude.aiでも戻せないため、「ピンしてから全リリースを昇格させる」運用に入る前に、その覚悟があるかを決めておく必要があります
2. 2つのIDが一致するまでポーリングする実装は避けます。スキャンが失敗した場合などは、一致しないままになることがあります

コンテンツスキャンが有効なときの落とし穴

組織設定でコンテンツスキャンが有効だと、新しく保存したバージョンがスキャンされ、結果がcontent_scanに入ります。配布されるのは、配布版のスキャンがcompletedでpassかwarnのときだけです。スキャン中や失敗時は、前のバージョンが代わりに配られることはなく、プラグインそのものがメンバーから使えなくなります。

ここで、API経由のアップロードには固有の挙動があります。claude.aiで保存したバージョンはスキャンが終わるまで配布を待ちますが、API経由でアップロードしたバージョンは待ちません。ピン留めされていないプラグインにAPIでアップロードすると、そのバージョンがすぐ配布版になり、スキャンが通るまでメンバーはプラグインを失います。スキャンが失敗すれば、そのままです。

回避策は、先にプラグインをピン留めしておくことです。ピン留め後は、アップロードしたバージョンはスキャンの結果が出るまで配られません。昇格のAPIも、スキャンが走っているバージョンには409 scan_pending、失敗したバージョンには400 scan_failedを返します。

なお、ピンのためにAPIを呼ぶ最初の1回も、現在のバージョンのスキャンが終わるまでは409 scan_pendingを返します。warnは受け付けられます。

リリースパイプラインから配布する

CIで毎ビルドをアップロードし、昇格のタイミングだけパイプラインが握る構成の手順です。

初回のアップロードは、次のようにfiles[]にzipを渡します。marketplace_idを省略すると、組織のライブラリマーケットプレイスに入ります。これは組織所有のmanualマーケットプレイスで、最初のアップロード時に作られます。

curl -X POST "https://api.anthropic.com/v1/organizations/plugins" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: ce-plugins-2026-09-01" \
  -F "files[]=@dist/sales-toolkit.zip" \
  -F "release_notes=First release"

2回目以降のバージョン追加は、エンドポイントを/plugins/{plugin_id}/versionsに変えるだけです。アップロードしたマニフェストのnameは、既存プラグインのnameと一致していなければなりません。昇格はJSON本文で行います。

curl -X POST \
  "https://api.anthropic.com/v1/organizations/plugins/$PLUGIN_ID" \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: ce-plugins-2026-09-01" \
  -d '{"served_version_id": "'"$NEW_VERSION_ID"'"}'

アップロードの要件

アップロードの規則はclaude.aiと共通で、同じアーカイブが両方で通ります。

• .zipまたは.pluginのアーカイブ1つ、または個別ファイルの集合
• .claude-plugin/plugin.jsonがちょうど1つあり、nameを宣言していること。マニフェストのないSKILL.mdだけでは拒否されます
• nameは小文字・数字・ハイフンで64字まで。大文字・空白・アンダースコアは不可です
• displayNameは64字まで、descriptionは500字まで、release_notesは5,000字までです
• 最上位のbin/配下にファイルを置けません。入れ子のzipも不可です
• 本文と展開後のサイズは各200 MBまで、ファイル数は5,000まで、パスの深さは12までです
• マーケットプレイス1つに入れられるのは500件までです

上限値のうちファイル数と500件の上限は、今後引き上げられる可能性があります。

失敗したときの再試行

どのエンドポイントもIdempotency-Keyを受け付けません。配布版の変更・インストール設定の設定・マーケットプレイスの既定の設定は、繰り返しても安全です。一方、削除と設定の削除は、2回目に404になります。

エラーを返したアップロードは何も保存しません。例外は503のregistration_pendingで、ファイルは保存されたもののスキル登録が終わっていない状態です。再アップロードで完了しますが、同一内容のバージョンがもう1つ増えます。

• プラグインの新規作成で出た場合は、プラグインは作成済みです。作成を再送せず、details.plugin_idのプラグインに対してバージョンとして同じファイルをアップロードします
• バージョンの作成で出た場合は、応答のx-should-retryがtrueのときだけ同じリクエストを再送します

応答を取りこぼした新規作成は、再送すると409 plugin_name_takenが返り、details.plugin_idで既存のプラグインが分かります。バージョンの作成を取りこぼした場合は、再送すると同一内容のバージョンが2つできます。これを避けるため、アップロードの前にlatest_version_idを記録し、応答が失われたらプラグインを読んで、値が変わっていないときだけ再送します。

グループ別の提供設定で段階展開する

誰が使えるかはインストール設定で決めます。値は4つで、メンバーから見える状態が決まります。

設定の単位は、組織全体と、RBACグループ単位です。メンバーが受け取る値は次の順で決まります。

1. 組織全体の値は、プラグイン自身の組織全体設定、なければマーケットプレイスの既定、それもなければnot_available
2. どのグループ設定にも該当しないメンバーは、組織全体の値
3. 設定を持つグループに1つ以上所属するメンバーは、組織全体の値ではなく、所属グループの設定のうち最も許容度が高いもの(required、auto_install、available、not_availableの順)

グループ設定は組織全体の値に足されるのではなく、置き換えます。組織全体がrequiredでパイロットグループがavailableなら、パイロットのメンバーはavailableになります。

APIで作ったプラグインは、設定を何も持たずに始まります。マーケットプレイスの既定が未設定ならnot_availableのままなので、アップロードしただけでは誰にも見えません。

パイロットから全社へ

段階展開の流れは次のとおりです。

1. GET /v1/organizations/rbac_groupsでパイロット用グループのIDを取る。このエンドポイントにはread:rbac_groupsスコープが要り、全リンク組織向けに作ったキーが必要です
2. 組織全体をnot_availableに保ったまま、グループにauto_installを設定する。パイロットのメンバーだけが受け取ります
3. 終了時に組織全体の値を設定し、そのあとグループの設定を削除する

設定はPOST /v1/organizations/plugins/{plugin_id}/installation_settings/{target}で行い、{target}にはorganizationかグループIDを入れます。

curl -X POST \
  "https://api.anthropic.com/v1/organizations/plugins/$PLUGIN_ID/installation_settings/$GROUP_ID" \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: ce-plugins-2026-09-01" \
  -d '{"installation_preference": "auto_install"}'

write:pluginsは作成した組織にしか効かないため、複数の組織を束ねる企業では、手順1用のキーと手順2・3用のキーが別になることがあります。プラグインを持つ組織で、両方のスコープを持つキーを作るのが簡単です。

組織全体の設定を入れると、そのプラグインはマーケットプレイスの既定を引き継がなくなります。値が既定と同じでも、以降の既定の変更には追随しません。引き継ぎに戻したいときは、組織全体の設定を削除します。グループ設定は影響を受けません。

同じプラグインへの設定の書き込みは、1件ずつ送ります。同時に送ると、一部が503(x-should-retry: true)で返ります。1〜2秒待って再送すれば問題ありません。

可逆な取り下げと、削除の違い

DELETE /v1/organizations/plugins/{plugin_id}は、プラグインとその全バージョンを恒久的に削除します。元に戻せず、バージョン単位の削除もありません。

一時的に止めたいだけなら、組織全体の設定をnot_availableにします。グループ設定も、削除するかnot_availableにしなければなりません。グループ設定が組織全体の値を上書きするためです。メンバー所有のプラグインは、削除以外の方法で取り下げられません。

セキュリティ棚卸しを夜間ジョブにする

プラグインが増えると、「どれがメンバーのPCや外部サービスに触れるのか」を把握する必要が出ます。一覧のレスポンスにあるreachが、そのためのフィールドです。

componentsの一覧が空でも、privilegedになり得ます。モニターやLSP、アプリ設定はcomponentsに出ないためです。保存時点で判定できなかったバージョンや、記録前の古いバージョンはnullで、未分類として扱います。

夜間ジョブは次の順で組めます。

1. GET /v1/organizations/plugins?limit=100をnext_pageがnullになるまで読み切る
2. reachがremote、またはcontent_scan.assessmentがfailかunknownのプラグインに印を付ける
3. 印を付けたプラグインの配布版のアーカイブを、/versions/{version}/contentでダウンロードしてレビューする

スキャンの結果はupdated_atを動かさないため、reachとcontent_scanは毎回の実行で読み直します。ページ送りはカーソル方式で、limitの既定は20、プラグインの上限は100です。ページが空でもnext_pageが残っていることがあるので、返された件数でなくnext_pageで終了を判定します。

一覧の読み切りは、削除の検知にも要ります。Gitの同期やアカウント削除で消えたプラグインは、イベントなしで一覧から消えるためです。

curl -s "https://api.anthropic.com/v1/organizations/plugins?limit=100" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: ce-plugins-2026-09-01" \
  | jq -r '.data[] | select(.reach == "remote") | .id'

アーカイブは、スキャン結果に関係なく取得できます。メンバーから見えない状態のバージョンも中身を調べられ、組織所有でmanualのプラグインなら、取得したzipを現行の要件を満たす限り、そのまま新しいバージョンとして再アップロードできます。

取り込む前にマーケットプレイスを検証する

Gitのマーケットプレイスをclaude.aiに接続する前に、同期したら何が起きるかを検証APIで確認できます。

• POST /v1/organizations/plugin_marketplaces/validate_repository: github.comの公開リポジトリのURLを受け取る。refでブランチか40桁のコミットSHAを指定できる
• POST /v1/organizations/plugin_marketplaces/validate_archive: マーケットプレイスのディレクトリをzipにして送る。上限は32 MB

レポートには、marketplace.jsonが正しい形式か、どのプラグインが除外されるか、一部が欠けて同期されるかが入ります。中身に問題があってもHTTPエラーにはならず、valid: falseで成功します。リポジトリが読めない場合も同じです。検証は読み取りとして数えられ、組織あたり毎分10回の追加上限があります。1回の検証に最大120秒かかることがあるため、クライアントのタイムアウトは120秒より長くします。このAPIはread:pluginsかwrite:pluginsのどちらかで通り、read:org_auditでは通りません。

マーケットプレイスの既定の提供設定は、POST /v1/organizations/plugin_marketplaces/{marketplace_id}のdefault_installation_preferenceで変えます。個別設定を持たないすべてのプラグインに、あとから追加されるものを含めて反映されます。一度設定した既定はnullに戻せません。

レート制限とActivity Feed

組織単位の上限は、読み取りが毎分300回、書き込みが毎分60回で、組織のすべてのキーで合算します。他のAdmin APIの上限とは別枠です。上限を超えるか、一時的に受け付けられないときは429とretry-afterが返るため、待ってから再試行します。

書き込みはすべてCompliance APIのActivity Feedに残り、実行したAPIキーがapi_actorとして記録されます。配布版の変更はclaude_plugin_served_version_updated、インストール設定の変更はplugin_installation_preference_updatedです。マーケットプレイスの既定を変えるとmarketplace_updatedが1件だけ出て、プラグイン単位のイベントは出ません。

誰がいつ昇格したかを後から追えるので、ロールバックの原因調査に使えます。組織がカスタマー管理の暗号鍵(CMEK)を使っていると、鍵が使えない間は読み取りは通る一方、description・release_notes・componentsがnullになり、ダウンロードと書き込みは400になります。

導入時にまず決めること

APIの呼び方より前に、運用の取り決めを3つ決めておくと迷いません。

• ピン留めを前提にするか。前提にするなら、全ビルドを明示的に昇格する運用になり、元には戻せません
• コンテンツスキャンを使う場合、ピンなしのAPIアップロードで一時的にプラグインが外れてもよいか
• 提供設定の既定を、マーケットプレイスのnot_availableのままにするか

Admin APIでのメンバー管理はAdmin APIのシート・メンバー管理が扱っています。プラグインの導入後に実際の利用を測る段階では、前述のAnalytics APIが受け皿になります。

よくある質問

Claude TeamプランやConsoleの組織でも使えますか

使えません。Claude Enterpriseの組織が対象で、Claude Platform(Console)の組織とHIPAA対応を有効にした組織は含まれません。

メンバー所有のプラグインを配布版として管理できますか

できません。バージョンのアップロードと配布版の変更は403になります。管理者に残るのは、読み取り、ファイルのダウンロード、manualマーケットプレイスでの削除です。