插件 API

插件 API 让您可以执行以下操作：

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

有关插件使用情况报告（成员使用哪些插件和技能，以及使用频率），请参阅 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 活动源上记录一个 claude_plugin_archive_accessed 事件，标识密钥、插件、版本和成员（请参阅活动源事件）。下载组织拥有的插件不会被记录。

读取同一父组织下的其他组织

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 处都有一个清单。清单中的 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：提供的版本通常跟随最新版本。当内容扫描开启时，在 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 设置为其当前版本来固定插件一次；此后，提升您想要提供的每个构建。在内容扫描开启的情况下，当前版本的 content_scan 显示为 processing 时，首次固定会返回 409 scan_pending；如果扫描显示为 fail、unknown 或 errored，则返回 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，而试点组持有 available，则试点成员获得 available。当您将插件从试点组推广到整个组织时，请设置组织范围的值，然后移除该组的设置。设置组织范围的值会使插件不再继承其市场默认值；移除组织范围的设置会使插件恢复为该默认值。

通过此 API 创建的插件一开始没有自己的设置，因此会继承其市场的默认值：除非有人设置了默认值，否则为 not_available。删除一个组会从每个插件中移除该组的设置。

共享

共享决定谁可以使用成员拥有的插件。所有者在 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 都需要包含 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 压缩，且不能加密或包含符号链接。
• 当市场已容纳 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) 元组可保留每个文件在插件内的路径；
# 若仅传入文件对象，则只会以其基本文件名发送。
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 市场中的任何插件，包括成员的插件，即使该成员此后已离开组织。删除返回时，该插件、其版本及其文件将从所有读取结果中消失，并且不再向成员提供。组织所有插件的安装设置会随之移除；成员所有插件的共享会被撤回，并且该插件对其所有者也会消失。从 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 活动源上记录一个 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；它会记录在活动源上。返回该设置。需要 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；它会记录在活动源上。响应以复合键代替 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" }
}

插件共享

共享仅存在于成员所有的插件上，并且在此 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 次验证（请参阅速率限制）；它们不会在活动源上记录任何内容。一次验证最多可能需要 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 接受 multipart/form-data，其中恰好包含一个部分 archive，以带文件名的文件部分形式发送。该文件是市场目录的 .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 指定的时间，然后重试。除这些限制外，请逐个发送同一插件的安装设置写入请求：当多个请求同时到达时，其中一些可能会收到带有 x-should-retry: true 的 503，这些请求可以在一两秒后安全地再次发送（请参阅设置安装设置）。

分页

列表端点使用 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 未发生变化时才重试。

活动源事件

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

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

另请参阅