外掛程式 API

外掛程式 API 可讓您執行下列操作：

• 盤點您 Claude Enterprise 組織中的「plugin」（外掛程式）
• 從您自己的管線發布外掛程式及新版本
• 選擇要向成員提供哪個版本
• 控制誰可以使用每個外掛程式
• 下載外掛程式檔案以供審查
• 在連接 Git「marketplace」（市集）之前先進行檢查

如需外掛程式使用情況報告（成員使用哪些外掛程式和技能，以及使用頻率），請參閱 Analytics API。

端點

此 API 在五種資源中提供 18 個端點：

Anthropic 發布的外掛程式不會列入清單；其使用情況由 Analytics API 回報。市集是在 claude.ai 中建立、連接到儲存庫及刪除的，而非透過此 API。

先決條件

• 您的組織必須使用 Claude Enterprise 方案。
• 您的主要擁有者需在 claude.ai > 組織設定 > API 中建立具有 read:plugins 範圍、write:plugins 範圍或兩者兼具的 Admin API 金鑰。請參閱為 Claude Enterprise 組織建立金鑰。
• 每個請求都帶有三個標頭：x-api-key、anthropic-version: 2026-10-21 和 anthropic-beta: ce-plugins-2026-09-01。

在 Python、TypeScript、C#、Go、Java、PHP 和 Ruby 中，SDK 將這些端點公開於 client.beta.organization 之下，而 ant CLI 則將其公開於 ant beta:organization 之下；它們會為您傳送 anthropic-version 和 anthropic-beta 標頭。本頁的範例會從 ANTHROPIC_API_KEY 環境變數讀取 Admin API 金鑰。當 SDK 或 CLI 為您擷取更多頁面時，limit 設定的是每頁大小，而非總數（請參閱分頁）。

API 金鑰屬於組織，在建立者離開後仍會繼續運作。請勿分享金鑰，也不要將其簽入原始碼控制系統。

快速入門

列出您組織自有市集中的外掛程式，最新的排在最前面：

client = anthropic.Anthropic()

plugins = client.beta.organization.plugins.list(owner_type="organization", limit=20)

# 視需要自動擷取更多頁面。
for plugin in plugins:
    print(f"{plugin.id}: {plugin.name}")

{
  "data": [
    {
      "type": "plugin",
      "id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
      "name": "sales-toolkit",
      "display_name": "Sales Toolkit",
      "description": "Account research and call prep for the sales team.",
      "served_version_id": "pluginver_01Km7tL4pR9xF5sU2zV3jP6q",
      "served_version_pinned": true,
      "latest_version_id": "pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p",
      "manifest_version": "1.4.0",
      "owner": { "type": "organization" },
      "marketplace_id": "marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r",
      "created_by": { "type": "api_actor", "api_key_id": "apikey_01Nq9vN6rT2zH7uW4bX5mR8s" },
      "organization_installation_preference": "available",
      "organization_installation_preference_inherited": true,
      "content_scan": { "status": "completed", "assessment": "pass", "reason": null },
      "components": [
        {
          "type": "skill",
          "name": "account-research",
          "description": "Researches a customer account before a call."
        },
        { "type": "mcp_server", "name": "crm", "description": null }
      ],
      "reach": "remote",
      "created_at": "2026-09-01T17:04:11Z",
      "updated_at": "2026-09-15T14:12:30Z"
    }
  ],
  "next_page": "page_xK9f2LqT7vNw3pRzBd8sHy"
}

在此範例中，外掛程式被釘選到較早的版本：較新的版本（latest_version_id）已儲存，但尚未提供。

範圍

一把金鑰可以帶有多個範圍。上傳外掛程式後再將其讀回的整合，需要同時具備 read:plugins 和 write:plugins。本頁凡提到端點需要 read:plugins 範圍之處，具有 read:org_audit 或 read:compliance_org_data 的金鑰也同樣適用。

存取成員的外掛程式檔案

這些讀取範圍（read:plugins、read:org_audit 和 read:compliance_org_data）中的每一個，都可以下載成員個人市集中外掛程式的檔案，包括 claude.ai 管理設定中未顯示的檔案；而綁定到您上層組織的 read:org_audit 或 read:compliance_org_data 金鑰，可以透過傳遞 organization_id，在其下任何可存取此 API 的組織中執行此操作（請參閱讀取同一上層組織下的其他組織）。每次此類下載都會在 Compliance API Activity Feed 上記錄一個 claude_plugin_archive_accessed 事件，識別金鑰、外掛程式、版本和成員（請參閱 Activity Feed 事件）。組織擁有之外掛程式的下載不會被記錄。

讀取同一上層組織下的其他組織

read:plugins 和 write:plugins 金鑰只能讀取和寫入其建立時所屬的組織。有些公司有數個 Claude 組織連結在同一個上層組織之下。為所有連結組織建立的 read:org_audit 或 read:compliance_org_data 金鑰也可以讀取任何可使用此 API 的連結組織。若要讀取某個組織，請在本頁任何 GET 端點的 organization_id 查詢參數中傳入其 ID。此 ID 為 claude.ai 設定中顯示的組織 UUID（也接受其帶有 org_ 前綴的形式）。若未提供此參數，金鑰會讀取其建立時所屬的組織。沒有自身所屬組織的金鑰必須一律傳入 organization_id。404 表示指定的組織不在金鑰的上層組織之下，或該組織無法使用此 API；若值既不是 UUID 也不是 org_ ID，則會傳回 400。任何其他金鑰若指定了非其所屬的組織，會收到 404。寫入操作不接受 organization_id。

關鍵概念

外掛程式與元件

外掛程式是為您組織成員擴充 Claude 功能的套件。它包含下列元件的任意組合：

每個外掛程式在 .claude-plugin/plugin.json 都有一個「manifest」（資訊清單）。資訊清單的 name 會成為外掛程式的 name：一個在其市集內唯一的小寫識別碼。

市集

市集是外掛程式的容器。每個市集都有一個擁有者和一個來源。

• 擁有者。 組織擁有其市集。每位成員也可以擁有個人市集。
• 來源。 manual 表示外掛程式是透過上傳而來，可在 claude.ai 中上傳，或者（對於組織市集）透過此 API 上傳。github、gitlab 和 public_git 表示外掛程式是從擁有者連接的 Git 儲存庫同步而來。同步的市集無法上傳任何內容，此 API 也無法刪除其外掛程式，因為下一次同步會撤銷任一變更。請改為變更儲存庫。

您組織的程式庫市集（library marketplace）是組織擁有的 manual 市集，當您未指定市集時，上傳內容會進入此市集。它會在第一次有內容上傳到其中時建立。

組織擁有與成員擁有的外掛程式

外掛程式的 owner.type 說明它位於誰的市集中：

• organization：您可以透過此 API 管理它，但位於從 Git 同步之市集中的外掛程式無法在此接收上傳或被刪除。
• user：它位於某位成員的個人市集中。您可以讀取其詳細資訊並下載其檔案，若其市集為 manual，也可以刪除它。上傳版本和選擇提供版本會傳回 403。分享僅由成員在 claude.ai 中管理。

將成員從組織中移除並不會移除其外掛程式。它們會以該成員的 user_id 保留在清單中，owner_user_id 篩選器仍能找到它們，因此您可以審查並移除已離開成員的內容。當成員的帳戶被刪除時，它們才會從清單中移除。

版本與提供版本

