API de Plugins

A API de Plugins permite que você inventarie todos os plugins da sua organização Claude Enterprise, publique plugins e novas versões a partir dos seus próprios pipelines, escolha qual versão é servida aos membros, controle quem pode usar cada plugin, baixe arquivos de plugins para revisão e verifique um marketplace Git antes de conectá-lo.

Para relatórios de uso de plugins (quais plugins e skills os membros usam e com que frequência), consulte APIs de Analytics.

Endpoints

A API expõe 18 endpoints distribuídos em cinco recursos:

Esta versão não inclui skills avulsas (skills que um membro escreve no editor de skills ou envia como uma única skill no claude.ai). Elas não aparecem no inventário e não podem ser criadas aqui. Plugins publicados pela Anthropic também não são inventariados; o uso deles é informado pelas APIs de Analytics. Marketplaces são criados, conectados a repositórios e excluídos no claude.ai, não por meio desta API.

Pré-requisitos

• Sua organização deve estar em um plano Claude Enterprise.
• O proprietário principal da sua organização cria uma chave de API de Admin com o escopo read:plugins, o escopo write:plugins ou ambos em claude.ai > Configurações da organização > API. Consulte Criar uma chave de API de Admin.
• Toda requisição carrega três cabeçalhos: x-api-key, anthropic-version: 2023-06-01 e anthropic-beta: ce-plugins-2026-09-01.

Os SDKs de Python, TypeScript, C#, Go, Java, PHP e Ruby expõem esses endpoints em client.beta.organization, e a CLI ant em ant beta:organization; eles enviam os cabeçalhos anthropic-version e anthropic-beta para você. Os exemplos desta página usam o cliente padrão de cada SDK, que, assim como a CLI, lê a chave de API de Admin da variável de ambiente ANTHROPIC_API_KEY; os exemplos com curl leem a chave da mesma variável e a passam no cabeçalho x-api-key. Nos exemplos de listagem em Python, TypeScript, C#, Go, Java e Ruby e na CLI, o SDK busca mais páginas conforme você itera, então limit define o tamanho da página, não o total; os exemplos em PHP e curl retornam uma página (consulte Paginação).

As chaves de API pertencem à organização e continuam funcionando depois que a pessoa que as criou sai. Não as compartilhe nem as inclua no controle de versão.

Início rápido

Liste os plugins dos marketplaces da própria organização, do mais recente para o mais antigo:

client = anthropic.Anthropic()

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

# Busca automaticamente mais páginas conforme necessário.
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"
}

Neste exemplo, o plugin está fixado em uma versão anterior: uma versão mais recente (latest_version_id) está armazenada, mas ainda não é servida.

Escopos

Uma chave pode ter vários escopos. Uma integração que faz upload de um plugin e depois o lê de volta precisa de read:plugins e write:plugins. Sempre que esta página disser que um endpoint exige o escopo read:plugins, uma chave com read:org_audit ou read:compliance_org_data também funciona.

Acesso aos arquivos de plugins dos membros

Cada um desses escopos de leitura (read:plugins, read:org_audit e read:compliance_org_data) pode baixar os arquivos de plugins nos marketplaces pessoais dos membros, incluindo arquivos que as configurações de administrador do claude.ai não mostram, e uma chave read:org_audit ou read:compliance_org_data vinculada à sua organização-mãe pode fazer isso em qualquer organização abaixo dela que tenha acesso a esta API, passando organization_id (consulte Ler outra organização sob a mesma organização-mãe). Cada um desses downloads registra um evento claude_plugin_archive_accessed no Activity Feed da Compliance API, identificando a chave, o plugin, a versão e o membro (consulte Eventos do Activity Feed). Downloads de plugins de propriedade da organização não são registrados.

Ler outra organização sob a mesma organização-mãe

Chaves read:plugins e write:plugins leem e escrevem apenas na organização em que foram criadas. Se sua empresa tiver várias organizações Claude vinculadas a uma organização-mãe, uma chave read:org_audit ou read:compliance_org_data que o proprietário principal da organização-mãe criou para todas as organizações vinculadas (consulte Criar uma chave de API de Admin) também pode ler qualquer uma delas que tenha acesso a esta API: passe o ID dessa organização no parâmetro de consulta organization_id em qualquer endpoint GET desta página. O ID é o UUID da organização mostrado nas configurações do claude.ai (sua forma com o prefixo org_ também é aceita). Sem o parâmetro, a chave lê a organização em que foi criada. Um 404 significa que a organização indicada não está sob a organização-mãe da chave ou que a API não está disponível para ela; um valor que não seja um UUID nem um ID org_ retorna 400. Qualquer outra chave que indique uma organização diferente da sua recebe 404. Escritas não aceitam organization_id.

Conceitos principais

Plugins e componentes

Um plugin é um pacote que estende o Claude para os membros da sua organização. Ele contém qualquer combinação destes componentes:

Todo plugin tem um manifesto em .claude-plugin/plugin.json. O name do manifesto se torna o name do plugin: um identificador em letras minúsculas que é único dentro do seu marketplace.

Marketplaces

Um marketplace é um contêiner de plugins. Cada marketplace tem um proprietário e uma origem.

• Proprietário. A organização é proprietária dos seus marketplaces. Cada membro também pode ter marketplaces pessoais.
• Origem. manual significa que os plugins são enviados por upload, no claude.ai ou, no caso de um marketplace da organização, por meio desta API. github, gitlab e public_git significam que os plugins são sincronizados a partir de um repositório Git que o proprietário conectou. Nada pode ser enviado a um marketplace sincronizado, e esta API não pode excluir seus plugins, porque a próxima sincronização desfaria qualquer uma dessas alterações. Altere o repositório em vez disso.

O library marketplace (marketplace de biblioteca) da sua organização é o marketplace manual de propriedade da organização para o qual vão os uploads quando você não indica um marketplace. Ele é criado na primeira vez que algo é enviado para ele.

