Claude Platform Docs
AdministraçãoOrganização

API de Plugins

Inventarie e gerencie os plugins da sua organização Claude Enterprise: faça upload de plugins e versões, escolha a versão servida aos membros, controle quem pode usar cada plugin, baixe arquivos de plugins para revisão e valide um marketplace antes de conectá-lo.

A API de Plugins permite que você faça o seguinte:

  • Fazer o inventário dos plugins da sua organização Claude Enterprise
  • Publicar plugins e novas versões a partir dos seus próprios pipelines
  • Escolher qual versão é servida aos membros
  • Controlar quem pode usar cada plugin
  • Baixar os arquivos de plugins para revisão
  • Verificar 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:

RecursoEndpoints
Plugins: listar os plugins da organização, fazer upload de um novo, consultar um, escolher a versão servida aos membros (reverter ou promover), excluir umGET /v1/organizations/plugins
POST /v1/organizations/plugins
GET /v1/organizations/plugins/{plugin_id}
POST /v1/organizations/plugins/{plugin_id}
DELETE /v1/organizations/plugins/{plugin_id}
Versões de plugin: listar o histórico de versões de um plugin, fazer upload de uma nova versão, consultar uma, baixar os arquivos de uma versãoGET /v1/organizations/plugins/{plugin_id}/versions
POST /v1/organizations/plugins/{plugin_id}/versions
GET /v1/organizations/plugins/{plugin_id}/versions/{version}
GET /v1/organizations/plugins/{plugin_id}/versions/{version}/content
Configurações de instalação: ler quem pode usar um plugin de propriedade da organização, defini-lo para toda a organização ou para um grupo, remover qualquer uma das configuraçõesGET /v1/organizations/plugins/{plugin_id}/installation_settings
POST /v1/organizations/plugins/{plugin_id}/installation_settings/{target}
DELETE /v1/organizations/plugins/{plugin_id}/installation_settings/{target}
Compartilhamentos: ler com quem um membro compartilhou seu próprio plugin (somente leitura)GET /v1/organizations/plugins/{plugin_id}/shares
Marketplaces de plugins: encontrar o ID de um marketplace, consultar um, definir a configuração de instalação padrão para seus plugins, verificar o conteúdo de um marketplace antes de conectá-loGET /v1/organizations/plugin_marketplaces
GET /v1/organizations/plugin_marketplaces/{marketplace_id}
POST /v1/organizations/plugin_marketplaces/{marketplace_id}
POST /v1/organizations/plugin_marketplaces/validate_repository
POST /v1/organizations/plugin_marketplaces/validate_archive

Plugins publicados pela Anthropic 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

Em Python, TypeScript, C#, Go, Java, PHP e Ruby, o SDK expõe estes endpoints em client.beta.organization, e a CLI ant em ant beta:organization; eles enviam os cabeçalhos anthropic-version e anthropic-beta por você. Os exemplos desta página leem a chave de API de Admin da variável de ambiente ANTHROPIC_API_KEY. Onde um SDK ou a CLI busca mais páginas por você, limit define o tamanho da página, não o total (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

EscopoConcede
read:pluginsTodos os endpoints GET desta página, incluindo downloads de arquivos compactados, além da validação de marketplace.
write:pluginsTodos os endpoints POST e DELETE desta página: criar um plugin, criar uma versão, alterar a versão servida, excluir um plugin, definir e remover configurações de instalação e definir o padrão de um marketplace, além da validação de marketplace. Não concede leituras.
read:org_auditUm escopo somente leitura para integrações de auditoria de segurança: todos os endpoints GET desta página, incluindo downloads de arquivos compactados, além dos endpoints de leitura de gerenciamento de usuários e da Compliance API. Não concede validação de marketplace nem qualquer escrita.
read:compliance_org_dataO escopo da Compliance API para metadados da organização (nomes, tipos, funções e grupos) e configurações efetivas. Concede todos os endpoints GET desta página, exatamente como read:org_audit, de modo que uma Compliance Access Key pode ler plugins sem uma segunda chave. Não concede validação de marketplace nem qualquer escrita.

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. Algumas empresas têm várias organizações Claude vinculadas sob uma organização pai. Uma chave read:org_audit ou read:compliance_org_data criada para todas as organizações vinculadas também pode ler qualquer organização vinculada que tenha acesso a esta API. Para ler uma delas, passe o ID dela 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 prefixo org_ também é aceita). Sem o parâmetro, a chave lê a organização em que foi criada. Uma chave sem organização própria deve sempre passar organization_id. Um 404 significa que a organização indicada não está sob o pai 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:

