外掛程式 API

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

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

端點

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

此版本不包含獨立技能（成員在技能編輯器中撰寫，或在 claude.ai 中以單一技能形式上傳的技能）。它們不會出現在清單中，也無法在此建立。Anthropic 發布的外掛程式也不會列入清單；其使用情況由 Analytics API 回報。市集是在 claude.ai 中建立、連接到儲存庫及刪除的，而非透過此 API。

先決條件

• 您的組織必須使用 Claude Enterprise 方案。
• 您的主要擁有者在 claude.ai > Organization settings > API 中建立具有 read:plugins 範圍、write:plugins 範圍或兩者兼具的 Admin API 金鑰。請參閱建立 Admin API 金鑰。
• 每個請求都帶有三個標頭：x-api-key、anthropic-version: 2023-06-01 和 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 標頭。本頁的範例使用各 SDK 的預設用戶端，該用戶端與 CLI 一樣，會從 ANTHROPIC_API_KEY 環境變數讀取 Admin API 金鑰；curl 範例從同一個變數讀取金鑰，並在 x-api-key 標頭中傳遞。在 Python、TypeScript、C#、Go、Java 和 Ruby 的列表範例以及 CLI 中，SDK 會在您迭代時擷取更多頁面，因此 limit 設定的是每頁大小，而非總數；PHP 和 curl 範例只傳回一頁（請參閱分頁）。

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 金鑰（請參閱建立 Admin API 金鑰），也可以讀取其中任何可存取此 API 的組織：在本頁任何 GET 端點上，於 organization_id 查詢參數中傳遞該組織的 ID。此 ID 是 claude.ai 設定中顯示的組織 UUID（也接受其 org_ 前綴形式）。若未提供此參數，金鑰會讀取建立它的組織。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：提供版本會跟隨最新版本，每個新版本一經儲存即會提供。

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

這讓發布管線可以上傳每個建置、進行測試，然後再升級它。若要讓您的管線決定每個建置何時提供，請將 served_version_id 設為外掛程式目前的版本，以釘選外掛程式一次；從那時起，升級您想要提供的每個建置。啟用內容掃描時，在目前版本的掃描完成之前，第一次釘選會傳回 409 scan_pending；若掃描完成的結果為 fail 或 unknown，或發生錯誤，則傳回 400 scan_failed（warn 會被接受）。已釘選的外掛程式目前無法取消釘選，無論在此處或在 claude.ai 中皆然。

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

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

安裝設定

安裝設定決定誰可以使用組織擁有的外掛程式。每個設定具有四個值之一，承載於名為 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，而 Pilot 群組持有 available，則 Pilot 成員會取得 available。當您將外掛程式從試行群組推廣到整個組織時，請先設定全組織值，再移除該群組的設定（設定全組織值會永久停止外掛程式繼承其市集預設值，如設定安裝設定所述）。

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

分享

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

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

內容掃描

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

啟用掃描期間，只有當外掛程式提供版本的掃描為 completed 且結果為 pass 或 warn 時，才會提供給成員。在掃描執行期間，或在掃描失敗、發生錯誤或未得出判定之後，外掛程式會對成員隱藏，且不會改為提供較早的版本。從未掃描過的版本（content_scan: null）會正常提供。

在未釘選的外掛程式上，每次上傳都會立即成為提供版本。在新版本的掃描通過之前，成員會失去該外掛程式，若掃描失敗則會持續無法使用。如果成員應在新版本掃描期間保留目前版本，請先釘選外掛程式（請參閱版本與提供版本）。

上傳後，content_scan.status 為 processing，判定結果會以非同步方式送達。請讀取版本以查看結果；外掛程式物件只會顯示其提供版本的掃描。將提供版本變更為掃描仍在執行中的版本會傳回 409 scan_pending；變更為掃描失敗的版本則傳回 400 scan_failed。

觸及範圍

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

reach 會計入版本宣告的所有內容，包括 components 未列出的 monitor、LSP 伺服器和應用程式設定，因此 components 列表為空的版本仍可能是 privileged。對於在開始記錄元件之前儲存的版本，以及因其某個技能或指令檔案無法讀取而無法判定觸及範圍的版本，其值為 null；請將 null 視為未分類。

上傳要求

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

• 上傳內容可以是一個 .zip 或 .plugin 封存檔，或一組個別檔案。封存檔可以將所有內容包在一個頂層資料夾中。
• 它必須恰好包含一個資訊清單，位於 .claude-plugin/plugin.json，且必須宣告 name。沒有資訊清單的單獨 SKILL.md 會被拒絕。
• 若頂層 SKILL.md 的 frontmatter 宣告了外掛程式元件，會被合併到資訊清單中；兩者都設定某個值時，以 plugin.json 為準。
• 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 壓縮，且不得加密或包含符號連結。
• 一個市集最多容納 500 個項目，計入其外掛程式以及成員保存在其中的任何獨立技能。此限制和 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

   

   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。

保持安全清單同步

執行每晚作業，標記觸及範圍超出成員工作階段，或內容掃描未通過的外掛程式。

