Plugins API

Plugins API позволяет инвентаризировать каждый «plugin» (плагин) в вашей организации Claude Enterprise, публиковать плагины и их новые версии из собственных конвейеров, выбирать версию, которую получают участники, управлять тем, кто может использовать каждый плагин, скачивать файлы плагинов для проверки и проверять «marketplace» (маркетплейс) на базе Git перед его подключением.

Отчёты об использовании плагинов (какие плагины и навыки используют участники и как часто) описаны в разделе Analytics APIs.

Конечные точки

API предоставляет 18 конечных точек для пяти ресурсов:

Этот выпуск не включает отдельные навыки (навыки, которые участник пишет в редакторе навыков или загружает как отдельный навык в claude.ai). Они не отображаются в инвентаре и не могут быть созданы здесь. Плагины, публикуемые Anthropic, также не инвентаризируются; их использование отражается в Analytics APIs. Маркетплейсы создаются, подключаются к репозиториям и удаляются в claude.ai, а не через этот API.

Предварительные требования

• Ваша организация должна использовать план Claude Enterprise.
• Основной владелец вашей организации создаёт ключ Admin API с областью действия read:plugins, write:plugins или обеими в claude.ai > Organization settings > API. См. Создание ключа Admin API.
• Каждый запрос содержит три заголовка: x-api-key, anthropic-version: 2023-06-01 и anthropic-beta: ce-plugins-2026-09-01.

SDK для Python, TypeScript, C#, Go, Java, PHP и Ruby предоставляют эти конечные точки в client.beta.organization, а CLI ant — в ant beta:organization; они отправляют заголовки anthropic-version и anthropic-beta за вас. Примеры на этой странице используют клиент по умолчанию каждого SDK, который, как и CLI, считывает ключ Admin API из переменной окружения ANTHROPIC_API_KEY; примеры 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, привязанный к вашей родительской организации, может делать это в любой подчинённой ей организации, имеющей доступ к этому API, передавая organization_id (см. Чтение другой организации с тем же родителем). Каждое такое скачивание записывает событие claude_plugin_archive_accessed в Compliance API Activity Feed, указывающее ключ, плагин, версию и участника (см. События Activity Feed). Скачивания плагинов, принадлежащих организации, не записываются.

Чтение другой организации с тем же родителем

Ключи read:plugins и write:plugins читают и записывают данные только той организации, в которой они были созданы. Если у вашей компании несколько организаций Claude, связанных под одной родительской организацией, ключ read:org_audit или read:compliance_org_data, созданный основным владельцем родительской организации для всех связанных организаций (см. Создание ключа Admin API), может также читать любую из них, имеющую доступ к этому API: передайте ID этой организации в параметре запроса organization_id в любой конечной точке GET на этой странице. ID — это UUID организации, отображаемый в настройках claude.ai (также принимается его форма с префиксом org_). Без этого параметра ключ читает организацию, в которой он был создан. 404 означает, что указанная организация не подчинена родителю ключа или API ей недоступен; значение, не являющееся UUID или ID с префиксом org_, возвращает 400. Любой другой ключ, указывающий организацию, отличную от своей, получает 404. Операции записи не принимают organization_id.

Ключевые понятия

Плагины и компоненты

Плагин — это пакет, расширяющий возможности Claude для участников вашей организации. Он содержит любое сочетание следующих компонентов:

У каждого плагина есть «manifest» (манифест) в .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 по-прежнему их находит, поэтому вы можете проверить и удалить содержимое ушедшего участника. Они удаляются при удалении учётной записи участника.

Версии и обслуживаемая версия

Каждая загрузка создаёт новую неизменяемую версию, независимо от того, поступает ли она из этого API, из claude.ai или из синхронизации Git. У плагина есть два указателя на его версии:

• latest_version_id: самая новая версия.
• served_version_id: «served version» (обслуживаемая версия), то есть версия, которую получают участники.

По умолчанию served_version_pinned имеет значение false: обслуживаемая версия следует за самой новой, и каждая новая версия начинает предоставляться участникам сразу после сохранения.

Выбор версии с помощью POST /v1/organizations/plugins/{plugin_id} «pins» (закрепляет) плагин (served_version_pinned: true). То же происходит, когда администратор выбирает версию в claude.ai или принимает запрос участника на публикацию в плагин. С этого момента новые загрузки сохраняются и продвигают latest_version_id, но участники остаются на закреплённой версии, пока вы не укажете в served_version_id другую. У плагина, два указателя которого различаются, есть сохранённая версия, которая не предоставляется участникам.

Это позволяет конвейеру выпуска загружать каждую сборку, тестировать её, а затем продвигать. Чтобы ваш конвейер решал, когда предоставлять каждую сборку, один раз закрепите плагин, задав в served_version_id его текущую версию; после этого продвигайте каждую сборку, которую хотите предоставить. При включённом сканировании содержимого это первое закрепление возвращает 409 scan_pending, пока не завершится сканирование текущей версии, и 400 scan_failed, если сканирование завершилось с результатом fail или unknown либо с ошибкой (warn принимается). Закреплённый плагин в настоящее время нельзя открепить ни здесь, ни в claude.ai.