Plugins de propriedade da organização e de membros

O owner.type de um plugin indica em qual marketplace ele está:

• organization: você pode gerenciá-lo por meio desta API, exceto que um plugin em um marketplace sincronizado a partir do Git não pode receber uploads nem ser excluído aqui.
• user: ele está no marketplace pessoal de um membro. Você pode ler seus detalhes e baixar seus arquivos, e excluí-lo se o marketplace for manual. Fazer upload de versões e escolher a versão servida retornam 403. O compartilhamento é gerenciado apenas pelo membro, no claude.ai.

Remover um membro da organização não remove seus plugins. Eles permanecem no inventário sob o user_id do membro, e o filtro owner_user_id ainda os encontra, para que você possa revisar e remover o conteúdo de um membro que saiu. Eles são excluídos quando a conta do membro é excluída.

Versões e a versão servida

Todo upload cria uma nova version (versão) imutável, seja ela proveniente desta API, do claude.ai ou de uma sincronização Git. Um plugin tem dois ponteiros para suas versões:

• latest_version_id: a versão mais recente.
• served_version_id: a "served version" (versão servida), ou seja, a versão servida aos membros.

Por padrão, served_version_pinned é false: a versão servida acompanha a mais recente, e cada nova versão é servida assim que é armazenada.

Escolher uma versão com POST /v1/organizations/plugins/{plugin_id} fixa ("pins") o plugin (served_version_pinned: true). O mesmo acontece quando um administrador escolhe uma versão no claude.ai ou aceita a solicitação de um membro para publicar no plugin. A partir daí, novos uploads são armazenados e avançam latest_version_id, mas os membros continuam com a versão fixada até que você aponte served_version_id para outra. Um plugin cujos dois ponteiros diferem tem uma versão armazenada que não está sendo servida.

Isso permite que um pipeline de release faça upload de cada build, teste-o e depois o promova. Para que seu pipeline decida quando cada build é servido, fixe o plugin uma vez definindo served_version_id como sua versão atual; a partir daí, promova cada build que você quiser servir. Com a verificação de conteúdo ativada, essa primeira fixação retorna 409 scan_pending até que a verificação da versão atual seja concluída, e 400 scan_failed se a verificação tiver sido concluída com fail ou unknown, ou tiver dado erro (warn é aceito). Atualmente, um plugin fixado não pode ser desafixado, nem aqui nem no claude.ai.

Para reverter, defina served_version_id como uma versão anterior. Avance da mesma forma.

Essas regras descrevem plugins de propriedade da organização. A versão servida de um plugin de propriedade de um membro é controlada pelo seu proprietário no claude.ai.

Configurações de instalação

As installation settings (configurações de instalação) decidem quem pode usar um plugin de propriedade da organização. Cada configuração tem um de quatro valores, contidos nos campos chamados installation_preference (e, nos objetos de plugin e de marketplace, organization_installation_preference e default_installation_preference):

Um plugin pode ter uma configuração para toda a organização e uma configuração por grupo (os grupos de controle de acesso baseado em funções gerenciados em Gerenciamento de usuários). Um membro recebe um valor de acordo com estas regras:

1. O valor para toda a organização é a configuração do próprio plugin para toda a organização, se houver; caso contrário, o padrão do seu marketplace; caso contrário, not_available. O plugin informa esse valor em organization_installation_preference, com organization_installation_preference_inherited: true enquanto ele vier do padrão do marketplace.
2. Um membro que não pertence a nenhum grupo com uma configuração para o plugin recebe o valor para toda a organização.
3. Um membro que pertence a um ou mais grupos com uma configuração recebe, em vez disso, a mais permissiva das configurações desses grupos, na ordem required, auto_install, available, not_available.

A configuração de um grupo substitui o valor para toda a organização para seus membros; ela não se soma a ele. Por exemplo, se o valor para toda a organização for required e o grupo Pilot tiver available, os membros do Pilot recebem available. Ao mover um plugin de um grupo piloto para toda a organização, defina o valor para toda a organização e depois remova a configuração do grupo (definir o valor para toda a organização impede permanentemente que o plugin herde o padrão do seu marketplace, como explica Definir uma configuração de instalação).

Um plugin criado por meio desta API começa sem configurações próprias, então herda o padrão do seu marketplace: not_available, a menos que alguém tenha definido um padrão. Excluir um grupo remove suas configurações de todos os plugins.

Compartilhamentos

Os shares (compartilhamentos) decidem quem pode usar um plugin de propriedade de um membro. O proprietário o compartilha no claude.ai com todos os membros, com um grupo ou com membros específicos. Esta API lista os compartilhamentos, mas não pode alterá-los.

Se sua organização tiver desativado um tipo de compartilhamento nas configurações do claude.ai, os compartilhamentos desse tipo ainda aparecem na lista, mas não dão acesso a ninguém enquanto essa configuração estiver desativada; a própria lista não mostra se ela está.

Verificação de conteúdo

A "content scanning" (verificação de conteúdo) é uma configuração da organização no claude.ai. Quando ela está ativada, as versões recém-armazenadas são verificadas (o claude.ai isenta algumas) e o resultado é informado em content_scan; uma versão que não foi verificada, por exemplo, uma armazenada antes de a verificação ser ativada, tem content_scan: null. A verificação não é oferecida a organizações que usam chaves de criptografia gerenciadas pelo cliente ou retenção zero de dados.

Enquanto a verificação estiver ativada, um plugin só é servido aos membros quando a verificação da sua versão servida está completed com pass ou warn. Enquanto a verificação está em andamento, ou depois que ela falha, dá erro ou não chega a um veredito, o plugin fica indisponível para os membros, e uma versão anterior não é servida no lugar dele. Uma versão que nunca foi verificada (content_scan: null) é servida normalmente.