ComponenteO que é
SkillInstruções e arquivos que o Claude carrega quando uma tarefa os exige.
ComandoUm prompt salvo que um membro executa digitando / seguido do nome do comando.
AgenteUm assistente auxiliar com suas próprias instruções, ao qual o Claude pode delegar parte de uma tarefa.
HookUm comando que é executado automaticamente quando ocorre um evento em uma sessão, como antes de o Claude usar uma ferramenta.
Servidor MCPUma conexão do Claude com ferramentas e dados em outro sistema (“Model Context Protocol”, ou MCP).
CLIUm programa de linha de comando que o plugin permite que o Claude execute.

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 removidos do inventário 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 nova
  • served_version_id: a versão servida aos membros

Por padrão, served_version_pinned é false: a versão servida normalmente acompanha a mais nova. Quando a varredura de conteúdo está ativada, uma versão salva no claude.ai pode aguardar a varredura de conteúdo: ela é armazenada, mas não é servida imediatamente. Esta página usa “aguardar” apenas para uma versão salva no claude.ai, não para uma que um membro ou um administrador publica em um plugin. Enquanto a varredura estiver ativada, uma versão em espera só é servida quando seu content_scan indica completed com pass ou warn. Enquanto uma versão aguarda, served_version_id aponta para uma versão anterior à de latest_version_id. Não faça polling até que os dois IDs coincidam: eles podem continuar diferentes, por exemplo, quando a varredura falha.

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 envie cada build, teste-o e depois o promova. Para que o seu pipeline determine quando cada build é servido, fixe o plugin uma vez definindo served_version_id para a 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 enquanto o content_scan da versão atual indicar processing, e 400 scan_failed se a verificação indicar fail, unknown ou errored (warn é aceito). Um plugin fixado não pode ser desfixado, 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 configurações de instalação determinam quem pode usar um plugin de propriedade da organização. Cada configuração tem um de quatro valores, transportados nos campos chamados installation_preference (e, nos objetos de plugin e de marketplace, organization_installation_preference e default_installation_preference):

ValorO que os membros veem
requiredO plugin está instalado e não pode ser removido.
auto_installO plugin está instalado e pode ser removido.
availableO plugin pode ser instalado mediante solicitação.
not_availableO plugin fica oculto.

Um plugin pode ter uma configuração para toda a organização e uma configuração para cada 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 Piloto tiver available, os membros do Piloto 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 faz com que o plugin deixe de herdar o padrão do seu marketplace; remover a configuração para toda a organização retorna o plugin a esse padrã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 compartilhamentos determinam 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 varredura estiver ativada, um plugin só é servido aos membros quando a varredura da sua versão servida está completed com pass ou warn. Enquanto a varredura estiver processing ou errored, ou indicar fail ou unknown, o plugin fica retido dos membros, e uma versão anterior não é servida no lugar dele. Uma versão que nunca foi verificada (content_scan: null) é servida normalmente.

Uma versão que você envia por meio desta API nunca aguarda a varredura de conteúdo. Quando ela se torna a versão servida, os membros perdem o plugin até que o content_scan dela indique completed com pass ou warn. 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).

Enquanto uma versão salva no claude.ai aguarda sua verificação, a versão servida não muda. Quando seu envio pela API se torna a versão servida, qualquer espera termina: a versão em espera só é servida se alguém a escolher. Para ver a verificação de uma versão em espera, leia a versão (consulte Listar as versões de um plugin).

Após um envio, 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. Enquanto a verificação estiver ativada, alterar a versão servida para uma versão cujo content_scan indica processing retorna 409 scan_pending, e alterá-la para uma cuja verificação indica fail, unknown ou errored retorna 400 scan_failed.

Verificações com falha permitidas no claude.ai

No claude.ai, os proprietários da organização podem permitir uma versão cuja verificação falhou. O mesmo vale para membros cuja função personalizada pode gerenciar Bibliotecas. Esta API pode então informar essa verificação como completed com warn e o reason da verificação com falha. Enquanto isso ocorrer, as regras de warn se aplicam: a versão pode ser servida aos membros, e você pode torná-la a versão servida. Nada na resposta mostra que ela foi permitida, então um warn é ou um aviso ou uma verificação com falha que foi permitida. Permitir uma versão cuja verificação indica warn não altera seu content_scan. Quando uma versão deixa de ser permitida, esta API informa o veredito da sua verificação concluída mais recente. Uma versão servida cuja verificação passa a indicar fail ou unknown é retida dos membros.

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:

ValorSignificado
remoteDeclara um servidor MCP ou uma CLI, independentemente do que mais declare.
privilegedNão declara servidor MCP nem CLI, mas declara um hook, um monitor (um comando em segundo plano que continua em execução durante uma sessão), um servidor LSP (Language Server Protocol), um workflow (um script que o Claude Code pode executar; qualquer arquivo em uma pasta workflows/ na raiz do plugin conta como um) ou configurações que o plugin aplica ao aplicativo do membro, ou contém uma skill, um comando ou qualquer outro arquivo Markdown cujo frontmatter pré-aprova ferramentas (allowed-tools). Esses são executados, ou entram em vigor, no próprio computador do membro.
containedNão declara servidor MCP, CLI, hook, monitor, servidor LSP, workflow nem configurações de aplicativo, e nenhum de seus arquivos Markdown pré-aprova ferramentas (por exemplo, um plugin que contém apenas skills, comandos e agentes, nenhum com allowed-tools).

reach considera tudo o que a versão declara, incluindo monitores, servidores LSP, workflows e configurações de aplicativo, que components não lista, de modo que 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 o SKILL.md de uma de suas skills, ou um de seus arquivos de comando, não pôde ser lido; trate null como não classificado. O valor normalmente é calculado quando uma versão é armazenada, de acordo com as regras vigentes naquele momento. Assim, uma versão mais antiga pode ser contained enquanto os mesmos arquivos armazenados hoje seriam privileged.

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. Um description que o manifesto obtém desse SKILL.md é cortado para seus primeiros 500 caracteres.
  • 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 comandos, não podem compartilhar um nome.
  • Nenhum arquivo pode estar em um diretório bin/ de nível superior.
  • Nenhum arquivo .zip aninhado. Servidores MCP 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 envio 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 upload que cria um plugin retorna 400 quando o marketplace já contém 1.000 plugins. Plugins que esta API não lista também contam, então o limite pode ser atingido enquanto Listar plugins mostra menos de 1.000 nesse marketplace. A Anthropic pode aumentar o limite de 5.000 arquivos.

Fluxos de trabalho de exemplo

Publicar cada build a partir de um pipeline de release

Envie cada build com tag a partir do CI e deixe o pipeline determinar 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 marketplace da biblioteca.
  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 (consulte Grupos e funções em Gerenciamento de usuários). Os próximos passos precisam de write:plugins, que atua apenas na organização em que sua chave foi criada; então, em uma empresa com várias organizações vinculadas, crie uma única chave na organização que contém o plugin e dê a ela ambos os escopos, ou use uma segunda chave criada lá para esses passos.

  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 com a chamada a seguir e depois remova a configuração do grupo para que o grupo volte a seguir a organização. Definir o valor para toda a organização faz com que o plugin deixe de herdar o padrão do seu marketplace; remover a configuração para toda a organização posteriormente retorna o plugin a esse padrão.

    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 cuja varredura de conteúdo indica warn, fail ou unknown.

  1. Percorra as páginas de GET /v1/organizations/plugins?limit=100 até que next_page seja null (consulte Paginação). Leia o reach e o content_scan de cada plugin nessa lista em toda execução: uma alteração apenas em content_scan, como um veredito que chega depois, não altera updated_at. updated_at normalmente indica quais plugins têm conteúdo novo ou uma nova versão servida desde a última execução (vale um novo download do arquivo compactado). Uma versão em espera (consulte Versões e a versão servida) altera updated_at quando se torna a versão servida, não necessariamente quando é armazenada. Para notar uma, compare latest_version_id com o valor da sua última execução. 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 um evento.
  2. Sinalize cada plugin cujo reach seja remote (ele declara um servidor MCP ou uma CLI), ou cujo content_scan.assessment seja warn, fail ou unknown. Um warn também pode ser uma verificação com falha que foi permitida no claude.ai. Deixe warn de fora somente se você aceitar toda verificação com falha que for permitida lá. Esses campos descrevem a versão servida. Para verificar também uma versão mais nova que não é servida, liste as versões do plugin quando latest_version_id for diferente de served_version_id (consulte Listar as versões de um plugin).
  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). Baixe também, pelo seu ID, qualquer versão não servida que atenda ao critério da etapa 2.
  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.