每次上傳都會建立一個新的、不可變的版本，無論它來自此 API、claude.ai 或 Git 同步。外掛程式有兩個指向其版本的指標：

• latest_version_id：最新的版本
• served_version_id：向成員提供的版本

根據預設，served_version_pinned 為 false：「served version」（提供版本）通常會跟隨最新版本。當內容掃描開啟時，在 claude.ai 中儲存的版本可能會等待其內容掃描：該版本會被儲存，但不會立即提供。本頁僅將「等待」用於在 claude.ai 中儲存的版本，而不用於成員或管理員發布到外掛程式中的版本。在掃描開啟期間，等待中的版本只有在其 content_scan 顯示 completed 且結果為 pass 或 warn 時才會被提供。當某個版本正在等待時，served_version_id 所指的版本會早於 latest_version_id。請勿輪詢直到兩個 ID 相符：它們可能會一直不同，例如在掃描失敗時。

使用 POST /v1/organizations/plugins/{plugin_id} 選擇版本會釘選（pin）外掛程式（served_version_pinned: true）。管理員在 claude.ai 中選擇版本，或接受成員發布到該外掛程式的請求，也會產生相同效果。從那時起，新的上傳會被儲存並推進 latest_version_id，但成員會持續使用釘選的版本，直到您將 served_version_id 指向另一個版本。兩個指標不同的外掛程式，表示有一個已儲存但未提供的版本。

這讓發布管線可以上傳每個建置、進行測試，然後再推廣它。若要讓您的管線決定每個建置何時被提供，請將 served_version_id 設為外掛程式目前的版本，藉此「pin」（釘選）外掛程式一次；從那時起，推廣每個您想提供的建置即可。在內容掃描開啟時，若目前版本的 content_scan 顯示 processing，首次釘選會傳回 409 scan_pending；若掃描顯示 fail、unknown 或 errored，則會傳回 400 scan_failed（warn 可被接受）。已釘選的外掛程式無法取消釘選，無論在此處或在 claude.ai 中皆然。

若要回復，請將 served_version_id 設為較早的版本。以相同方式向前推進。

這些規則描述的是組織擁有的外掛程式。成員擁有之外掛程式的提供版本由其擁有者在 claude.ai 中控制。

安裝設定

「Installation settings」（安裝設定） 決定誰可以使用組織擁有的外掛程式。每項設定有四個值之一，存放在名為 installation_preference 的欄位中（在外掛程式和市集物件上，則為 organization_installation_preference 和 default_installation_preference）：

外掛程式可以擁有一項組織範圍的設定，以及每個群組各一項設定（即在使用者管理中管理的群組，屬於角色型存取控制）。成員依下列規則取得值：

1. 全組織值是外掛程式自身的全組織設定（若有），否則為其市集的預設值，再否則為 not_available。外掛程式會在 organization_installation_preference 中回報此值，當該值來自市集預設值時，organization_installation_preference_inherited: true。
2. 不屬於任何對該外掛程式持有設定之群組的成員，會取得全組織值。
3. 屬於一個或多個持有設定之群組的成員，則改為取得這些群組設定中最寬鬆的一個，寬鬆程度依序為 required、auto_install、available、not_available。

群組的設定會為其成員取代全組織值，而非疊加於其上。例如，若全組織值為 required，而試行群組持有 available，則試行群組的成員取得 available。當您將外掛程式從試行群組推廣至整個組織時，請設定全組織值，然後移除該群組的設定。設定全組織值會使外掛程式不再繼承其市集預設值；移除全組織設定會讓外掛程式回到該預設值。

透過此 API 建立的外掛程式一開始沒有自己的設定，因此會繼承其市集的預設值：除非有人設定了預設值，否則為 not_available。刪除群組會從每個外掛程式中移除該群組的設定。

分享

「Shares」（共用） 決定誰可以使用成員擁有的外掛程式。擁有者在 claude.ai 中將其與所有成員、某個群組或指定的成員共用。此 API 可列出共用，但無法變更它們。

如果您的組織已在其 claude.ai 設定中關閉某種分享，該類型的分享仍會出現在列表中，但在該設定關閉期間不會授予任何人存取權；列表本身不會顯示該設定是否已關閉。

內容掃描

內容掃描是 claude.ai 中的組織設定。啟用時，新儲存的版本會被掃描（claude.ai 會豁免少數版本），結果會回報在 content_scan 中；未經掃描的版本（例如在啟用掃描之前儲存的版本）的值為 content_scan: null。使用客戶管理加密金鑰或零資料保留的組織不提供掃描功能。

在掃描開啟期間，只有當外掛程式提供版本的掃描為 completed 且結果為 pass 或 warn 時，成員才會獲得該外掛程式。當掃描為 processing 或 errored，或顯示 fail 或 unknown 時，外掛程式會對成員隱藏，且不會改為提供較早的版本。從未掃描過的版本（content_scan: null）會正常提供。

您透過此 API 上傳的版本永遠不會等待其內容掃描。當它成為提供版本時，成員將無法使用該外掛程式，直到其 content_scan 顯示 completed 且結果為 pass 或 warn。如果希望成員在新版本掃描期間保留目前版本，請先釘選外掛程式（請參閱版本與提供版本）。

當在 claude.ai 中儲存的版本等待其掃描時，提供的版本不會改變。當您透過 API 上傳的版本成為提供的版本時，任何等待都會結束：等待中的版本只有在有人選擇它時才會提供。若要查看等待中版本的掃描，請讀取該版本（請參閱列出外掛程式的版本）。

上傳後，content_scan.status 為 processing，結果會以非同步方式送達。請讀取該版本以查看結果；外掛程式物件只會顯示其提供版本的掃描。在掃描開啟期間，將提供版本變更為 content_scan 顯示 processing 的版本會傳回 409 scan_pending，而變更為掃描顯示 fail、unknown 或 errored 的版本則會傳回 400 scan_failed。

在 claude.ai 中被允許的失敗掃描

在 claude.ai 中，組織擁有者可以允許掃描失敗的版本。自訂角色可管理文件庫的成員也可以這麼做。此時，此 API 可能會將該掃描回報為 completed，結果為 warn，並附上失敗掃描的 reason。在此情況下，適用 warn 的規則：該版本可以提供給成員，您也可以將其設為提供版本。回應中沒有任何內容顯示它是被允許的，因此 warn 可能是警告，也可能是被允許的失敗掃描。允許掃描顯示 warn 的版本不會改變其 content_scan。當某個版本不再被允許時，此 API 會回報其最新完成掃描的結果。此時若提供版本的掃描顯示 fail 或 unknown，則會對成員隱藏。

觸及範圍

reach（觸及範圍）以單一值概括版本在成員電腦上及其他地方的觸及程度：

reach 會計入版本宣告的所有內容，包括 components 未列出的監控器、LSP 伺服器、工作流程和應用程式設定，因此 components 清單為空的版本仍可能是 privileged。對於在開始記錄元件之前儲存的版本，以及因其某個技能的 SKILL.md 或某個指令檔案無法讀取而無法判定觸及範圍的版本，其值為 null；請將 null 視為未分類。此值通常在版本儲存時依照當時的規則計算得出。因此，較舊的版本可能是 contained，而相同的檔案若在今天儲存則會是 privileged。

上傳要求

上傳遵循與 claude.ai 中外掛程式上傳相同的規則，因此兩處接受相同的封存檔。