Em um plugin que não está fixado, cada upload se torna imediatamente a versão servida. Os membros perdem o plugin até que a verificação da nova versão seja aprovada, e continuam sem ele se a verificação falhar. Se os membros devem manter a versão atual enquanto uma nova é verificada, fixe o plugin primeiro (consulte Versões e a versão servida).

Após um upload, content_scan.status é processing e o veredito chega de forma assíncrona. Leia a versão para vê-lo; o objeto do plugin mostra apenas a verificação da sua versão servida. Alterar a versão servida para uma versão cuja verificação ainda está em andamento retorna 409 scan_pending; para uma cuja verificação falhou, 400 scan_failed.

Alcance

O reach ("reach", alcance) resume, em um único valor, até onde uma versão chega nas máquinas dos membros e além delas:

O reach considera tudo o que a versão declara, incluindo monitores, servidores LSP e configurações de aplicativo, que components não lista, então uma versão com uma lista components vazia ainda pode ser privileged. Ele é null para uma versão armazenada antes de os componentes serem registrados e para uma versão cujo alcance não pôde ser determinado porque um de seus arquivos de skill ou command não pôde ser lido; trate null como não classificado.

Requisitos de upload

Os uploads seguem as mesmas regras dos uploads de plugins no claude.ai, então os mesmos arquivos compactados são aceitos nos dois lugares.

• O upload é um único arquivo compactado .zip ou .plugin, ou um conjunto de arquivos individuais. Um arquivo compactado pode envolver tudo em uma única pasta de nível superior.
• Ele deve conter exatamente um manifesto, em .claude-plugin/plugin.json, que deve declarar um name. Um SKILL.md isolado sem manifesto é rejeitado.
• Um SKILL.md de nível superior cujo frontmatter declara componentes de plugin é mesclado ao manifesto; plugin.json prevalece sempre que ambos definem um valor.
• name pode conter letras minúsculas (de qualquer alfabeto), dígitos e hifens, com até 64 caracteres. Letras maiúsculas, espaços, sublinhados e outras pontuações são rejeitados.
• displayName tem no máximo 64 caracteres e description no máximo 500.
• Todo SKILL.md precisa de um frontmatter YAML válido com name e description, nenhum dos dois contendo tags XML como <example>. Duas skills, ou dois commands, não podem compartilhar um nome.
• Nenhum arquivo pode estar em um diretório bin/ de nível superior.
• Nenhum arquivo .zip aninhado. MCP servers empacotados (.mcpb, .dxt) são permitidos.
• Os caminhos de arquivo devem ser relativos, não conter .. e usar apenas letras, dígitos, espaços e _ . - / ( ) ,.
• O corpo da requisição e o arquivo compactado descompactado têm, cada um, no máximo 200 MB; um corpo de requisição acima do limite retorna 413 (request_too_large) em vez de 400. Um upload tem no máximo 5.000 arquivos, profundidade de caminho de 12, caminhos de 472 caracteres e nomes de arquivos ou pastas de 255 caracteres.
• Arquivos ZIP devem usar compressão DEFLATE ou STORE e não podem ser criptografados nem conter links simbólicos.
• Um marketplace comporta no máximo 500 itens, contando seus plugins e quaisquer skills avulsas que os membros mantenham nele. Esse limite e o limite de 5.000 arquivos são valores atuais que podem ser aumentados.

Fluxos de trabalho de exemplo

Publicar cada build a partir de um pipeline de release

Faça upload de cada build com tag a partir do CI e deixe o pipeline decidir quando um build é servido.

1. Encontre o marketplace para o qual fazer upload com GET /v1/organizations/plugin_marketplaces?owner_type=organization, ou omita marketplace_id para usar o library marketplace.
2. No primeiro release, crie o plugin com POST /v1/organizations/plugins. Em cada release posterior, registre o latest_version_id do plugin e depois faça upload de uma versão com POST /v1/organizations/plugins/{plugin_id}/versions. Se a resposta do upload se perder, leia o plugin e tente novamente apenas se latest_version_id não tiver mudado (consulte Repetir uploads).
3. Para manter os membros na versão atual enquanto cada novo build é verificado, fixe o plugin uma vez definindo served_version_id como sua versão atual. A partir daí, cada upload é armazenado sem ser servido, e a fixação não pode ser desfeita: todo build que você quiser servir precisa da etapa 5.
4. Quando a verificação de conteúdo estiver ativada, consulte GET /v1/organizations/plugins/{plugin_id}/versions/{version} periodicamente até que content_scan.status não seja mais processing, e promova apenas quando for completed com pass ou warn.
5. Promova o build com POST /v1/organizations/plugins/{plugin_id} e {"served_version_id": "<the new version's ID>"}. Para reverter, envie o ID da versão anterior da mesma forma.

Liberar um plugin para um grupo piloto e depois para todos

1. Consulte o ID do grupo piloto com GET /v1/organizations/rbac_groups. Essa chamada precisa do escopo read:rbac_groups, que exige uma chave criada para todas as organizações vinculadas (consulte Gerenciamento de usuários). As próximas etapas precisam de write:plugins, que atua apenas na organização em que sua chave foi criada; portanto, em uma empresa com várias organizações vinculadas, crie essa chave na organização que contém o plugin e dê a ela os dois escopos, ou use uma segunda chave criada lá para essas etapas.

2. Dê ao grupo sua própria configuração, por exemplo auto_install, com POST /v1/organizations/plugins/{plugin_id}/installation_settings/{target}, em que {target} é o ID rbac_group_ do grupo, enquanto o valor para toda a organização permanece not_available. Apenas os membros do grupo recebem o plugin.