CampoDescrição
idCom o prefixo plugin_.
nameVem do manifesto. Único dentro do seu marketplace, não em toda a organização. Fixo para um plugin de propriedade da organização; muda se um membro renomear seu próprio plugin no claude.ai.
display_name, description, manifest_versionOs campos displayName, description e version do manifesto da versão servida; cada um é null quando o manifesto não declara nenhum. description pode ser o description de uma skill em vez do do manifesto (descrito após esta tabela). manifest_version é normalizado para exibição: um v ou V inicial é removido, de modo que um version de manifesto igual a "v1.4.0" é retornado como "1.4.0". Também é null para um valor que não se parece com um número de versão, como "latest", e para uma versão de plugin criada antes de o claude.ai começar a registrar este campo em agosto de 2026. Um upload nunca é recusado por causa do seu version, e manifest_version não é único.
served_version_id, latest_version_idCom o prefixo pluginver_: a versão servida aos membros e a versão mais recente. Consulte Versões e a versão servida.
served_version_pinnedfalse até que o plugin seja fixado (consulte Versões e a versão servida); true a partir de então.
owner{"type": "organization"}, ou {"type": "user", "user_id": "user_..."} para o marketplace pessoal de um membro.
marketplace_idCom o prefixo marketplace_.
created_byQuem criou o plugin: {"type": "user_actor", "user_id": "user_...", "email_address": "..."} para uma pessoa no claude.ai (email_address pode ser null), ou {"type": "api_actor", "api_key_id": "apikey_..."} para uma chave de API. Outros tipos de ator podem aparecer. null quando nenhum criador está registrado, como no caso de plugins sincronizados a partir do Git.
organization_installation_preference, organization_installation_preference_inheritedDe propriedade da organização: o valor para toda a organização e se ele vem do padrão do marketplace (consulte Configurações de instalação). De propriedade de um membro: ambos null.
content_scanO resultado da verificação da versão servida, um objeto com status, assessment e reason (descritos após esta tabela). null quando ela nunca foi verificada.
componentsOs componentes da versão servida, cada um {"type", "name", "description"} com type sendo um de skill, mcp_server, command, agent, hook ou cli, listados nessa ordem de tipo e depois por nome. Para um servidor MCP, name é sua chave no manifesto; para um hook, o evento em que ele é executado; para uma CLI, o nome do executável. description é sempre null para servidores MCP, hooks e CLIs. null quando não registrado.
reachcontained, privileged ou remote. Consulte Alcance.
updated_atMuda quando a versão servida muda, quando o plugin é fixado e, normalmente, quando uma nova versão é armazenada. Uma versão em espera (consulte Versões e a versão servida) o altera quando se torna a versão servida, não necessariamente quando é armazenada. Não muda para configurações de instalação, compartilhamentos ou uma alteração apenas em content_scan.

description nem sempre é o do manifesto. Um description que o manifesto obtém de um SKILL.md de nível superior é cortado para seus primeiros 500 caracteres (consulte Requisitos de upload). Se o description do manifesto for os primeiros 500 caracteres de exatamente um description de skill distinto em components, a API retorna esse description de skill em vez dele. Como resultado:

  • Um description que você lê pode ter mais de 500 caracteres, o limite para um manifesto enviado. Um envio cujo plugin.json define tal description retorna 400.
  • Nos arquivos que você baixa, .claude-plugin/plugin.json pode ter um description diferente, ou nenhum.

O objeto content_scan:

CampoDescrição
statusprocessing enquanto a verificação é executada, completed quando ela terminou, ou errored quando não pôde terminar (ou, ocasionalmente, quando seu resultado não pôde ser lido para esta resposta; nesse caso, uma leitura posterior pode relatá-lo). É relatada a verificação concluída mais recente, se houver. Os membros não recebem uma versão cujo status seja processing ou errored; enviar o conteúdo novamente como uma nova versão obtém uma nova verificação.
assessmentDefinido quando status é completed: pass (nada encontrado), warn (algo encontrado que não bloqueia o uso, ou uma verificação com falha que foi permitida no claude.ai), fail (algo encontrado que bloqueia o uso) ou unknown (sem veredito). Caso contrário, null.
reasonPara warn e fail, a principal preocupação, da lista a seguir. Caso contrário, null, e também null em uma verificação mais antiga, anterior ao registro de motivos.

Um plugin_id sem o prefixo plugin_ retorna 400. Um plugin_id que tem o prefixo, mas não está no inventário da sua organização retorna 404.