• 上傳內容必須是一個 .zip 或 .plugin 封存檔，或是一組個別檔案。封存檔可以將所有內容包在一個頂層資料夾中。
• 它必須正好包含一個資訊清單，位於 .claude-plugin/plugin.json，且必須宣告 name。不含資訊清單的單獨 SKILL.md 會被拒絕。
• 頂層 SKILL.md 若其 frontmatter 宣告了外掛程式元件，會合併到資訊清單中；兩者都設定某值時，以 plugin.json 為準。資訊清單從該 SKILL.md 取得的 description 會截斷為前 500 個字元。
• name 可包含小寫字母（任何字母系統）、數字和連字號，最多 64 個字元。大寫字母、空格、底線和其他標點符號會被拒絕。
• displayName 最多 64 個字元，description 最多 500 個字元。
• 每個 SKILL.md 都需要有效的 YAML frontmatter，包含 name 和 description，兩者都不得包含 XML 標籤，例如 <example>。兩個技能或兩個命令不得同名。
• 任何檔案都不得位於頂層 bin/ 目錄下。
• 不得包含巢狀的 .zip 檔案。允許封裝的 MCP 伺服器（.mcpb、.dxt）。
• 檔案路徑必須是相對路徑、不得包含 ..，且只能使用字母、數字、空格和 _ . - / ( ) ,。
• 請求本文和解壓縮後的封存檔各自最多 200 MB；請求本文超過限制會傳回 413（request_too_large），而非 400。一次上傳最多 5,000 個檔案、路徑深度 12 層、路徑長度 472 個字元，檔案或資料夾名稱最多 255 個字元。
• ZIP 封存檔必須使用 DEFLATE 或 STORE 壓縮，且不得加密或包含符號連結。
• 當市集已容納 1,000 個外掛程式時，建立外掛程式的上傳會傳回 400。此 API 未列出的外掛程式也會計入，因此即使列出外掛程式顯示該市集中少於 1,000 個，仍可能達到此限制。Anthropic 可以提高 5,000 個檔案的限制。

範例工作流程

從發布管線發布每個建置

從 CI 上傳每個已標記的建置，並由管線決定建置何時被提供。

1. 使用 GET /v1/organizations/plugin_marketplaces?owner_type=organization 找到要上傳的市集，或省略 marketplace_id 以使用程式庫市集。
2. 首次發布時，使用 POST /v1/organizations/plugins 建立外掛程式。之後每次發布時，記錄外掛程式的 latest_version_id，然後使用 POST /v1/organizations/plugins/{plugin_id}/versions 上傳版本。如果上傳的回應遺失，請讀取外掛程式，並僅在 latest_version_id 未變更時重試（請參閱重試上傳）。
3. 若要在檢查每個新建置期間讓成員保持使用目前版本，請將 served_version_id 設為外掛程式目前的版本，以釘選外掛程式一次。從那時起，每次上傳都會被儲存但不會提供，且釘選無法撤銷：您想要提供的每個建置都需要執行步驟 5。
4. 啟用內容掃描時，輪詢 GET /v1/organizations/plugins/{plugin_id}/versions/{version} 直到 content_scan.status 不再是 processing，並僅在其為 completed 且結果為 pass 或 warn 時才升級。
5. 使用 POST /v1/organizations/plugins/{plugin_id} 和 {"served_version_id": "<the new version's ID>"} 升級建置。若要回復，請以相同方式傳送前一個版本的 ID。

將外掛程式推出給試行群組，再推出給所有人

1. 使用 GET /v1/organizations/rbac_groups 查詢試行群組的 ID。此呼叫需要 read:rbac_groups 範圍（請參閱使用者管理中的群組與角色）。接下來的步驟需要 write:plugins，它只作用於金鑰建立時所屬的組織，因此在擁有多個連結組織的企業中，請在持有該外掛程式的組織中建立一把金鑰並賦予兩個範圍，或在這些步驟中使用在該處建立的第二把金鑰。

2. 使用 POST /v1/organizations/plugins/{plugin_id}/installation_settings/{target} 為該群組設定專屬設定，例如 auto_install，其中 {target} 是該群組的 rbac_group_ ID，同時組織範圍的值維持為 not_available。只有該群組的成員會取得此外掛程式。

3. 試行結束時，使用下列呼叫設定組織範圍的值，然後移除該群組的設定，讓群組再次跟隨組織。設定組織範圍的值會使外掛程式不再繼承其市集預設值；之後移除組織範圍的設定會讓外掛程式恢復使用該預設值。

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

   client = anthropic.Anthropic()
   
   setting = client.beta.organization.plugins.installation_settings.set(
       "organization",
       plugin_id="plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
       installation_preference="required",
   )
   
   print(f"plugin_id: {setting.plugin_id}")
   print(f"installation_preference: {setting.installation_preference}")

   然後使用 DELETE /v1/organizations/plugins/{plugin_id}/installation_settings/{target} 移除該群組的設定，其中 {target} 是該群組的 ID。群組的設定會為其成員取代組織範圍的值，而非疊加於其上，因此殘留的 available 群組設定會讓這些成員維持在 available。

保持安全清單同步

執行每晚的工作，標記會觸及成員工作階段以外範圍的外掛程式，或內容掃描顯示 warn、fail 或 unknown 的外掛程式。

1. 逐頁瀏覽 GET /v1/organizations/plugins?limit=100，直到 next_page 為 null（請參閱分頁）。每次執行時都從該清單讀取每個外掛程式的 reach 和 content_scan：僅 content_scan 的變更（例如稍後才送達的結果）不會改變 updated_at。updated_at 通常會告訴您自上次執行以來，哪些外掛程式有新內容或新的提供版本（值得重新下載封存檔）。等待中的版本（請參閱版本與提供版本）會在成為提供版本時改變 updated_at，而不一定是在儲存時。若要察覺此情況，請將 latest_version_id 與上次執行的值進行比較。完整的重新列出也能偵測到移除，因為因 Git 同步或帳戶刪除而移除的外掛程式會在沒有事件的情況下消失。
2. 標記 reach 為 remote（宣告了 MCP 伺服器或 CLI）的每個外掛程式，或 content_scan.assessment 為 warn、fail 或 unknown 的外掛程式。warn 也可能是在 claude.ai 中被允許的失敗掃描。只有在您接受所有在該處被允許的失敗掃描時，才可略過 warn。這些欄位描述的是提供版本。若要同時檢查未提供的較新版本，請在 latest_version_id 與 served_version_id 不同時，列出該外掛程式的版本（請參閱列出外掛程式的版本）。
3. 對於每個被標記的外掛程式，使用 GET /v1/organizations/plugins/{plugin_id}/versions/{served_version_id}/content 下載提供版本的封存檔以供審查（請參閱下載版本的檔案）。也請依 ID 下載任何符合步驟 2 檢驗條件的未提供版本。
4. 若要在審查期間讓成員無法使用某外掛程式，請參閱刪除外掛程式，了解可逆（組織擁有）和永久的選項。

外掛程式

外掛程式物件描述位於您組織某個市集或成員個人市集中的外掛程式（快速入門的回應顯示了一個完整的物件）。其 display_name、description、manifest_version、content_scan、components 和 reach 描述的是其提供版本，因此一次列表呼叫即可顯示成員正在使用的內容。

description 不一定是資訊清單的。資訊清單從頂層 SKILL.md 取得的 description 會被截斷為前 500 個字元（請參閱上傳要求）。若 components 的技能 description 中（內容相同者只算一個）恰好只有一個以資訊清單的 description 作為前 500 個字元，API 會改為傳回該技能的 description。因此：