3. Quando o piloto terminar, defina o valor para toda a organização (isso impede permanentemente que o plugin herde o padrão do seu marketplace, como explica Definir uma configuração de instalação) e depois remova a configuração do grupo para que o grupo volte a seguir a organização:

   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}")

   Em seguida, remova a configuração do grupo com DELETE /v1/organizations/plugins/{plugin_id}/installation_settings/{target}, em que {target} é o ID do grupo. A configuração de um grupo substitui o valor para toda a organização para seus membros em vez de se somar a ele, então uma configuração de grupo remanescente de available manteria esses membros em available.

Manter um inventário de segurança sincronizado

Execute um job noturno que sinalize plugins que alcançam além da sessão do membro ou que falham na verificação de conteúdo.

1. Percorra as páginas de GET /v1/organizations/plugins?limit=100 até que next_page seja null, passando você mesmo o next_page de cada página como page em vez de usar um iterador de listagem do SDK, que pode parar antes do fim nesta lista (consulte Paginação). Leia o reach e o content_scan de cada plugin a partir dessa lista em todas as execuções: um veredito de verificação que chega depois não altera updated_at. updated_at informa quais plugins têm novo conteúdo ou uma nova versão servida desde a última execução (vale a pena baixar o arquivo compactado novamente); a nova listagem completa também é o que detecta remoções, porque um plugin removido por uma sincronização Git ou pela exclusão de uma conta desaparece sem gerar um evento.
2. Sinalize cada plugin cujo reach seja remote (ele declara um MCP server ou uma CLI), ou cujo content_scan.assessment seja fail ou unknown.
3. Para cada plugin sinalizado, baixe o arquivo compactado da versão servida para revisão com GET /v1/organizations/plugins/{plugin_id}/versions/{served_version_id}/content (consulte Baixar os arquivos de uma versão).
4. Para retirar um plugin dos membros enquanto você o revisa, consulte Excluir um plugin para ver as opções reversível (de propriedade da organização) e permanente.

Plugins

O objeto de plugin descreve um plugin em um dos marketplaces da sua organização ou no marketplace pessoal de um membro (a resposta do Início rápido mostra um completo). Seus campos display_name, description, manifest_version, content_scan, components e reach descrevem sua versão servida, de modo que uma única chamada de listagem mostra o que está sendo servido aos membros.

O objeto content_scan:

Um plugin_id sem o prefixo plugin_ retorna 400. Um plugin_id que tem o prefixo, mas não é resolvido, pertence a outra organização ou se refere a uma skill avulsa retorna 404.

Listar plugins

GET /v1/organizations/plugins lista todos os plugins da sua organização, nos marketplaces da organização e nos marketplaces pessoais dos membros, ordenados por created_at em ordem decrescente. Filtre por owner_type (organization ou user), owner_user_id (com o prefixo user_; os plugins de um membro, inclusive depois que o membro sai da organização), marketplace_id e created_at[gte], created_at[gt], created_at[lte], created_at[lt] (timestamps RFC 3339). Os filtros são combinados com AND. Um marketplace_id ou owner_user_id que não corresponde a nada na sua organização retorna uma página vazia, não um erro. A resposta tem o formato mostrado em Início rápido. Requer o escopo read:plugins.

client = anthropic.Anthropic()

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

# Busca automaticamente mais páginas conforme necessário.
for plugin in plugins:
    print(f"{plugin.id}: {plugin.name}")

Criar um plugin

POST /v1/organizations/plugins cria um plugin de propriedade da organização e sua primeira versão em uma única chamada; a versão se torna a "served version" (versão servida). O corpo é multipart/form-data: files[] é um único arquivo compactado .zip ou .plugin, ou uma parte por arquivo, em que o nome de arquivo de cada parte é o caminho do arquivo dentro do plugin (por exemplo .claude-plugin/plugin.json). Os campos opcionais são marketplace_id (um marketplace manual de propriedade da organização; o padrão é o marketplace da sua biblioteca, que é criado no primeiro uso) e release_notes (até 5.000 caracteres, exibidas no histórico de versões do claude.ai e retornadas na versão). Os campos name, display_name, description e manifest_version do plugin vêm do manifesto enviado, e o upload deve atender aos requisitos de upload. Quando a "content scanning" (verificação de conteúdo) está ativada, o content_scan.status da resposta é processing e o veredito chega de forma assíncrona. Retorna o plugin. Requer o "scope" (escopo) write:plugins.

Enviar um arquivo compactado:

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"
}

Envie arquivos individuais para um marketplace nomeado. Anexe cada arquivo sob seu caminho dentro do plugin (o sufixo ;filename= no exemplo cURL, os argumentos de nome de arquivo nos exemplos de SDK); um arquivo enviado apenas com seu nome base faz com que o manifesto não seja encontrado. Os SDKs TypeScript e Java e a CLI ant ainda não conseguem anexar arquivos sob um caminho, então esses exemplos enviam o plugin como um único arquivo compactado para o marketplace:

client = anthropic.Anthropic()

# Uma tupla (filename, file) preserva o caminho de cada arquivo dentro do plugin;
# um objeto de arquivo simples seria enviado apenas com seu nome base.
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}")

Além de um 400 para um upload que viola os requisitos de upload (413 para um corpo de requisição acima de 200 MB) e das respostas compartilhadas (um 403 quando marketplace_id é o marketplace pessoal de um membro; consulte Respostas de erro), uma criação pode falhar com:

Obter um plugin

GET /v1/organizations/plugins/{plugin_id} retorna um plugin. Requer o escopo read:plugins.

client = anthropic.Anthropic()

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

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

Alterar a versão servida

POST /v1/organizations/plugins/{plugin_id} altera qual versão de um plugin de propriedade da organização é servida aos membros. Passe uma versão anterior para reverter, ou uma mais recente para promover um build que foi armazenado sem ser servido. Isso "pins" (fixa) o plugin, e um plugin fixado atualmente não pode ser desafixado, nem aqui nem no claude.ai (consulte Versões e a versão servida). O único campo atualizável é served_version_id, e ele é obrigatório. A alteração chega aos membros antes de a resposta retornar e não cria uma versão. Quando a verificação de conteúdo está ativada, a versão deve ser uma que possa ser servida aos membros (consulte Verificação de conteúdo). Passar a versão já servida em um plugin fixado não altera nada; passá-la em um plugin não fixado o fixa nela, de modo que uploads posteriores deixam de ser servidos automaticamente. Retorna o plugin. Requer o escopo 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"
}