1. 逐頁瀏覽 GET /v1/organizations/plugins?limit=100 直到 next_page 為 null，請自行將每頁的 next_page 作為 page 傳遞，而非使用 SDK 列表迭代器，因為它在此列表上可能提前停止（請參閱分頁）。每次執行時都從該列表讀取每個外掛程式的 reach 和 content_scan：稍後送達的掃描判定不會變更 updated_at。updated_at 會告訴您自上次執行以來，哪些外掛程式有新內容或新的提供版本（值得重新下載封存檔）；完整重新列出也是偵測移除的方式，因為被 Git 同步或帳戶刪除所移除的外掛程式，會在沒有任何事件的情況下消失。
2. 標記 reach 為 remote（宣告了 MCP 伺服器或 CLI），或 content_scan.assessment 為 fail 或 unknown 的每個外掛程式。
3. 對於每個被標記的外掛程式，使用 GET /v1/organizations/plugins/{plugin_id}/versions/{served_version_id}/content 下載提供版本的封存檔以供審查（請參閱下載版本的檔案）。
4. 若要在審查期間讓成員無法使用外掛程式，請參閱刪除外掛程式，了解可逆（組織擁有）和永久的選項。

外掛程式

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

content_scan 物件：

缺少 plugin_ 前綴的 plugin_id 會傳回 400。帶有前綴但無法解析、屬於其他組織或指向獨立技能的 plugin_id 會傳回 404。

列出外掛程式

GET /v1/organizations/plugins 會列出您組織中的每個外掛程式，包括組織市集和成員個人市集中的外掛程式，依 created_at 遞減排序。可依 owner_type（organization 或 user）、owner_user_id（前綴為 user_；某位成員的外掛程式，包括該成員離開組織之後）、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 會在一次呼叫中建立一個組織擁有的「plugin」（外掛程式）及其第一個版本；該版本會成為「served version」（提供版本）。請求主體為 multipart/form-data：files[] 可以是單一 .zip 或 .plugin 封存檔，也可以是每個檔案各一個部分，其中每個部分的檔名是該檔案在外掛程式中的路徑（例如 .claude-plugin/plugin.json）。選用欄位為 marketplace_id（組織擁有的 manual「marketplace」（市集）；預設為您的程式庫市集，該市集會在首次使用時建立）和 release_notes（最多 5,000 個字元，會顯示在 claude.ai 的版本歷史記錄中，並隨版本一併傳回）。外掛程式的 name、display_name、description 和 manifest_version 來自上傳的 manifest，且上傳內容必須符合上傳要求。啟用「content scanning」（內容掃描）時，回應的 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 範例中的檔名引數）；若檔案僅以其基本名稱傳送，將會找不到 manifest。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} 會變更組織擁有的外掛程式要向成員提供哪個版本。傳入較早的版本以回復，或傳入較新的版本以升級一個已儲存但未提供的建置。這會「pin」（釘選）該外掛程式，而已釘選的外掛程式目前無法取消釘選，無論是在此處或在 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 欄位、上傳要求，以及檔案、manifest、封存檔和大小錯誤。上傳的名稱（manifest 的 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} 移除組織擁有的外掛程式的某個群組設定。該群組的成員會回退到組織層級值，或其所屬其他群組的設定。組織層級設定一旦設定便無法移除，與 claude.ai 中相同（{target} 為 organization 時會傳回 400）；請改為變更其值。對此外掛程式未持有設定的群組會傳回 404。回應會以複合鍵取代 id。需要 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 以外主機上的外掛程式來源；這類外掛程式通常會收到 marketplace_validate_source_not_checked 警告，並在市集實際同步時進行檢查。如果儲存庫是（或封存檔指名的是）Anthropic 同步到每個組織的市集，則適用更嚴格的規則：市集外部的每個外掛程式來源都必須釘選到完整的 commit SHA，未釘選或位於不支援主機的來源會被回報為外掛程式錯誤，且讀取的分支預設為該市集同步來源的分支。

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

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

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 個請求的「rate limit」（速率限制），寫入請求（建立外掛程式或版本、變更提供版本、刪除、設定或移除安裝設定，以及更新市集）共用每個組織每分鐘 60 個請求的限制。市集驗證（任一端點）算作讀取，且驗證另外限制為每個組織在兩個端點合計每分鐘 10 次；兩項限制都會在讀取請求主體之前檢查。這些限制是跨您組織的所有金鑰計算的，並與您組織的其他 Admin API 限制分開。超過限制的請求會傳回 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。SDK 的清單迭代器會在您迭代時擷取後續頁面，但會在第一個空白頁面停止，因此在外掛程式清單上可能會提早結束；當您需要取得每個外掛程式時（如安全清單工作流程），請自行請求每個頁面，並將其 next_page 作為 page 傳入。

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

錯誤回應

錯誤回應遵循 錯誤 中記載的標準格式。聯絡支援團隊時，請提供回應主體中的 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 中提供該外掛程式的 ID，您可以繼續使用該外掛程式。重試一個遺失回應的版本建立請求，會儲存第二個相同的版本。為避免這種情況，請在每次上傳前記錄外掛程式的 latest_version_id；如果回應遺失，請讀取該外掛程式，並僅在 latest_version_id 未變更時才重試。

Activity Feed 事件

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

這些事件中的外掛程式、版本和市集 ID，與此 API 傳回的 ID 相同。plugin_installation_preference_updated 以外掛程式的 name 和 marketplace_id 來識別外掛程式，而非其 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 撤回其技能，而這需要該金鑰。其他刪除、安裝設定和市集預設值則可正常運作。

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

另請參閱