• 您讀取到的 description 可能超過 500 個字元，也就是上傳資訊清單的限制。若上傳的 plugin.json 設定了這樣的 description，會傳回 400。
• 在您下載的檔案中，.claude-plugin/plugin.json 可能有不同的 description，或完全沒有。

content_scan 物件：

缺少 plugin_ 前綴的 plugin_id 會傳回 400。帶有前綴但不在您組織清單中的 plugin_id 會傳回 404。

列出外掛程式

GET /v1/organizations/plugins 會列出您組織中的外掛程式，包括組織市集和成員個人市集中的外掛程式，依 created_at 遞減排序。可依 owner_type（organization 或 user）、owner_user_id（前綴為 user_ 的 ID，可找出某成員的外掛程式，包括該成員離開組織之後）、marketplace_id，以及 created_at[gte]、created_at[gt]、created_at[lte]、created_at[lt]（RFC 3339 時間戳記）進行篩選。篩選條件以 AND 組合。若 marketplace_id 或 owner_user_id 在您的組織中找不到符合項目，會傳回空白頁面，而非錯誤。回應的結構如快速入門中所示。需要 read:plugins 範圍。

client = anthropic.Anthropic()

plugins = client.beta.organization.plugins.list(owner_type="organization", limit=20)

# 視需要自動擷取更多頁面。
for plugin in plugins:
    print(f"{plugin.id}: {plugin.name}")

建立外掛程式

POST /v1/organizations/plugins 會在一次呼叫中建立組織擁有的外掛程式及其第一個版本；該版本會成為提供版本。本文為 multipart/form-data：files[] 可以是一個 .zip 或 .plugin 封存檔，或是每個檔案各一個部分，其中每個部分的檔案名稱為該檔案在外掛程式內的路徑（例如 .claude-plugin/plugin.json）。選用欄位為 marketplace_id（組織擁有的 manual 市集，或預設為您的程式庫市集，該市集會在首次使用時建立）和 release_notes（最多 5,000 個字元，會顯示在 claude.ai 的版本歷史記錄中，並在版本上傳回）。外掛程式的 name、display_name、description 和 manifest_version 來自上傳的檔案，且上傳內容必須符合上傳要求。當內容掃描開啟時，回應的 content_scan.status 為 processing，結果會以非同步方式送達。傳回外掛程式。需要 write:plugins 範圍。

上傳封存檔：

client = anthropic.Anthropic()

with open("dist/sales-toolkit.zip", "rb") as archive:
    plugin = client.beta.organization.plugins.create(
        files=[archive],
        release_notes="First release",
    )

print(f"id: {plugin.id}")
print(f"served_version_id: {plugin.served_version_id}")

{
  "type": "plugin",
  "id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
  "name": "sales-toolkit",
  "display_name": "Sales Toolkit",
  "description": "Account research and call prep for the sales team.",
  "served_version_id": "pluginver_01Km7tL4pR9xF5sU2zV3jP6q",
  "served_version_pinned": false,
  "latest_version_id": "pluginver_01Km7tL4pR9xF5sU2zV3jP6q",
  "manifest_version": "1.4.0",
  "owner": { "type": "organization" },
  "marketplace_id": "marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r",
  "created_by": { "type": "api_actor", "api_key_id": "apikey_01Nq9vN6rT2zH7uW4bX5mR8s" },
  "organization_installation_preference": "available",
  "organization_installation_preference_inherited": true,
  "content_scan": { "status": "processing", "assessment": null, "reason": null },
  "components": [
    {
      "type": "skill",
      "name": "account-research",
      "description": "Researches a customer account before a call."
    },
    { "type": "mcp_server", "name": "crm", "description": null }
  ],
  "reach": "remote",
  "created_at": "2026-09-01T17:04:11Z",
  "updated_at": "2026-09-01T17:04:11Z"
}

將個別檔案上傳到指定的市集。將每個檔案以其在外掛程式內的路徑附加（即 cURL 範例中的 ;filename= 後綴，以及 SDK 範例中的檔案名稱引數）；若檔案僅以其基本名稱傳送，將找不到資訊清單。TypeScript 和 Java SDK 以及 ant CLI 目前還無法以路徑附加檔案，因此這些範例改為將外掛程式以一個封存檔上傳到市集中：

client = anthropic.Anthropic()

# 使用 (filename, file) tuple 可保留每個檔案在外掛程式中的路徑；
# 若直接傳入檔案物件，則只會以其基本名稱傳送。
with (
    open(".claude-plugin/plugin.json", "rb") as manifest,
    open("skills/account-research/SKILL.md", "rb") as skill_md,
):
    plugin = client.beta.organization.plugins.create(
        files=[
            (".claude-plugin/plugin.json", manifest),
            ("skills/account-research/SKILL.md", skill_md),
        ],
        marketplace_id="marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r",
    )

print(f"id: {plugin.id}")
print(f"served_version_id: {plugin.served_version_id}")

除了違反上傳要求的上傳會傳回 400（請求本文超過 200 MB 則為 413），以及共通回應（當 marketplace_id 是成員的個人市集時會傳回 403；請參閱錯誤回應）之外，建立操作還可能因下列原因失敗：

取得外掛程式

GET /v1/organizations/plugins/{plugin_id} 傳回一個外掛程式。需要 read:plugins 範圍。

client = anthropic.Anthropic()

plugin = client.beta.organization.plugins.retrieve("plugin_01Hq3vX8kZcN2mB7pR4tY9wL")

print(f"id: {plugin.id}")
print(f"name: {plugin.name}")

變更提供版本

POST /v1/organizations/plugins/{plugin_id} 會變更組織擁有的外掛程式要向成員提供哪個版本。傳入較早的版本可進行回復，傳入較新的版本則可推廣已儲存但未提供的建置。這會釘選外掛程式，而已釘選的外掛程式無法取消釘選，無論在此處或在 claude.ai 中皆然（請參閱版本與提供版本）。唯一可更新的欄位是 served_version_id，且為必填。此變更會在回應傳回之前送達成員，且不會建立版本。當內容掃描開啟時，該版本必須是可以提供給成員的版本（請參閱內容掃描）。對已釘選的外掛程式傳入已提供的版本不會有任何變更；對未釘選的外掛程式傳入它則會將其釘選在該版本，因此之後的上傳將不再自動提供。釘選也會結束任何等待：正在等待其內容掃描的版本會保持儲存狀態，且只有在有人選擇它時才會被提供。傳回外掛程式。需要 write:plugins 範圍。

client = anthropic.Anthropic()

plugin = client.beta.organization.plugins.update(
    "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
    served_version_id="pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p",
)

print(f"id: {plugin.id}")
print(f"served_version_id: {plugin.served_version_id}")

{
  "type": "plugin",
  "id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
  "name": "sales-toolkit",
  "display_name": "Sales Toolkit",
  "description": "Account research and call prep for the sales team.",
  "served_version_id": "pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p",
  "served_version_pinned": true,
  "latest_version_id": "pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p",
  "manifest_version": "1.5.0",
  "owner": { "type": "organization" },
  "marketplace_id": "marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r",
  "created_by": { "type": "api_actor", "api_key_id": "apikey_01Nq9vN6rT2zH7uW4bX5mR8s" },
  "organization_installation_preference": "available",
  "organization_installation_preference_inherited": true,
  "content_scan": { "status": "completed", "assessment": "pass", "reason": null },
  "components": [
    {
      "type": "skill",
      "name": "account-research",
      "description": "Researches a customer account before a call."
    },
    { "type": "mcp_server", "name": "crm", "description": null },
    {
      "type": "command",
      "name": "call-prep",
      "description": "Builds a one-page brief for an upcoming call."
    }
  ],
  "reach": "remote",
  "created_at": "2026-09-01T17:04:11Z",
  "updated_at": "2026-09-16T10:02:45Z"
}