Além das respostas compartilhadas (um 403 para um plugin de propriedade de um membro, e 409 scan_pending ou 400 scan_failed para uma versão que não pode ser servida aos membros; consulte Respostas de erro), a requisição pode falhar com:

Excluir um plugin

DELETE /v1/organizations/plugins/{plugin_id} exclui permanentemente um plugin e todas as versões que ele contém, assim como a exclusão feita por um administrador no claude.ai. Funciona em qualquer plugin de um marketplace manual, incluindo o plugin de um membro, mesmo que esse membro já tenha saído da organização. Quando a exclusão retorna, o plugin, suas versões e seus arquivos desaparecem de todas as leituras, e ele deixa de ser servido aos membros. As configurações de instalação de um plugin de propriedade da organização são removidas junto com ele; os compartilhamentos de um plugin de propriedade de um membro são retirados, e ele também desaparece para seu proprietário. Um plugin em um marketplace sincronizado a partir do Git retorna 400: remova-o do repositório ou remova o marketplace no claude.ai. Requer o escopo write:plugins.

A exclusão não pode ser desfeita, e não há exclusão por versão. Para, em vez disso, retirar um plugin de propriedade da organização de forma reversível, defina sua configuração de instalação para toda a organização como not_available (um plugin que herdava o padrão de seu marketplace passa a manter uma configuração própria a partir de então) e remova (ou defina como not_available) cada configuração de grupo listada por GET /v1/organizations/plugins/{plugin_id}/installation_settings, porque a configuração de um grupo substitui o valor para toda a organização para seus membros. Envie essas gravações uma após a outra, não em paralelo (consulte Definir uma configuração de instalação). Um plugin de propriedade de um membro não pode ser retirado por meio desta API, exceto excluindo-o, e somente se seu marketplace for 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" }

Versões de plugin

Uma versão de plugin é um snapshot imutável dos arquivos de um plugin a partir de um upload (a resposta de Criar uma versão mostra um objeto completo). Seus campos espelham os campos de versão servida do plugin (display_name, description, manifest_version, content_scan, components, reach) para esta versão, além de release_notes (conforme fornecidas com o upload; exibidas no histórico de versões do claude.ai) e created_by (quem a enviou).

Um {version} sem o prefixo pluginver_ retorna 400 (exceto o literal latest onde indicado). Um que tenha o prefixo, mas não identifique uma versão desse plugin, retorna 404.

Listar as versões de um plugin

GET /v1/organizations/plugins/{plugin_id}/versions lista as versões de um plugin, ordenadas por created_at em ordem decrescente; o primeiro item é a versão identificada por latest_version_id. limit vai de 1 a 1.000. Requer o escopo read:plugins.

client = anthropic.Anthropic()

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

# Busca automaticamente mais páginas conforme necessário.
for version in versions:
    print(f"{version.id}: {version.manifest_version}")

Criar uma versão

POST /v1/organizations/plugins/{plugin_id}/versions adiciona uma versão a um plugin de propriedade da organização em um marketplace manual. O corpo é multipart/form-data, com os mesmos campos files[] e release_notes, os mesmos requisitos de upload e os mesmos erros de arquivo, manifesto, arquivo compactado e tamanho de Criar um plugin. O nome enviado (o name do manifesto) deve ser igual ao name do plugin. Se o plugin não estiver fixado, a nova versão é servida assim que é armazenada; se estiver fixado, a versão é armazenada, mas não é servida até que você altere a versão servida para ela. Para verificar, compare o id da resposta com o served_version_id do plugin. Retorna a versão. Requer o escopo 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"
}

Além de um 400 para um upload que viola os requisitos de upload (413 para um corpo de requisição acima de 200 MB) e das respostas compartilhadas (um 403 para um plugin de propriedade de um membro; consulte Respostas de erro), a requisição pode falhar com:

Obter uma versão

GET /v1/organizations/plugins/{plugin_id}/versions/{version} retorna uma versão. {version} é um ID de versão, ou latest para a versão identificada por latest_version_id no momento da requisição. Requer o escopo 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}")

Baixar os arquivos de uma versão

GET /v1/organizations/plugins/{plugin_id}/versions/{version}/content baixa os arquivos de uma versão como o arquivo compactado .zip armazenado (Content-Type: application/zip). O arquivo compactado é retornado independentemente do resultado da verificação de conteúdo, para que você possa inspecionar versões retidas dos membros. Ele é servido exatamente como foi armazenado, então, para um plugin de propriedade da organização em um marketplace manual, você pode reenviá-lo sem alterações como uma nova versão, desde que ele atenda aos requisitos de upload atuais. {version} deve ser um ID de versão, não latest: leia primeiro o served_version_id ou o latest_version_id do plugin, ou resolva latest com GET /v1/organizations/plugins/{plugin_id}/versions/latest. O nome de arquivo em Content-Disposition é derivado do nome do plugin e não é único; nomeie os arquivos salvos pelo ID do plugin e da versão. Requer o escopo read:plugins.

Baixar o arquivo compactado de um plugin de propriedade de um membro registra um evento claude_plugin_archive_accessed no Activity Feed da Compliance API, identificando a chave (como api_actor), o plugin e seu marketplace, a versão e o membro proprietário por ID; ele não contém nomes. Baixar o arquivo compactado de um plugin de propriedade da organização não registra nada.

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")

Configurações de instalação de plugin

