插件 API

Plugins API 让您可以清点 Claude Enterprise 组织中的每个 "plugin"（插件），从您自己的流水线发布插件和新版本，选择向成员提供哪个版本，控制谁可以使用每个插件，下载插件文件以供审查，并在连接 Git "marketplace"（市场）之前对其进行检查。

有关插件使用情况报告（成员使用哪些插件和技能，以及使用频率），请参阅 Analytics API。

端点

该 API 在五种资源上共提供 18 个端点：

此版本不包括独立技能（成员在 claude.ai 的技能编辑器中编写或作为单个技能上传的技能）。它们不会出现在清单中，也无法在此处创建。Anthropic 发布的插件也不会被清点；其使用情况由 Analytics API 报告。市场的创建、与代码仓库的连接以及删除均在 claude.ai 中进行，而不是通过此 API。

前提条件

• 您的组织必须使用 Claude Enterprise 计划。
• 您的主所有者在 claude.ai > 组织设置 > 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 处都有一个清单。清单中的 name 会成为插件的 name：一个在其市场内唯一的小写标识符。

市场

市场是插件的容器。每个市场都有一个所有者和一个来源。

• 所有者。 组织拥有其市场。每个成员也可以拥有个人市场。
• 来源。 manual 表示插件是上传的，可以在 claude.ai 中上传，对于组织市场也可以通过此 API 上传。github、gitlab 和 public_git 表示插件从所有者连接的 Git 仓库同步而来。同步的市场无法上传任何内容，此 API 也无法删除其中的插件，因为下一次同步会撤销这两种更改。请改为修改仓库。

您组织的库市场是组织拥有的 manual 市场，当您未指定市场时，上传内容会进入该市场。它会在首次有内容上传到其中时创建。

组织拥有的插件和成员拥有的插件

插件的 owner.type 表明它位于谁的市场中：

• organization：您可以通过此 API 管理它，但位于从 Git 同步的市场中的插件无法在此处接收上传或被删除。
• user：它位于某个成员的个人市场中。您可以读取其详细信息并下载其文件，如果其市场为 manual，还可以删除它。上传版本和选择提供的版本会返回 403。共享仅由该成员在 claude.ai 中管理。

将成员从组织中移除不会移除其插件。这些插件会以该成员的 user_id 保留在清单中，owner_user_id 筛选器仍能找到它们，因此您可以审查并移除已离职成员的内容。当该成员的账户被删除时，这些插件也会被删除。

版本和提供的版本

每次上传都会创建一个新的、不可变的 "version"（版本），无论它来自此 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 未列出的监视器、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 都需要包含 name 和 description 的有效 YAML frontmatter，且两者都不能包含 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 在一次调用中创建一个组织所有的插件及其第一个版本；该版本成为 "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 示例中的文件名参数）；如果文件仅以其基本名称发送，将找不到清单。TypeScript 和 Java SDK 以及 ant CLI 目前还无法以路径附加文件，因此这些示例改为将插件作为一个归档文件上传到该市场：

client = anthropic.Anthropic()

# 使用 (filename, file) 元组可保留每个文件在插件内的路径；
# 若仅传入文件对象，则只会以其基本文件名发送。
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 市场中的任何插件，包括成员的插件，即使该成员此后已离开组织。删除返回时，该插件、其版本及其文件将从所有读取结果中消失，并且不再向成员提供。组织所有插件的安装设置会随之移除；成员所有插件的共享会被撤回，并且该插件对其所有者也会消失。从 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} 移除组织所有插件的某个组设置。该组的成员将回退到组织范围的值，或其所属其他组的设置。组织范围的设置一旦设置便无法移除，这与 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" }
}

插件共享

共享仅存在于成员所有的插件上，并且在此 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 同步到每个组织中的市场，则适用更严格的规则：市场外部的每个插件来源都必须固定到完整的提交 SHA，未固定或位于不受支持主机上的来源会被报告为插件错误，并且读取的分支默认为该市场同步所用的分支。

validate_repository 接受包含两个字段的 JSON 请求体：repository_url，即 github.com 上公共存储库的 https:// URL（必填）；以及 ref，即分支名称或完整的 40 个字符的提交 SHA（可选；省略或为 null 时，使用同步会读取的分支，通常是存储库的默认分支）。validate_archive 接受 multipart/form-data，其中恰好包含一个部分 archive，以带文件名的文件部分发送：即市场目录的 .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 个请求的限制，写入请求（创建插件或版本、更改提供版本、删除、设置或移除安装设置以及更新市场）共享每个组织每分钟 60 个请求的限制。市场验证（任一端点）计为一次读取，并且两个端点的验证合计还额外限制为每个组织每分钟 10 次；这两项限制都会在读取请求体之前进行检查。这些限制按您组织的所有密钥合计计算，并且独立于您组织的其他 Admin API 限制。超出限制的请求会返回 429 Too Many Requests 以及 retry-after 标头。响应包含适用限制的 anthropic-ratelimit-requests-* 标头（对于市场验证，为其每分钟 10 次的限制；对于 429，为拒绝该请求的那项限制）。

当服务暂时没有容量处理另一个上传、提供版本更改或验证时，这些操作也可能返回带有 retry-after 的 429；当您的组织超出其内容扫描速率时，上传也会返回 429。请以相同方式处理所有这些情况：等待 retry-after 指定的时间，然后重试。除这些限制外，请逐个发送同一插件的安装设置写入请求：当多个请求同时到达时，其中一些可能会收到带有 x-should-retry: true 的 503，这些请求可以在一两秒后安全地再次发送（请参阅设置安装设置）。

分页

列表端点使用 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。每个列表都按从新到旧的顺序排列。

错误响应

"Error responses"（错误响应）遵循 错误 中记录的标准结构。联系支持团队时，请提供响应正文中的 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 未发生变化时才重试。

活动源事件

通过此 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。
• 归档文件下载、创建、版本创建以及提供版本的更改会返回 400，并带有 cmek_key_disabled 或 cmek_key_network_blocked。
• 删除库市场中的插件会返回 400 cmek_key_disabled 且不会删除任何内容，因为必须先从 claude.ai 撤回其技能，而这需要该密钥。其他删除操作、安装设置和市场默认值均可正常使用。

恢复密钥后，上述所有限制都会解除。

另请参阅