除了共用回應（成員擁有的外掛程式為 403，成員無法取得的版本為 409 scan_pending 或 400 scan_failed；請參閱錯誤回應）之外，請求還可能因以下原因失敗：

刪除外掛程式

DELETE /v1/organizations/plugins/{plugin_id} 會永久刪除外掛程式及其包含的每個版本，就如同管理員在 claude.ai 中執行刪除一樣。它適用於 manual 市集中的任何外掛程式，包括成員的外掛程式，即使該成員已離開組織。刪除傳回後，該外掛程式、其版本及其檔案將從所有讀取中消失，成員也不再獲得提供。組織擁有的外掛程式的「installation setting」（安裝設定）會隨之移除；成員擁有的外掛程式的分享會被撤回，且對其擁有者而言也會消失。位於從 Git 同步之市集中的外掛程式會傳回 400：請從儲存庫中移除它，或在 claude.ai 中移除該市集。需要 write:plugins 範圍。

刪除無法復原，且沒有針對個別版本的刪除。若要以可復原的方式停止提供組織擁有的外掛程式，請將其組織層級安裝設定設為 not_available（原本繼承其市集預設值的外掛程式會取得自己的設定，之後移除該組織層級設定即可讓外掛程式回到預設值），並移除（或設為 not_available）GET /v1/organizations/plugins/{plugin_id}/installation_settings 列出的每個群組設定，因為群組的設定會覆寫其成員的組織層級值。請依序傳送這些寫入，而非平行傳送（請參閱設定安裝設定）。成員擁有的外掛程式無法透過此 API 停止提供，只能將其刪除，且僅限其市集為 manual 時。

client = anthropic.Anthropic()

deleted_plugin = client.beta.organization.plugins.delete(
    "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
)

print(f"id: {deleted_plugin.id}")

{ "type": "plugin_deleted", "id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL" }

外掛程式版本

外掛程式版本是某次上傳中外掛程式檔案的不可變快照（建立版本的回應顯示了完整的物件）。其欄位與外掛程式針對此版本的提供版本欄位（display_name、description、manifest_version、content_scan、components、reach）相對應，另外還有 release_notes（隨上傳提供，並顯示在 claude.ai 的版本歷史記錄中）和 created_by（上傳者）。

缺少 pluginver_ 前綴的 {version} 會傳回 400（註明之處的字面值 latest 除外）。帶有前綴但無法識別該外掛程式版本的值會傳回 404。

列出外掛程式的版本

GET /v1/organizations/plugins/{plugin_id}/versions 列出外掛程式的版本，依 created_at 遞減排序；第一個項目是 latest_version_id 所識別的版本。limit 為 1 到 1,000。需要 read:plugins 範圍。

client = anthropic.Anthropic()

versions = client.beta.organization.plugins.versions.list(
    "plugin_01Hq3vX8kZcN2mB7pR4tY9wL", limit=50
)

# 會視需要自動擷取更多頁面。
for version in versions:
    print(f"{version.id}: {version.manifest_version}")

建立版本

POST /v1/organizations/plugins/{plugin_id}/versions 會為 manual 市集中組織擁有的外掛程式新增一個版本。請求主體為 multipart/form-data，具有與建立外掛程式相同的 files[] 和 release_notes 欄位、上傳要求，以及檔案、資訊清單、封存檔和大小錯誤。上傳的名稱（資訊清單的 name）必須與外掛程式的 name 相同。若外掛程式未釘選，新版本通常會在儲存後立即提供；若已釘選，該版本會被儲存，但在您將提供的版本變更為它之前不會提供。若要確認，請比較回應的 id 與外掛程式的 served_version_id。傳回該版本。需要 write:plugins 範圍。

client = anthropic.Anthropic()

with open("dist/sales-toolkit.zip", "rb") as archive:
    version = client.beta.organization.plugins.versions.create(
        "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
        files=[archive],
        release_notes="Adds the call-prep command.",
    )

print(f"id: {version.id}")
print(f"manifest_version: {version.manifest_version}")

{
  "type": "plugin_version",
  "id": "pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p",
  "plugin_id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
  "display_name": "Sales Toolkit",
  "description": "Account research and call prep for the sales team.",
  "manifest_version": "1.5.0",
  "release_notes": "Adds the call-prep command.",
  "created_by": { "type": "api_actor", "api_key_id": "apikey_01Nq9vN6rT2zH7uW4bX5mR8s" },
  "content_scan": { "status": "processing", "assessment": null, "reason": null },
  "components": [
    {
      "type": "skill",
      "name": "account-research",
      "description": "Researches a customer account before a call."
    },
    { "type": "mcp_server", "name": "crm", "description": null },
    {
      "type": "command",
      "name": "call-prep",
      "description": "Builds a one-page brief for an upcoming call."
    }
  ],
  "reach": "remote",
  "created_at": "2026-09-15T14:12:30Z"
}

除了違反上傳要求的上傳會傳回 400（請求本文超過 200 MB 則為 413），以及共通回應（成員擁有的外掛程式會傳回 403；請參閱錯誤回應）之外，請求還可能因下列原因失敗：

取得版本

GET /v1/organizations/plugins/{plugin_id}/versions/{version} 傳回一個版本。{version} 是版本 ID，或是 latest，代表請求當下 latest_version_id 所識別的版本。需要 read:plugins 範圍。

client = anthropic.Anthropic()

version = client.beta.organization.plugins.versions.retrieve(
    "latest",
    plugin_id="plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
)

print(f"id: {version.id}")
print(f"manifest_version: {version.manifest_version}")

下載版本的檔案

GET /v1/organizations/plugins/{plugin_id}/versions/{version}/content 會以儲存的 .zip 封存檔（Content-Type: application/zip）下載版本的檔案。無論其內容掃描結果為何都會傳回封存檔，因此您可以檢查對成員隱藏的版本。它會完全依照儲存時的狀態提供，因此對於 manual 市集中的組織擁有外掛程式，只要符合目前的上傳要求，您就可以原封不動地將其重新上傳為新版本。{version} 必須是版本 ID，而非 latest：請先讀取外掛程式的 served_version_id 或 latest_version_id，或使用 GET /v1/organizations/plugins/{plugin_id}/versions/latest 解析 latest。Content-Disposition 檔案名稱衍生自外掛程式的名稱，不具唯一性；請依外掛程式和版本 ID 為儲存的檔案命名。需要 read:plugins 範圍。

下載成員擁有的外掛程式封存檔會在 Compliance API 的 Activity Feed（活動摘要）上記錄一個 claude_plugin_archive_accessed 事件，以 ID 識別金鑰（作為 api_actor）、外掛程式及其市集、版本以及擁有該外掛程式的成員；其中不包含任何名稱。下載組織擁有的外掛程式封存檔則不會記錄任何內容。

client = anthropic.Anthropic()

plugin_id = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
version_id = "pluginver_01Km7tL4pR9xF5sU2zV3jP6q"