Estes endpoints se aplicam a plugins de propriedade da organização. Eles retornam 404 para um plugin de propriedade de um membro, que tem compartilhamentos em vez disso. {target} é o literal organization para a configuração do plugin para toda a organização, ou o ID rbac_group_ de um grupo para a configuração desse grupo; qualquer outro valor retorna 400. Os IDs de grupo vêm de GET /v1/organizations/rbac_groups (escopo read:rbac_groups; consulte Gerenciamento de usuários). Uma configuração não tem um id próprio: ela é endereçada por (plugin_id, target), e nenhum ator é registrado nela (o ator está em seu evento de atividade plugin_installation_preference_updated).

Listar as configurações de instalação de um plugin

GET /v1/organizations/plugins/{plugin_id}/installation_settings lista as configurações que um plugin de propriedade da organização possui, ordenadas por created_at em ordem decrescente: sua própria configuração para toda a organização (ausente enquanto ele herda o padrão de seu marketplace) e a configuração de cada grupo. Filtre por target_type (organization ou rbac_group). Requer o escopo read:plugins.

client = anthropic.Anthropic()

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

# Busca automaticamente mais páginas conforme necessário.
for setting in settings:
    print(f"{setting.plugin_id}: {setting.installation_preference}")

Definir uma configuração de instalação

POST /v1/organizations/plugins/{plugin_id}/installation_settings/{target} define a configuração de instalação de um destino para um plugin de propriedade da organização, criando-a ou alterando o valor que ela já possui. O único campo do corpo é installation_preference (required, auto_install, available ou not_available), e ele é obrigatório. Definir o valor que o destino já possui não altera nada. Definir o destino organization faz o plugin deixar de herdar o padrão de seu marketplace (organization_installation_preference_inherited passa a ser false), mesmo quando o valor é igual ao padrão; isso não pode ser desfeito, porque a configuração para toda a organização não pode ser removida, então o plugin deixa de acompanhar alterações posteriores no padrão do marketplace. Um destino de grupo deve ser um grupo que sua organização consiga ver em GET /v1/organizations/rbac_groups; caso contrário, a requisição retorna 404. A alteração não modifica o updated_at do plugin; ela é registrada no Activity Feed. Retorna a configuração. Requer o escopo write:plugins.

Envie as gravações de configuração de instalação de um plugin uma de cada vez. Se várias gravações para o mesmo plugin chegarem ao mesmo tempo, o servidor as processa uma após a outra e pode responder a algumas delas com 503 em vez de aplicá-las. Esse 503 traz x-should-retry: true, e é seguro repetir a gravação: aguarde um ou dois segundos e envie-a novamente.

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"
}

Remover a configuração de instalação de um grupo

DELETE /v1/organizations/plugins/{plugin_id}/installation_settings/{target} remove a configuração de um grupo para um plugin de propriedade da organização. Os membros desse grupo passam a usar o valor para toda a organização, ou a configuração de outro de seus grupos. A configuração para toda a organização não pode ser removida depois de definida, assim como no claude.ai ({target} igual a organization retorna 400); em vez disso, altere seu valor. Um grupo que não possui configuração para este plugin retorna 404. A resposta traz a chave composta no lugar de um id. Requer o escopo 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" }
}

Compartilhamentos de plugin

Compartilhamentos existem apenas em plugins de propriedade de membros e são somente leitura nesta API (consulte Compartilhamentos).

Listar os compartilhamentos de um plugin

GET /v1/organizations/plugins/{plugin_id}/shares lista com quem o proprietário de um plugin de propriedade de um membro o compartilhou, ordenado por granted_at em ordem decrescente: todos os membros (organization), um grupo (rbac_group) ou um membro específico (organization_member). Filtre por target_type. Um plugin que seu proprietário não compartilhou retorna uma lista vazia; um plugin de propriedade da organização retorna 404. Os compartilhamentos são somente leitura nesta API, e um compartilhamento listado só concede acesso enquanto esse tipo de compartilhamento estiver ativado para sua organização no claude.ai (consulte Compartilhamentos). granted_at é quando o compartilhamento foi concedido; se o proprietário alterar o compartilhamento posteriormente no claude.ai, é o momento dessa alteração. Requer o escopo read:plugins.

client = anthropic.Anthropic()

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

# Busca automaticamente mais páginas conforme necessário.
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
}

Marketplaces de plugins

Esta API lê marketplaces e define a configuração de instalação padrão de um marketplace da organização; os próprios marketplaces são criados, conectados a um repositório e excluídos no 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"
}

Um marketplace_id sem o prefixo marketplace_ retorna 400. Um que tenha o prefixo, mas não seja resolvido ou pertença a outra organização, retorna 404.

Listar marketplaces

GET /v1/organizations/plugin_marketplaces lista os marketplaces da sua organização e os marketplaces pessoais dos membros, ordenados por created_at em ordem decrescente. Use-o para encontrar o ID de um marketplace, para filtrar a lista de plugins por ele ou para fazer upload nele, antes que ele contenha qualquer plugin. O marketplace da biblioteca aparece assim que algo é criado nele pela primeira vez, no claude.ai ou por meio desta API. Filtre por owner_type (organization ou user) e source. limit vai de 1 a 1.000. Requer o escopo read:plugins.

client = anthropic.Anthropic()

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

# Busca automaticamente mais páginas conforme necessário.
for marketplace in marketplaces:
    print(f"{marketplace.id}: {marketplace.name}")

Obter um marketplace

GET /v1/organizations/plugin_marketplaces/{marketplace_id} retorna um marketplace. Requer o escopo read:plugins.

client = anthropic.Anthropic()

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

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

Definir a configuração de instalação padrão de um marketplace