Listar plugins

GET /v1/organizations/plugins lista 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 (um ID com prefixo user_, que encontra 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 no 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 versão servida. O corpo é multipart/form-data: files[] é um único arquivo .zip ou .plugin, ou uma parte para cada 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 ou, por padrão, seu marketplace de biblioteca, que é criado no primeiro uso) e release_notes (até 5.000 caracteres, exibidos no histórico de versões do claude.ai e retornados na versão). Os campos name, display_name, description e manifest_version do plugin vêm dos arquivos enviados, e o upload deve atender aos requisitos de upload. Quando a 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 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, por isso 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:

StatusCausaO que fazer
404marketplace_id não é um marketplace da sua organização.Obtenha o ID em Listar marketplaces.
400O marketplace é sincronizado a partir do Git, ou já contém 1.000 plugins (consulte Requisitos de upload).Faça o upload para outro marketplace manual ou, em vez disso, altere o repositório.
409 plugin_name_takenO nome já está em uso nesse marketplace.Envie uma versão para details.plugin_id somente se for o plugin que você pretendia atualizar, pois outra pessoa pode tê-lo criado. Caso contrário, ou quando details.plugin_id estiver ausente, envie com outro nome (altere o name do manifesto).
409 skill_name_takenO plugin está indo para o marketplace da biblioteca e uma de suas skills tem o nome de uma skill da organização.Renomeie a skill ou remova a skill da organização no claude.ai.
409 (sem error_code)Outro upload com o mesmo nome para o mesmo marketplace está em andamento, ou um plugin que esta API não lista detém o nome.Tente novamente com backoff. Se o 409 persistir por mais de alguns minutos, faça o upload com outro nome (altere o name do manifesto).
503 registration_pendingO plugin foi criado, mas seu registro não foi concluído.Não reenvie; envie os mesmos arquivos como uma versão de details.plugin_id (consulte Repetindo uploads).

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 fixa o plugin, e um plugin fixado 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 que a resposta seja retornada 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 nessa versão, de modo que uploads posteriores deixam de ser servidos automaticamente. A fixação também encerra qualquer espera: uma versão que estava aguardando sua verificação de conteúdo permanece armazenada e só é servida se alguém a escolher. 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:

StatusCausaO que fazer
400O corpo omite served_version_id, define-o como null ou contém qualquer outro campo; ou o valor não tem o prefixo pluginver_ ou é latest.Envie exatamente {"served_version_id": "pluginver_..."}.
404served_version_id não é uma versão deste plugin.Obtenha o ID em Listar as versões de um plugin.
409 (sem error_code)Um upload para este plugin ou outra alteração de versão servida ainda está em andamento.Tente novamente em breve.
409 skill_name_takenO plugin está no marketplace da biblioteca e a versão tem uma skill cujo nome agora é usado por uma skill da organização.Escolha outra versão ou renomeie uma das skills.

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 estava herdando o padrão do seu marketplace recebe uma configuração própria, e remover essa configuração para toda a organização posteriormente retorna o plugin ao padrão), e remova (ou defina como not_available) cada configuração de grupo que GET /v1/organizations/plugins/{plugin_id}/installation_settings lista, 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 pertencente a 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 da versão servida do plugin (display_name, description, manifest_version, content_scan, components, reach) para esta versão, além de release_notes (conforme fornecido com o upload e exibido 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, requisitos de upload e erros de arquivo, manifesto, arquivo compactado e tamanho que 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 normalmente é 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 membro; consulte Respostas de erro), a requisição pode falhar com:

StatusCausaO que fazer
400O plugin está em um marketplace sincronizado a partir do Git, ou o nome enviado difere do nome do plugin.Em vez disso, altere o repositório ou corrija o name do manifesto.
409 (sem error_code)Outro upload para este plugin, ou uma alteração de versão servida, ainda está em andamento.Tente novamente em breve.
409 skill_name_takenO plugin está no marketplace da biblioteca e a versão adiciona uma skill com o nome de uma skill da organização.Renomeie a skill ou remova a skill da organização no claude.ai.
503 registration_pendingA versão foi armazenada, mas seu registro não foi concluído.Reenvie a mesma requisição quando a resposta trouxer x-should-retry: true (consulte Repetindo uploads).

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 .zip armazenado (Content-Type: application/zip). O arquivo é retornado independentemente do resultado da sua verificação de conteúdo, para que você possa inspecionar versões retidas dos membros. Ele é servido exatamente como foi armazenado, portanto, 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 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 membro, que tem compartilhamentos em vez disso (consulte Compartilhamentos de plugin). {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 Grupos em Gerenciamento de usuários). Uma configuração não tem id próprio: ela é endereçada por (plugin_id, target), e nenhum ator é registrado nela (o ator está no 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 alvo 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 alvo já possui não altera nada. Definir o alvo organization faz o plugin deixar de herdar o padrão do seu marketplace (organization_installation_preference_inherited passa a ser false), mesmo quando o valor é igual ao padrão, de modo que o plugin não acompanha mais alterações posteriores no padrão do marketplace. Para retornar o plugin ao padrão do seu marketplace, remova a configuração para toda a organização; as configurações de grupo não são afetadas. Um alvo de grupo deve ser um grupo que sua organização consegue 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 uma configuração de instalação

DELETE /v1/organizations/plugins/{plugin_id}/installation_settings/{target} remove a configuração de instalação de um alvo para um plugin de propriedade da organização. Com {target} igual a organization, remove a própria configuração do plugin para toda a organização. O plugin então volta a herdar o padrão do seu marketplace (organization_installation_preference_inherited passa a ser true) e acompanha alterações posteriores nesse padrão; as configurações de grupo não são afetadas. Com o ID rbac_group_ de um grupo, remove a configuração desse grupo: os membros do grupo passam a usar o valor para toda a organização, ou a configuração de outro de seus grupos. Um alvo que não possui configuração própria retorna 404; isso inclui o alvo organization de um plugin que já herda o padrão do seu marketplace. A alteração não modifica o updated_at do plugin; ela é registrada no Activity Feed. A resposta traz a chave composta no lugar de um id; para o alvo organization, seu target é {"type": "organization"}. 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"
}
CampoDescrição
nameO nome do marketplace. Fixo durante toda a sua existência.
ownerMesmo formato que no plugin.
sourcemanual, github, gitlab ou public_git. Consulte Marketplaces.
sync_statusResultado da sincronização mais recente: success, in_progress, failed_content, failed_transient, failed_auth ou failed_limits. null até que uma sincronização seja tentada pela primeira vez, o que nunca ocorre para um marketplace cuja origem é manual.
last_sync_ended_atQuando a tentativa de sincronização mais recente terminou, qualquer que tenha sido seu resultado; para um repositório conectado que ainda não foi sincronizado, quando o marketplace foi criado. null para um marketplace que não é sincronizado.
last_sync_read_shaO commit que a última sincronização leu do repositório. Não necessariamente o commit de onde vieram as versões servidas. null para um marketplace que não é sincronizado.
default_installation_preferenceMarketplaces da organização: o valor para toda a organização de cada plugin nele sem configuração própria (not_available se nunca definido). Marketplaces pessoais: null.

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 o marketplace.json está bem formado, quais plugins seriam ignorados e por quê, e quais plugins seriam sincronizados com parte do 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 solicitação é bem-sucedida com valid: false, mesmo quando o repositório ou o arquivo 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 para cada 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, portanto 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).

A validação lê o repositório anonimamente. Ela faz o mesmo para qualquer fonte de plugin que esteja no GitHub, mas fora do repositório. Como resultado, a validação relata um repositório privado ou uma fonte de plugin privada como não encontrados ou como exigindo login no GitHub. Quando a validação relata que um login no GitHub é necessário, o código do relatório é marketplace_repo_sign_in_required.

A validação não busca fontes de plugin em hosts diferentes do GitHub. Um plugin com tal fonte normalmente recebe um aviso marketplace_validate_source_not_checked e é verificado quando o marketplace é de fato sincronizado.