with client.beta.organization.plugins.versions.with_streaming_response.download(
    version_id,
    plugin_id=plugin_id,
) as response:
    response.stream_to_file(f"{plugin_id}_{version_id}.zip")

外掛程式安裝設定

這些端點適用於組織擁有的外掛程式。對於成員擁有的外掛程式，它們會傳回 404，因為這類外掛程式改用共用（請參閱外掛程式共用）。{target} 為字面值 organization 時代表外掛程式的組織範圍設定，為群組的 rbac_group_ ID 時則代表該群組的設定；任何其他值都會傳回 400。群組 ID 來自 GET /v1/organizations/rbac_groups（範圍為 read:rbac_groups；請參閱使用者管理中的群組）。設定本身沒有 id：它以 (plugin_id, target) 定址，且不會在其上記錄執行者（執行者記錄在其 plugin_installation_preference_updated 活動事件上）。

列出外掛程式的安裝設定

GET /v1/organizations/plugins/{plugin_id}/installation_settings 列出組織擁有的外掛程式所持有的設定，依 created_at 遞減排序：其自身的組織層級設定（在繼承其市集預設值期間不存在）以及每個群組的設定。可依 target_type（organization 或 rbac_group）篩選。需要 read:plugins 範圍。

client = anthropic.Anthropic()

settings = client.beta.organization.plugins.installation_settings.list(
    "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
)

# 會視需要自動擷取更多頁面。
for setting in settings:
    print(f"{setting.plugin_id}: {setting.installation_preference}")

設定安裝設定

POST /v1/organizations/plugins/{plugin_id}/installation_settings/{target} 會為組織擁有的外掛程式設定某個目標的安裝設定，建立該設定或變更其現有的值。請求主體唯一的欄位是 installation_preference（required、auto_install、available 或 not_available），且為必填。設定目標已持有的值不會有任何變更。設定 organization 目標會使外掛程式停止繼承其市集的預設值（organization_installation_preference_inherited 變為 false），即使該值與預設值相同亦然，因此外掛程式將不再跟隨市集預設值之後的變更。若要讓外掛程式回到其市集的預設值，請移除組織層級設定；群組設定不受影響。群組目標必須是您的組織可在 GET /v1/organizations/rbac_groups 中看到的群組，否則請求會傳回 404。此變更不會改變外掛程式的 updated_at；它會記錄在 Activity Feed 上。傳回該設定。需要 write:plugins 範圍。

請一次只傳送一個外掛程式的安裝設定寫入。如果同一個外掛程式的多個寫入同時抵達，伺服器會依序處理，並可能以 503 回應其中部分寫入，而不套用它們。該 503 帶有 x-should-retry: true，且該寫入可以安全地重複：等待一兩秒，然後再次傳送。

client = anthropic.Anthropic()

setting = client.beta.organization.plugins.installation_settings.set(
    "rbac_group_01F3xQqQzXyWvUtSrQpOnMlK",
    plugin_id="plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
    installation_preference="available",
)

print(f"plugin_id: {setting.plugin_id}")
print(f"installation_preference: {setting.installation_preference}")

{
  "type": "plugin_installation_setting",
  "plugin_id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
  "target": { "type": "rbac_group", "rbac_group_id": "rbac_group_01F3xQqQzXyWvUtSrQpOnMlK" },
  "installation_preference": "available",
  "created_at": "2026-09-02T10:00:00Z",
  "updated_at": "2026-09-02T10:00:00Z"
}

移除安裝設定

DELETE /v1/organizations/plugins/{plugin_id}/installation_settings/{target} 會移除組織擁有的外掛程式某個目標的安裝設定。當 {target} 為 organization 時，會移除外掛程式自身的組織層級設定。外掛程式隨後會再次繼承其市集的預設值（organization_installation_preference_inherited 變為 true），並跟隨該預設值之後的變更；群組設定不受影響。當使用群組的 rbac_group_ ID 時，會移除該群組的設定：該群組的成員會改用組織層級值，或其所屬其他群組的設定。沒有自身設定的目標會傳回 404；這包括已繼承其市集預設值之外掛程式的 organization 目標。此變更不會改變外掛程式的 updated_at；它會記錄在 Activity Feed 上。回應以複合鍵取代 id；對於 organization 目標，其 target 為 {"type": "organization"}。需要 write:plugins 範圍。

client = anthropic.Anthropic()

removed_setting = client.beta.organization.plugins.installation_settings.remove(
    "rbac_group_01F3xQqQzXyWvUtSrQpOnMlK",
    plugin_id="plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
)

print(f"plugin_id: {removed_setting.plugin_id}")

{
  "type": "plugin_installation_setting_deleted",
  "plugin_id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
  "target": { "type": "rbac_group", "rbac_group_id": "rbac_group_01F3xQqQzXyWvUtSrQpOnMlK" }
}

外掛程式分享

「Share」（分享）僅存在於成員擁有的外掛程式上，且在此 API 中為唯讀（請參閱分享）。

列出外掛程式的分享

GET /v1/organizations/plugins/{plugin_id}/shares 列出成員擁有的外掛程式的擁有者已將其分享給誰，依 granted_at 遞減排序：所有成員（organization）、某個群組（rbac_group）或指定的成員（organization_member）。可依 target_type 篩選。擁有者未分享的外掛程式會傳回空清單；組織擁有的外掛程式會傳回 404。分享在此 API 上為唯讀，且列出的分享僅在您的組織於 claude.ai 中開啟該類型的分享時才會授予存取權（請參閱分享）。granted_at 是給予分享的時間；如果擁有者之後在 claude.ai 中變更了分享，則為該變更的時間。需要 read:plugins 範圍。

client = anthropic.Anthropic()

shares = client.beta.organization.plugins.shares.list("plugin_01Mr2wP7sU3aJ8vX5cY6nS9t")

# 視需要自動擷取更多頁面。
for share in shares:
    print(f"plugin_id: {share.plugin_id}")

{
  "data": [
    {
      "type": "plugin_share",
      "plugin_id": "plugin_01Mr2wP7sU3aJ8vX5cY6nS9t",
      "target": { "type": "organization_member", "user_id": "user_01WCz9BvGLdMYRUMmcAxMWvW" },
      "granted_at": "2026-08-20T15:12:00Z"
    }
  ],
  "next_page": null
}

外掛程式市集

此 API 會讀取市集並設定組織市集的預設安裝設定；市集本身是在 claude.ai 中建立、連接到儲存庫及刪除的。

{
  "type": "plugin_marketplace",
  "id": "marketplace_01VbNcMxZaSdFgHjKlQwErTy",
  "name": "engineering-tools",
  "owner": { "type": "organization" },
  "source": "github",
  "sync_status": "success",
  "last_sync_ended_at": "2026-09-10T22:15:03Z",
  "last_sync_read_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8",
  "default_installation_preference": "available",
  "created_at": "2026-06-12T08:45:00Z"
}

缺少 marketplace_ 前綴的 marketplace_id 會傳回 400。帶有前綴但無法解析或屬於其他組織的值會傳回 404。

列出市集

GET /v1/organizations/plugin_marketplaces 列出您組織的市集以及成員的個人市集，依 created_at 遞減排序。您可以使用它來找出市集的 ID，以便在市集包含任何外掛程式之前，依其篩選外掛程式清單或上傳到其中。程式庫市集會在首次於其中建立內容後出現，無論是在 claude.ai 中或透過此 API 建立。可依 owner_type（organization 或 user）和 source 篩選。limit 為 1 到 1,000。需要 read:plugins 範圍。