POST /v1/organizations/plugin_marketplaces/{marketplace_id} define a configuração de instalação padrão de um marketplace de propriedade da organização. Todo plugin no marketplace sem configuração própria para toda a organização informa esse padrão como seu organization_installation_preference, incluindo plugins adicionados posteriormente. Funciona para marketplaces manual e sincronizados; o marketplace pessoal de um membro retorna 403. O único campo atualizável é default_installation_preference, e ele é obrigatório. Ele não pode ser redefinido como null: depois que um marketplace tem um padrão, ele mantém um, como no claude.ai. Uma alteração é registrada como um único evento marketplace_updated, sem eventos por plugin, e não modifica o updated_at de nenhum plugin. Definir o valor já definido não altera nada, com uma exceção: um marketplace cujo padrão nunca foi definido informa not_available, mas não possui configuração, então sua primeira gravação (mesmo not_available) conta como uma alteração. Retorna o marketplace. Requer o escopo 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}")

Validar o conteúdo de um marketplace

Dois endpoints informam o que uma sincronização do conteúdo de marketplace fornecido faria, sem conectar nem armazenar nada: POST /v1/organizations/plugin_marketplaces/validate_repository lê um repositório público do GitHub, e POST /v1/organizations/plugin_marketplaces/validate_archive lê um .zip do diretório do marketplace que você envia. Ambos retornam o mesmo relatório: se marketplace.json está bem formado, quais plugins seriam ignorados e por quê, e quais plugins seriam sincronizados com parte de seu conteúdo deixada de fora. As verificações são as mesmas que uma sincronização real executa. Problemas com o conteúdo voltam no relatório, não como erros HTTP: a requisição é bem-sucedida com valid: false, mesmo quando o repositório ou o arquivo compactado não pode ser lido de forma alguma. Uma validação conta como uma leitura, e os dois endpoints juntos são adicionalmente limitados a 10 validações por minuto por organização (consulte Limitação de taxa); eles não registram nada no Activity Feed. Uma validação pode levar até 120 segundos para retornar, então defina o timeout do seu cliente acima disso. Ambos os endpoints exigem o escopo read:plugins ou write:plugins (read:org_audit e read:compliance_org_data não os concedem).

O repositório, e qualquer origem de plugin fora dele no GitHub, são lidos anonimamente, então um repositório privado ou uma origem de plugin privada é informado como não encontrado. Origens de plugin em hosts que não sejam o GitHub não são buscadas; esse tipo de plugin normalmente recebe um aviso marketplace_validate_source_not_checked e é verificado quando o marketplace é de fato sincronizado. Se o repositório for, ou o arquivo compactado nomear, um marketplace que a Anthropic sincroniza em todas as organizações, regras mais rígidas se aplicam: toda origem de plugin fora do marketplace deve estar fixada em um SHA de commit completo, origens não fixadas ou em hosts não suportados são informadas como erros de plugin, e o branch lido por padrão é aquele a partir do qual esse marketplace é sincronizado.

validate_repository recebe um corpo JSON com dois campos: repository_url, a URL https:// de um repositório público no github.com (obrigatório), e ref, um nome de branch ou um SHA de commit completo de 40 caracteres (opcional; quando omitido ou null, é usado o branch que uma sincronização leria, geralmente o branch padrão do repositório). validate_archive recebe multipart/form-data com exatamente uma parte, archive, enviada como uma parte de arquivo com um nome de arquivo: um .zip do diretório do marketplace, com no máximo 32 MB, com seu conteúdo na raiz ou envolvido em uma única pasta (como o download de um host Git produz), apenas com compressão DEFLATE ou STORE. Nenhum outro campo de formulário é aceito.

Validar um repositório público em um branch:

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"
        }
      ]
    }
  ]
}

Em vez disso, valide uma cópia local do diretório do marketplace, como um .zip; a resposta é o mesmo relatório:

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}")

Problemas com o conteúdo nunca fazem a requisição falhar. Além das respostas que todos os endpoints compartilham (um 403 para uma chave que tem apenas read:org_audit ou read:compliance_org_data; consulte Respostas de erro e Limitação de taxa), a própria requisição pode falhar com:

Códigos do relatório

Cada constatação em um relatório tem um código estável: manifest_error_code quando nada pôde ser validado, error_code em cada entrada de plugin_errors e error_code em cada aviso. Quando um plugin tem vários problemas, error_code é o do primeiro e error junta suas mensagens. Novos códigos podem ser adicionados; um manifest_error_code não reconhecido ainda significa que o conteúdo não pôde ser validado, um em uma entrada de plugin_errors ainda significa que o plugin seria ignorado, e um em um aviso ainda significa que o plugin seria sincronizado. Estes códigos indicam condições transitórias, então a mesma requisição pode ser bem-sucedida mais tarde: 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 e, geralmente, marketplace_validate_deadline_exceeded.

Valores não reconhecidos

Todo valor de string nesta página (tipos de componente, reach, campos de verificação, source de marketplace, códigos de erro) pode ganhar novos valores a qualquer momento. Trate um valor que você não reconhece como trataria qualquer string desconhecida, em vez de falhar.

Limitação de taxa

As requisições de leitura (todos os endpoints GET desta página) compartilham um "rate limit" (limite de taxa) de 300 requisições por minuto por organização, e as requisições de gravação (criar um plugin ou versão, alterar a versão servida, excluir, definir ou remover uma configuração de instalação e atualizar um marketplace) compartilham um limite de 60 requisições por minuto por organização. Uma validação de marketplace (em qualquer um dos endpoints) conta como uma leitura, e as validações são adicionalmente limitadas a 10 por minuto por organização somando os dois endpoints; ambos os limites são verificados antes de o corpo da requisição ser lido. Esses limites são contabilizados em todas as chaves da sua organização e são separados dos outros limites da Admin API da sua organização. Requisições acima de um limite retornam 429 Too Many Requests com um cabeçalho retry-after. As respostas incluem cabeçalhos anthropic-ratelimit-requests-* para o limite aplicável (na validação de marketplace, seu limite de 10 por minuto; em um 429, o limite que recusou a requisição).