A validação aplica regras mais rígidas a um marketplace que a Anthropic sincroniza em todas as organizações. validate_repository as aplica quando o repositório é um desses marketplaces. validate_archive as aplica quando o arquivo nomeia um desses marketplaces. As regras mais rígidas são as seguintes:

  • Toda fonte de plugin fora do marketplace deve estar fixada em um SHA de commit completo.
  • A validação relata fontes não fixadas e fontes em hosts não suportados como erros de plugin.
  • Para validate_repository, a branch que a validação lê tem como padrão a branch a partir da qual o 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 ref é omitido ou null, o padrão é 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. O arquivo é um .zip do diretório do marketplace, com no máximo 32 MB, que usa apenas compressão DEFLATE ou STORE. O conteúdo do arquivo fica na raiz ou envolvido em uma única pasta (como produz o download de um host Git). 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"
        }
      ]
    }
  ]
}
CampoDescrição
validtrue quando marketplace.json está bem formado e nenhum plugin seria ignorado. Avisos não o tornam false.
refO branch que foi lido, pelo nome; null quando nenhum branch foi nomeado e o branch padrão foi lido, para um SHA de commit ou para um arquivo compactado.
commit_shaO commit que foi validado. Para um arquivo compactado baixado de um host Git, o commit que o host registrou no campo de comentário do arquivo ZIP, se houver (não verificado).
total_plugin_countQuantos plugins marketplace.json declara; 0 quando não pôde ser lido.
manifest_error, manifest_error_codeDefinido quando nada pôde ser validado: a fonte não pôde ser lida, ou o marketplace.json está ausente, malformado ou acima de um limite. Uma validação que não foi concluída em 120 segundos reporta manifest_error_code: "marketplace_validate_deadline_exceeded".
plugin_errorsUm {name, error, error_code} por plugin que uma sincronização ignoraria.
plugin_warningsUm {name, warnings: [{message, error_code}]} por plugin que seria sincronizado com parte de seu conteúdo deixada de fora.

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:

StatusCausaO que fazer
400Em validate_repository: o corpo não é um objeto JSON; repository_url está ausente, tem mais de 2.048 caracteres, contém credenciais, ou não está no formato https://github.com/{owner}/{repo} (um sufixo .git é aceito; outro host, um caminho mais longo como o /tree/main de uma página de branch, ou uma porta diferente de 443 ou 80 não é); ref está vazio, tem mais de 255 caracteres, contém .., ou contém um caractere diferente de letras ASCII, dígitos, ., _, -, + e /; ou outro campo está presente. Um ref que passa nessas verificações mas nomeia um branch que o repositório não tem não é recusado: a solicitação é bem-sucedida com valid: false e manifest_error diz que o branch não foi encontrado. Em validate_archive: o corpo não é multipart/form-data, a parte archive está ausente, repetida, ou não foi enviada como uma parte de arquivo com um nome de arquivo, ou outro campo de formulário está presente.Corrija a solicitação e reenvie.
413Em validate_archive: a parte archive, ou o tamanho de corpo declarado da requisição, excede 32 MB.Em vez disso, valide o repositório pela URL ou reduza o arquivo compactado.

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, portanto a mesma solicitaçã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