Чтобы выполнить откат, задайте в served_version_id более раннюю версию. Переход на более новую версию выполняется так же.

Эти правила описывают плагины, принадлежащие организации. Обслуживаемой версией плагина, принадлежащего участнику, управляет его владелец в claude.ai.

Настройки установки

«Installation settings» (настройки установки) определяют, кто может использовать плагин, принадлежащий организации. Каждая настройка имеет одно из четырёх значений, передаваемых в полях с именем installation_preference (а в объектах плагина и маркетплейса — organization_installation_preference и default_installation_preference):

Плагин может иметь одну настройку для всей организации и по одной настройке для каждой группы (групп управления доступом на основе ролей, которыми управляют в разделе Управление пользователями). Участник получает значение по следующим правилам:

1. Значение для всей организации — это собственная настройка плагина для всей организации, если она есть, иначе значение по умолчанию его маркетплейса, иначе not_available. Плагин сообщает это значение в organization_installation_preference, с organization_installation_preference_inherited: true, пока оно берётся из значения по умолчанию маркетплейса.
2. Участник, не входящий ни в одну группу с настройкой для плагина, получает значение для всей организации.
3. Участник, входящий в одну или несколько групп с настройкой, вместо этого получает наиболее разрешающую из настроек этих групп в порядке required, auto_install, available, not_available.

Настройка группы заменяет значение для всей организации для её участников, а не дополняет его. Например, если значение для всей организации — required, а группа Pilot имеет available, участники Pilot получают available. Когда вы переводите плагин с пилотной группы на всю организацию, задайте значение для всей организации, а затем удалите настройку группы (задание значения для всей организации навсегда прекращает наследование плагином значения по умолчанию его маркетплейса, как объясняется в разделе Задание настройки установки).

Плагин, созданный через этот API, изначально не имеет собственных настроек, поэтому наследует значение по умолчанию своего маркетплейса: not_available, если никто не задал значение по умолчанию. Удаление группы удаляет её настройки из всех плагинов.

Общий доступ

«Shares» (общий доступ) определяет, кто может использовать плагин, принадлежащий участнику. Владелец предоставляет к нему доступ в claude.ai всем участникам, группе или указанным участникам. Этот API перечисляет записи общего доступа, но не может их изменять.

Если ваша организация отключила какой-либо вид общего доступа в настройках claude.ai, записи этого вида по-прежнему отображаются в списке, но никому не дают доступа, пока эта настройка отключена; сам список не показывает, отключена ли она.

Сканирование содержимого

«Content scanning» (сканирование содержимого) — это настройка организации в 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» (охват)) одним значением обобщает, насколько далеко версия распространяет своё действие на компьютерах участников и за их пределами:

reach учитывает всё, что объявляет версия, включая мониторы, серверы LSP и настройки приложения, которые не перечисляются в components, поэтому версия с пустым списком 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 МБ каждый; тело запроса сверх лимита возвращает 413 (request_too_large), а не 400. Загрузка содержит не более 5 000 файлов, глубина путей — не более 12, длина путей — не более 472 символов, а имена файлов или папок — не более 255 символов.
• ZIP-архивы должны использовать сжатие DEFLATE или STORE и не могут быть зашифрованы или содержать символические ссылки.
• Маркетплейс содержит не более 500 элементов с учётом его плагинов и любых отдельных навыков, которые участники хранят в нём. Этот лимит и лимит в 5 000 файлов — текущие значения, которые могут быть увеличены.

Примеры рабочих процессов

Публикация каждой сборки из конвейера выпуска

Загружайте каждую помеченную тегом сборку из «continuous integration» (непрерывной интеграции), или 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. Найдите ID пилотной группы с помощью GET /v1/organizations/rbac_groups. Для этого вызова нужна область действия read:rbac_groups, для которой требуется ключ, созданный для всех связанных организаций (см. Управление пользователями). Для следующих шагов нужна область write:plugins, которая действует только в организации, где был создан её ключ, поэтому в корпоративной среде с несколькими связанными организациями создайте этот ключ в организации, которой принадлежит плагин, и предоставьте ему обе области, либо используйте для этих шагов второй ключ, созданный там.

2. Задайте группе собственную настройку, например auto_install, с помощью POST /v1/organizations/plugins/{plugin_id}/installation_settings/{target}, где {target} — ID группы с префиксом rbac_group_, при этом значение для всей организации остаётся 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_id без префикса plugin_ возвращает 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). Фильтры объединяются по И. 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» (плагин), принадлежащий организации, и его первую версию за один вызов; эта версия становится обслуживаемой. Тело запроса имеет формат multipart/form-data: files[] — это либо один архив .zip или .plugin, либо по одной части на каждый файл, где имя файла в каждой части — это путь к файлу внутри плагина (например, .claude-plugin/plugin.json). Необязательные поля: marketplace_id (принадлежащий организации «marketplace» (маркетплейс) типа 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"
}