Um upload, uma alteração de versão servida ou uma validação também pode retornar 429 com retry-after quando o serviço momentaneamente não tem capacidade para mais uma operação, e um upload retorna 429 quando sua organização excedeu sua taxa de verificação de conteúdo. Trate todos esses casos da mesma forma: aguarde o retry-after e tente novamente. Independentemente desses limites, envie as gravações de configuração de instalação para o mesmo plugin uma de cada vez: quando várias chegam ao mesmo tempo, algumas podem ser respondidas com 503 e x-should-retry: true, e é seguro enviá-las novamente após um ou dois segundos (consulte Definir uma configuração de instalação).

Paginação

Os endpoints de listagem usam um cursor opaco. A primeira requisição retorna até limit linhas mais um cursor next_page; passe o cursor sem alterações como o parâmetro page na próxima requisição e repita até que next_page seja null. Trate a string do cursor como opaca: não a analise, modifique ou construa você mesmo. Listar plugins pode retornar uma página com menos de limit plugins, ou nenhum, enquanto next_page ainda está definido, então continue solicitando páginas até que next_page seja null. Os iteradores de listagem dos SDKs buscam páginas adicionais conforme você itera, mas param na primeira página vazia, então, na lista de plugins, eles podem terminar antes do tempo; quando você precisar de todos os plugins, como no fluxo de trabalho de inventário de segurança, solicite cada página você mesmo e passe seu next_page como page.

limit tem padrão 20 e mínimo 1. O máximo é 100 para plugins, configurações de instalação e compartilhamentos, e 1.000 para versões e marketplaces. Toda lista é ordenada da mais recente para a mais antiga.

Respostas de erro

As respostas de erro seguem o formato padrão documentado em Erros. Informe o request_id do corpo da resposta ao entrar em contato com o suporte.

Quando um status tem várias causas que você trataria de forma diferente, o erro também inclui error.details.error_code e, quando a causa envolve um deles, error.details.plugin_id ou 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"
}

Novos códigos podem ser adicionados. Trate um código que você não reconhece da mesma forma que trata o status correspondente.

Repetindo uploads

Nenhum endpoint aceita um Idempotency-Key. Alterar a versão servida, definir uma configuração de instalação e definir um padrão de marketplace são operações seguras para repetir. Uma exclusão repetida, ou uma remoção repetida da configuração de instalação de um grupo, retorna 404.

Um upload que retorna um erro não armazenou nada, com uma exceção: 503 com error_code: "registration_pending". Depois de armazenar os arquivos de um upload, o servidor registra as skills da nova versão no claude.ai, o que as torna utilizáveis pelos membros; registration_pending significa que os arquivos foram armazenados, mas essa última etapa não foi concluída. Fazer o upload dos mesmos arquivos mais uma vez a conclui (e armazena mais uma versão idêntica):

• Em POST /v1/organizations/plugins, o plugin foi criado, e a resposta inclui x-should-retry: false: não reenvie a criação (um reenvio retorna 409 plugin_name_taken); em vez disso, faça o upload dos mesmos arquivos como uma versão de details.plugin_id.
• Em POST /v1/organizations/plugins/{plugin_id}/versions, a versão foi armazenada (details.plugin_version_id); reenvie a mesma solicitação quando a resposta incluir x-should-retry: true, e não reenvie quando incluir false.

Se a resposta de uma criação for perdida, tente novamente: a nova tentativa retorna 409 plugin_name_taken com o ID do plugin em details.plugin_id, e você continua com esse plugin. Repetir uma criação de versão cuja resposta foi perdida armazena uma segunda versão idêntica. Para evitar isso, registre o latest_version_id do plugin antes de cada upload; se uma resposta for perdida, leia o plugin e tente novamente somente se latest_version_id não tiver mudado.

Eventos do Activity Feed

Toda gravação feita por meio desta API é registrada no Compliance API Activity Feed da sua organização, atribuída à chave de API como um api_actor que contém seu ID apikey_. O mesmo ator aparece em created_by nos plugins e nas versões que a chave cria.

Os IDs de plugin, versão e marketplace nesses eventos são os mesmos IDs que esta API retorna. plugin_installation_preference_updated identifica o plugin por seu name e marketplace_id em vez de seu id.

Alterar o padrão de um marketplace registra um evento marketplace_updated e nenhum evento por plugin, mesmo que isso altere o valor de todos os plugins que herdam o padrão. Leituras não são registradas, exceto downloads do arquivo de um plugin pertencente a um membro. Uma gravação que não altera nada não registra nada.

Compartilhamentos concedidos ou retirados no claude.ai aparecem no feed como eventos role_assignment_granted e role_assignment_revoked. Esta API não informa exclusões: um plugin excluído simplesmente não aparece na próxima listagem. Um plugin removido por uma sincronização do Git, pela exclusão de seu marketplace (um evento marketplace_deleted) ou pela exclusão da conta de um membro ou da organização não emite nenhum evento por plugin; portanto, liste novamente o inventário completo periodicamente para detectar remoções.

Chaves de criptografia gerenciadas pelo cliente

Se sua organização usa uma "customer-managed encryption key" (chave de criptografia gerenciada pelo cliente), os campos description, release_notes e components e os arquivos de uma versão são criptografados com ela. Enquanto a chave estiver indisponível:

• Leituras e listagens continuam funcionando, com description, release_notes e components retornados como null.
• Downloads de arquivos, criações, criações de versão e alterações da versão servida retornam 400 com cmek_key_disabled ou cmek_key_network_blocked.
• Excluir um plugin no marketplace da biblioteca retorna 400 cmek_key_disabled e não exclui nada, porque suas skills precisam primeiro ser retiradas do claude.ai, e isso requer a chave. Outras exclusões, configurações de instalação e padrões de marketplace funcionam normalmente.

Restaurar a chave resolve todas essas situações.

Veja também