Solicitações de leitura (todo endpoint GET nesta página) compartilham um limite de 300 solicitações por minuto para cada organização. Solicitações de escrita (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 solicitações por minuto para cada organização. Uma validação de marketplace (qualquer um dos endpoints) conta como uma leitura, e as validações são adicionalmente limitadas a 10 por minuto para cada organização considerando ambos os endpoints; ambos os limites são verificados antes de o corpo da solicitaçã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. Uma leitura que passa organization_id conta para o limite da organização em que a chave foi criada, ou da organização pai se a chave não tiver organização própria. Solicitaçõ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 que se aplica (na validação de marketplace, seu limite de 10 por minuto; em um 429, o limite que recusou a solicitaçã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, portanto continue solicitando páginas até que next_page seja null. Os iteradores de listagem dos SDKs de Python, TypeScript, C#, Go, Java e Ruby e a CLI (exceto com --format raw) fazem isso por você. Eles solicitam a próxima página enquanto next_page estiver definido, de modo que uma página curta ou vazia não os encerra. Em PHP e curl, 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 da Claude API. Informe o request_id do corpo da resposta ao entrar em contato com o suporte.

StatusSignificado
400Entrada inválida, ou a operação não se aplica a este plugin ou marketplace (consulte a seção de cada endpoint). Também é retornado para um parâmetro de consulta que o endpoint não reconhece e para uma organização que não é uma organização Claude Enterprise (this endpoint is not supported for this organization type).
401Cabeçalho x-api-key ausente, ou a chave não é reconhecida.
403A chave não tem o escopo necessário, ou a solicitação faz upload para o plugin ou marketplace pessoal de um membro, altera a versão servida dele ou define o padrão para ele. (Excluir o plugin de um membro é permitido.)
404Recurso não encontrado. Também é retornado quando a solicitação omite o valor anthropic-beta ou quando a API não está habilitada para sua organização, de modo que os endpoints aparecem como inexistentes.
409Um nome já está em uso, o content_scan de uma versão indica processing, ou um upload conflitante está em andamento.
413O corpo da solicitação excede o limite de tamanho: 200 MB para um upload, 32 MB para validação de marketplace.
429“Rate limit” (limite de taxa) excedido. Consulte Limitação de taxa.
500Erro interno.
503Temporário. Também é retornado quando várias gravações de configuração de instalação para um mesmo plugin chegam ao mesmo tempo; envie-as uma de cada vez. Tente novamente com “backoff” (espera progressiva), exceto no caso de registration_pending (consulte a tabela a seguir).

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"
}
error_codeStatusSignificado e o que fazer
plugin_name_taken409O marketplace já contém este nome. details.plugin_id é o plugin que o detém, e outra pessoa pode tê-lo criado. Para ver quem, obtenha o plugin e leia seu created_by, que é null quando nenhum criador está registrado. Faça upload de versões para ele somente se for o plugin que você pretendia atualizar. Caso contrário, ou quando plugin_id estiver ausente, faça o upload com outro nome.
skill_name_taken409O plugin está no marketplace da biblioteca e uma de suas skills tem o mesmo nome de uma skill da organização (uma skill que um administrador enviou para toda a organização no claude.ai). details.skill_name indica qual é. Renomeie ou remova uma delas.
registration_pending503Os arquivos foram armazenados, mas as skills do plugin ainda não puderam ser disponibilizadas aos membros. Consulte Repetindo uploads.
scan_pending409O content_scan da versão indica processing. Tente novamente quando a verificação terminar.
scan_failed400O content_scan da versão indica fail, unknown ou errored, então ela não pode ser servida. Escolha outra versão.
cmek_key_disabled, cmek_key_network_blocked400A chave de criptografia gerenciada pelo cliente da sua organização está indisponível. Consulte Chaves de criptografia gerenciadas pelo cliente.
unsupported_charset400Em um upload ou validate_archive, o cabeçalho Content-Type da solicitação nomeia um charset diferente de UTF-8, ISO-8859-1 ou US-ASCII. Envie a solicitação sem charset, ou com um destes.

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 de repetir. Uma exclusão repetida, ou uma remoção repetida de uma configuração de instalação, 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, envie a criação novamente. Um 409 plugin_name_taken significa que a primeira tentativa armazenou o plugin ou que o nome já estava em uso. Sua criação perdida gerou o plugin em details.plugin_id somente se o created_by dele for um api_actor com o api_key_id da sua chave. Verifique isso antes de fazer upload para ele (consulte plugin_name_taken na tabela anterior). 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 Activity Feed da Compliance API 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.

EventoEmitido quando
claude_plugin_createdUm plugin é criado por um upload (aqui ou no claude.ai) ou por uma solicitação de publicação aceita. Um plugin criado por uma sincronização do Git emite apenas claude_plugin_version_created.
claude_plugin_version_createdUma versão é armazenada. Versões armazenadas por uma sincronização do Git são atribuídas a um system_actor.
claude_plugin_updatedUma nova versão é enviada para um plugin existente.
claude_plugin_served_version_updatedA versão servida muda.
claude_plugin_deletedUm plugin é excluído individualmente, aqui ou no claude.ai.
plugin_installation_preference_updatedUma configuração de instalação é definida ou removida.
marketplace_createdO primeiro upload cria o marketplace da biblioteca.
marketplace_updatedA configuração de instalação padrão de um marketplace muda, ou um administrador ou proprietário inicia uma sincronização no claude.ai.
marketplace_deletedUm marketplace é excluído no claude.ai junto com seus plugins (sem eventos por plugin).
claude_plugin_archive_accessedO arquivo de um plugin pertencente a um membro é baixado.
claude_plugin_security_scan_completedUma verificação de conteúdo é concluída.

Os IDs de plugin, versão e marketplace nesses eventos são os mesmos IDs que esta API retorna. Um evento também pode nomear um marketplace que esta API não lista, como um marketplace de plugins que a Anthropic publica. plugin_installation_preference_updated identifica o plugin pelo seu name e marketplace_id em vez do seu id. Em claude_plugin_security_scan_completed, plugin_version não é um ID de versão, e nenhum campo de uma versão de plugin corresponde a ele.

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

Onde seu proprietário principal cria uma chave com escopo.

Os endpoints de grupo que fornecem os IDs rbac_group_ usados nas configurações de instalação.

Onde as gravações de plugins e os downloads de arquivos de membros são registrados.

Relatórios de uso de plugins e skills para o Claude Enterprise.

Esta página foi útil?