client = anthropic.Anthropic()

marketplaces = client.beta.organization.plugin_marketplaces.list(
    owner_type="organization"
)

# 視需要自動擷取更多頁面。
for marketplace in marketplaces:
    print(f"{marketplace.id}: {marketplace.name}")

取得市集

GET /v1/organizations/plugin_marketplaces/{marketplace_id} 傳回一個市集。需要 read:plugins 範圍。

client = anthropic.Anthropic()

marketplace = client.beta.organization.plugin_marketplaces.retrieve(
    "marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r"
)

print(f"id: {marketplace.id}")
print(f"name: {marketplace.name}")

設定市集的預設安裝設定

POST /v1/organizations/plugin_marketplaces/{marketplace_id} 設定組織擁有的市集的預設安裝設定。市集中每個沒有自身組織層級設定的外掛程式都會將此預設值回報為其 organization_installation_preference，包括之後新增的外掛程式。它適用於 manual 和同步的市集；成員的個人市集會傳回 403。唯一可更新的欄位是 default_installation_preference，且為必填。它無法設回 null：市集一旦有了預設值，就會一直保有，與 claude.ai 中相同。變更會記錄為一個 marketplace_updated 事件，不會有個別外掛程式的事件，且不會改變任何外掛程式的 updated_at。設定為已設定的值不會有任何變更，但有一個例外：從未設定預設值的市集會回報 not_available，但並未持有設定，因此其第一次寫入（即使是 not_available）也算作變更。傳回市集。需要 write:plugins 範圍。

client = anthropic.Anthropic()

marketplace = client.beta.organization.plugin_marketplaces.update(
    "marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r",
    default_installation_preference="available",
)

print(f"id: {marketplace.id}")
print(f"default_installation_preference: {marketplace.default_installation_preference}")

驗證市集內容

有兩個端點會回報對給定市集內容進行同步時會發生什麼情況，而不會連接或儲存任何內容：POST /v1/organizations/plugin_marketplaces/validate_repository 會讀取公開的 GitHub 存放庫，而 POST /v1/organizations/plugin_marketplaces/validate_archive 會讀取您上傳的市集目錄 .zip 檔案。兩者都傳回相同的報告：marketplace.json 格式是否正確、哪些外掛程式會被略過及其原因，以及哪些外掛程式會在略去部分內容的情況下同步。這些檢查與實際同步所執行的檢查相同。內容的問題會在報告中傳回，而非以 HTTP 錯誤的形式傳回：即使存放庫或封存檔完全無法讀取，請求仍會成功並傳回 valid: false。驗證會計為讀取，且這兩個端點合計另外限制每個組織每分鐘 10 次驗證（請參閱速率限制）；它們不會在 Activity Feed 上記錄任何內容。驗證可能需要長達 120 秒才會傳回，因此請將用戶端的逾時設定為高於此值。兩個端點都需要 read:plugins 或 write:plugins 範圍（read:org_audit 和 read:compliance_org_data 不會授予這些範圍）。

驗證會以匿名方式讀取存放庫。對於任何位於 GitHub 上但在存放庫之外的外掛程式來源，也是如此。因此，驗證會將私人存放庫或私人外掛程式來源回報為找不到，或需要登入 GitHub。當驗證回報需要登入 GitHub 時，報告代碼為 marketplace_repo_sign_in_required。

驗證不會擷取位於 GitHub 以外主機上的外掛程式來源。具有此類來源的外掛程式通常會收到 marketplace_validate_source_not_checked 警告，並在市集實際同步時進行檢查。

對於 Anthropic 同步到每個組織的市集，驗證會套用更嚴格的規則。當存放庫是此類市集時，validate_repository 會套用這些規則。當封存檔指名此類市集時，validate_archive 會套用這些規則。更嚴格的規則如下：

• 市集之外的每個外掛程式來源都必須固定到完整的提交 SHA。
• 驗證會將未固定的來源和位於不支援主機上的來源回報為外掛程式錯誤。
• 對於 validate_repository，驗證讀取的分支預設為市集同步所用的分支。

validate_repository 接受具有兩個欄位的 JSON 本文：repository_url，即 github.com 上公開存放庫的 https:// URL（必填），以及 ref，即分支名稱或完整的 40 字元提交 SHA（選填）。當省略 ref 或其為 null 時，預設為同步會讀取的分支，通常是存放庫的預設分支。validate_archive 接受正好包含一個部分 archive 的 multipart/form-data，該部分以帶有檔案名稱的檔案部分傳送。該檔案是市集目錄的 .zip，最多 32 MB，且僅使用 DEFLATE 或 STORE 壓縮。封存檔的內容位於根目錄，或包在一個資料夾中（如同 Git 主機的下載所產生的）。不接受其他表單欄位。

驗證位於某分支的公開儲存庫：

client = anthropic.Anthropic()

report = client.beta.organization.plugin_marketplaces.validate_repository(
    repository_url="https://github.com/example-org/claude-plugins",
    ref="release-candidate",
)

print(f"valid: {str(report.valid).lower()}")
print(f"total_plugin_count: {report.total_plugin_count}")

{
  "type": "plugin_marketplace_validation_report",
  "valid": false,
  "ref": "release-candidate",
  "commit_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8",
  "total_plugin_count": 3,
  "manifest_error": null,
  "manifest_error_code": null,
  "plugin_errors": [
    {
      "name": "deploy-helper",
      "error": "The plugin has a top-level bin/ directory.",
      "error_code": "marketplace_sync_bin_directory_not_allowed"
    }
  ],
  "plugin_warnings": [
    {
      "name": "release-notes",
      "warnings": [
        {
          "message": "plugin.json has unrecognized top-level keys: owners",
          "error_code": "marketplace_sync_plugin_unrecognized_keys"
        }
      ]
    }
  ]
}

改為以 .zip 驗證市集目錄的本機副本；回應是相同的報告：

client = anthropic.Anthropic()

with open("marketplace.zip", "rb") as archive:
    report = client.beta.organization.plugin_marketplaces.validate_archive(
        archive=archive
    )

print(f"valid: {str(report.valid).lower()}")
print(f"total_plugin_count: {report.total_plugin_count}")

內容的問題永遠不會使請求失敗。除了每個端點共用的回應（僅具有 read:org_audit 或 read:compliance_org_data 的金鑰為 403；請參閱錯誤回應和速率限制）之外，請求本身還可能因以下原因失敗：

報告代碼

報告中的每個發現都有一個穩定的代碼：無法驗證任何內容時為 manifest_error_code，每個 plugin_errors 項目上為 error_code，每個警告上也為 error_code。當一個外掛程式有多個問題時，error_code 為第一個問題的代碼，而 error 會合併它們的訊息。未來可能會新增代碼；無法識別的 manifest_error_code 仍表示內容無法驗證，plugin_errors 項目上無法識別的代碼仍表示該外掛程式會被略過，而警告上無法識別的代碼仍表示該外掛程式會同步。下列代碼表示暫時性狀況，因此相同的請求稍後可能會成功：marketplace_host_rate_limited、marketplace_host_server_error、marketplace_host_timeout、marketplace_host_unreachable、marketplace_repo_access_denied、marketplace_sync_transient_fetch_budget_exhausted、marketplace_validate_network_error，以及通常為 marketplace_validate_deadline_exceeded。

無法識別的值