Загрузка отдельных файлов в указанный маркетплейс. Прикрепляйте каждый файл под его путём внутри плагина (суффикс ;filename= в примере cURL, аргументы с именем файла в примерах SDK); если файл отправлен только под своим базовым именем, манифест не будет найден. SDK для TypeScript и Java, а также CLI ant пока не умеют прикреплять файлы под путём, поэтому в этих примерах плагин вместо этого загружается в маркетплейс одним архивом:

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 для загрузки, нарушающей требования к загрузке (413 для тела запроса более 200 МБ), и общих ответов (403, когда marketplace_id — личный маркетплейс участника; см. Ответы с ошибками), создание может завершиться следующими ошибками:

Получение плагина

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 (кто её загрузил).

Для {version} без префикса pluginver_ возвращается 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 для загрузки, нарушающей требования к загрузке (413 для тела запроса более 200 МБ), и общих ответов (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 плагина либо разрешите latest с помощью GET /v1/organizations/plugins/{plugin_id}/versions/latest. Имя файла в Content-Disposition формируется из имени плагина и не является уникальным; называйте сохранённые файлы по ID плагина и версии. Требуется область доступа read:plugins.

Скачивание архива плагина, принадлежащего участнику, записывает событие claude_plugin_archive_accessed в Compliance API Activity Feed, которое идентифицирует ключ (как api_actor), плагин и его маркетплейс, версию и участника-владельца по ID; имён оно не содержит. Скачивание архива плагина, принадлежащего организации, ничего не записывает.

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 для общеорганизационной настройки плагина или ID группы с префиксом rbac_group_ для настройки этой группы; любое другое значение возвращает 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_id без префикса marketplace_ возвращается 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 — URL https:// публичного репозитория на github.com (обязательно), и ref — имя ветки или полный 40-символьный SHA коммита (необязательно; если оно опущено или равно null, используется ветка, которую прочитала бы синхронизация, обычно ветка репозитория по умолчанию). validate_archive принимает multipart/form-data ровно с одной частью archive, отправленной как файловая часть с именем файла: .zip каталога маркетплейса размером не более 32 МБ, содержимое которого находится в корне или обёрнуто в одну папку (как при скачивании с 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}")

Проблемы с содержимым никогда не приводят к ошибке запроса. Помимо ответов, общих для всех эндпоинтов (403 для ключа, у которого есть только read:org_audit или read:compliance_org_data; см. Ответы с ошибками и Ограничение скорости), сам запрос может завершиться следующими ошибками:

Коды отчёта

Каждая находка в отчёте имеет стабильный код: manifest_error_code, когда ничего не удалось проверить, error_code в каждой записи plugin_errors и 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 на этой странице) имеют общее «rate limit» (ограничение скорости) — 300 запросов в минуту на организацию, а запросы на запись (создание плагина или версии, изменение обслуживаемой версии, удаление, установка или удаление настройки установки и обновление маркетплейса) имеют общее ограничение 60 запросов в минуту на организацию. Проверка маркетплейса (любым из эндпоинтов) считается операцией чтения, и для проверок дополнительно действует ограничение 10 в минуту на организацию для обоих эндпоинтов вместе; оба ограничения проверяются до чтения тела запроса. Эти ограничения подсчитываются по всем ключам вашей организации и не зависят от других ограничений Admin API вашей организации. Запросы сверх ограничения возвращают 429 Too Many Requests с заголовком retry-after. Ответы содержат заголовки anthropic-ratelimit-requests-* для применимого ограничения (при проверке маркетплейса — для её ограничения 10 в минуту; при 429 — для того ограничения, которое отклонило запрос).

Загрузка, изменение обслуживаемой версии или проверка также могут вернуть 429 с retry-after, когда у сервиса временно нет ресурсов для ещё одной такой операции, а загрузка возвращает 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.

Загрузка, вернувшая ошибку, ничего не сохранила, за одним исключением: 503 с error_code: "registration_pending". После сохранения файлов загрузки сервер регистрирует навыки новой версии в 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, и вы продолжаете работу с этим плагином. Повторная попытка создания версии, ответ на которое был потерян, сохраняет вторую, идентичную версию. Чтобы избежать этого, записывайте latest_version_id плагина перед каждой загрузкой; если ответ потерян, прочитайте плагин и повторите попытку, только если latest_version_id не изменился.

События Activity Feed

Каждая операция записи через этот API регистрируется в Compliance API Activity Feed вашей организации и приписывается «API key» (ключу API) как api_actor с его идентификатором apikey_. Тот же субъект указывается в created_by у плагинов и версий, которые создаёт ключ.

Идентификаторы плагинов, версий и маркетплейсов в этих событиях совпадают с идентификаторами, которые возвращает этот API. 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, а для этого нужен ключ. Другие операции удаления, параметры установки и значения по умолчанию для маркетплейсов работают в обычном режиме.

Восстановление ключа устраняет все эти ограничения.

См. также