此頁面上的每個字串值（元件類型、reach、掃描欄位、市集 source、錯誤代碼）隨時可能新增值。請將無法識別的值視為任何未知字串來處理，而不是讓程式失敗。

速率限制

讀取請求（本頁上的每個 GET 端點）共用每個組織每分鐘 300 個請求的限制。寫入請求（建立外掛程式或版本、變更提供版本、刪除、設定或移除安裝設定，以及更新市集）共用每個組織每分鐘 60 個請求的限制。市集驗證（任一端點）會計為讀取，且兩個端點合計另外限制每個組織每分鐘 10 次驗證；兩項限制都會在讀取請求本文之前檢查。這些限制是跨您組織所有金鑰計算的，並與您組織的其他 Admin API 限制分開。傳入 organization_id 的讀取會計入金鑰建立時所屬組織的限制；若金鑰沒有自身所屬的組織，則計入上層組織的限制。超過限制的請求會傳回 429 Too Many Requests 及 retry-after 標頭。回應會包含適用限制的 anthropic-ratelimit-requests-* 標頭（在市集驗證上為其每分鐘 10 次的限制；在 429 上則為拒絕該請求的限制）。

當服務暫時沒有容量處理另一個上傳、提供版本變更或驗證時，這些作業也可能傳回帶有 retry-after 的 429，而當您的組織超過其內容掃描速率時，上傳會傳回 429。請以相同方式處理所有這些情況：等待 retry-after 指定的時間，然後重試。除了這些限制之外，請一次只傳送一個同一外掛程式的安裝設定寫入：當多個寫入同時抵達時，部分寫入可能會以 503 和 x-should-retry: true 回應，這些寫入在一兩秒後可以安全地再次傳送（請參閱設定安裝設定）。

分頁

列表端點使用「opaque cursor」（不透明游標）。第一個請求最多傳回 limit 列以及一個 next_page 游標；在下一個請求中將該游標原封不動地作為 page 參數傳遞，並重複此操作直到 next_page 為 null。請將游標字串視為不透明的：不要自行解析、修改或建構它。列出外掛程式可能會傳回少於 limit 個外掛程式或沒有任何外掛程式的頁面，而 next_page 仍然有設定，因此請持續請求頁面直到 next_page 為 null。Python、TypeScript、C#、Go、Java 和 Ruby SDK 的列表迭代器以及 CLI（使用 --format raw 時除外）會為您處理這件事。它們會在 next_page 有設定時請求下一頁，因此較短或空白的頁面不會使其結束。在 PHP 和 curl 中，請自行請求每一頁，並將其 next_page 作為 page 傳遞。

limit 預設為 20，最小值為 1。外掛程式、安裝設定和分享的最大值為 100，版本和市集的最大值為 1,000。每個清單都依最新優先排序。

錯誤回應

錯誤回應遵循 Claude API 錯誤中記載的標準結構。聯絡支援團隊時，請提供回應本文中的 request_id。

當同一狀態有多種需要您以不同方式處理的原因時，錯誤也會包含 error.details.error_code。若原因涉及特定外掛程式或版本，錯誤還會包含 error.details.plugin_id 或 error.details.plugin_version_id：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "...",
    "details": {
      "error_code": "plugin_name_taken",
      "plugin_id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
    }
  },
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWG"
}

日後可能會新增代碼。遇到無法辨識的代碼時，請依其狀態碼的方式處理。

重試上傳

沒有任何端點接受 Idempotency-Key。變更提供的版本、設定安裝設定以及設定市集預設值都可以安全地重複執行。重複的刪除或重複移除安裝設定會傳回 404。

傳回錯誤的上傳不會儲存任何內容，唯一的例外是帶有 error_code: "registration_pending" 的 503。伺服器儲存上傳的檔案後，會向 claude.ai 註冊新版本的技能，成員才能使用這些技能。registration_pending 表示檔案已儲存，但最後這個步驟未完成。再次上傳相同的檔案即可完成此步驟（同時會再儲存一個相同的版本）：

• 在 POST /v1/organizations/plugins 上，外掛程式已經建立，且回應帶有 x-should-retry: false：請勿重新傳送建立請求（重新傳送會傳回 409 plugin_name_taken），而應將相同的檔案上傳為 details.plugin_id 的一個版本。
• 在 POST /v1/organizations/plugins/{plugin_id}/versions 上，版本已經儲存（details.plugin_version_id）。回應帶有 x-should-retry: true 時，請重新傳送相同的請求；帶有 false 時則不要重新傳送。

如果建立請求的回應遺失，請再次傳送建立請求。409 plugin_name_taken 表示第一次嘗試已儲存了外掛程式，或該名稱早已被使用。只有當 details.plugin_id 所指外掛程式的 created_by 是帶有您金鑰 api_key_id 的 api_actor 時，該外掛程式才是您遺失回應的建立請求所建立的。在上傳至該外掛程式之前，請先確認這一點（請參閱上表中的 plugin_name_taken）。重試一個遺失回應的版本建立請求，會儲存第二個相同的版本。為避免這種情況，請在每次上傳前記錄外掛程式的 latest_version_id；如果回應遺失，請讀取該外掛程式，並僅在 latest_version_id 未變更時才重試。

Activity Feed 事件

透過此 API 進行的每次寫入，都會記錄在您組織的 Compliance API Activity Feed 上，並歸屬於該 API 金鑰，以帶有其 apikey_ ID 的 api_actor 表示。該金鑰所建立的外掛程式和版本，其 created_by 中也會出現相同的執行者。

這些事件中的外掛程式、版本和市集 ID 與此 API 傳回的 ID 相同。事件也可能指名此 API 未列出的市集，例如 Anthropic 發布的外掛程式所在的市集。plugin_installation_preference_updated 以外掛程式的 name 和 marketplace_id 而非其 id 來識別外掛程式。在 claude_plugin_security_scan_completed 中，plugin_version 不是版本 ID，且外掛程式版本的任何欄位都不與其對應。

變更市集的預設值只會記錄一個 marketplace_updated 事件，不會記錄個別外掛程式的事件，即使此變更會改變所有繼承該預設值的外掛程式的值。讀取操作不會被記錄，但下載成員擁有的外掛程式封存檔除外。未造成任何變更的寫入不會被記錄。

在 claude.ai 中授予或撤回的共用，會以 role_assignment_granted 和 role_assignment_revoked 事件出現在動態中。此 API 不會回報刪除：已刪除的外掛程式會從下一次的清單中消失。透過 Git 同步移除的外掛程式、因刪除其市集而移除的外掛程式（只有一個 marketplace_deleted 事件），或因刪除成員帳戶或組織而移除的外掛程式，都不會發出個別外掛程式的事件，因此請定期重新列出完整清單，以掌握移除情況。

客戶管理加密金鑰

如果您的組織使用「customer-managed encryption key」（客戶管理加密金鑰），版本的 description、release_notes、components 和檔案都會以該金鑰加密。當金鑰無法使用時：

• 讀取和列出仍會成功，但 description、release_notes 和 components 會以 null 傳回。
• 下載封存檔、建立、建立版本以及變更提供的版本，會傳回帶有 cmek_key_disabled 或 cmek_key_network_blocked 的 400。
• 刪除程式庫市集中的外掛程式會傳回 400 cmek_key_disabled，且不會刪除任何內容，因為必須先從 claude.ai 撤回其技能，而這需要該金鑰。其他刪除、安裝設定和市集預設值則可正常運作。

恢復金鑰後，上述所有限制都會解除。

另請參閱