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:
| Recurso | Endpoints |
|---|---|
| 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 um | GET /v1/organizations/pluginsPOST /v1/organizations/pluginsGET /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ão | GET /v1/organizations/plugins/{plugin_id}/versionsPOST /v1/organizations/plugins/{plugin_id}/versionsGET /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ções | GET /v1/organizations/plugins/{plugin_id}/installation_settingsPOST /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á-lo | GET /v1/organizations/plugin_marketplacesGET /v1/organizations/plugin_marketplaces/{marketplace_id}POST /v1/organizations/plugin_marketplaces/{marketplace_id}POST /v1/organizations/plugin_marketplaces/validate_repositoryPOST /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
- Sua organização deve estar em um plano Claude Enterprise.
- Seu proprietário principal cria uma chave de API de Admin com o escopo
read:plugins, o escopowrite:pluginsou ambos em claude.ai > Configurações da organização > API. Consulte Criar uma chave para uma organização Claude Enterprise. - Toda requisição carrega três cabeçalhos:
x-api-key,anthropic-version: 2026-10-21eanthropic-beta: ce-plugins-2026-09-01.
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
| Escopo | Concede |
|---|---|
read:plugins | Todos os endpoints GET desta página, incluindo downloads de arquivos compactados, além da validação de marketplace. |
write:plugins | Todos 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_audit | Um 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_data | O 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:
| Componente | O que é |
|---|---|
| Skill | Instruções e arquivos que o Claude carrega quando uma tarefa os exige. |
| Comando | Um prompt salvo que um membro executa digitando / seguido do nome do comando. |
| Agente | Um assistente auxiliar com suas próprias instruções, ao qual o Claude pode delegar parte de uma tarefa. |
| Hook | Um comando que é executado automaticamente quando ocorre um evento em uma sessão, como antes de o Claude usar uma ferramenta. |
| Servidor MCP | Uma conexão do Claude com ferramentas e dados em outro sistema (“Model Context Protocol”, ou MCP). |
| CLI | Um 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.
manualsignifica 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,gitlabepublic_gitsignificam 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 formanual. Fazer upload de versões e escolher a versão servida retornam403. 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 novaserved_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):
| Valor | O que os membros veem |
|---|---|
required | O plugin está instalado e não pode ser removido. |
auto_install | O plugin está instalado e pode ser removido. |
available | O plugin pode ser instalado mediante solicitação. |
not_available | O 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:
- 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 emorganization_installation_preference, comorganization_installation_preference_inherited: trueenquanto ele vier do padrão do marketplace. - Um membro que não pertence a nenhum grupo com uma configuração para o plugin recebe o valor para toda a organização.
- 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:
| Valor | Significado |
|---|---|
remote | Declara um servidor MCP ou uma CLI, independentemente do que mais declare. |
privileged | Nã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. |
contained | Nã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
.zipou.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 umname. UmSKILL.mdisolado sem manifesto é rejeitado. - Um
SKILL.mdde nível superior cujo frontmatter declara componentes de plugin é mesclado ao manifesto;plugin.jsonprevalece sempre que ambos definem um valor. Umdescriptionque o manifesto obtém desseSKILL.mdé cortado para seus primeiros 500 caracteres. namepode 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.displayNametem no máximo 64 caracteres edescriptionno máximo 500.- Todo
SKILL.mdprecisa de um frontmatter YAML válido comnameedescription, 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
.zipaninhado. 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 de400. 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
400quando 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.
- Encontre o marketplace para o qual fazer upload com
GET /v1/organizations/plugin_marketplaces?owner_type=organization, ou omitamarketplace_idpara usar o marketplace da biblioteca. - No primeiro release, crie o plugin com
POST /v1/organizations/plugins. Em cada release posterior, registre olatest_version_iddo plugin e depois faça upload de uma versão comPOST /v1/organizations/plugins/{plugin_id}/versions. Se a resposta do upload se perder, leia o plugin e tente novamente apenas selatest_version_idnão tiver mudado (consulte Repetir uploads). - Para manter os membros na versão atual enquanto cada novo build é verificado, fixe o plugin uma vez definindo
served_version_idcomo 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. - Quando a verificação de conteúdo estiver ativada, consulte
GET /v1/organizations/plugins/{plugin_id}/versions/{version}periodicamente até quecontent_scan.statusnão seja maisprocessing, e promova apenas quando forcompletedcompassouwarn. - 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
-
Consulte o ID do grupo piloto com
GET /v1/organizations/rbac_groups. Essa chamada precisa do escoporead:rbac_groups(consulte Grupos e funções em Gerenciamento de usuários). Os próximos passos precisam dewrite: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. -
Dê ao grupo sua própria configuração, por exemplo
auto_install, comPOST /v1/organizations/plugins/{plugin_id}/installation_settings/{target}, em que{target}é o IDrbac_group_do grupo, enquanto o valor para toda a organização permanecenot_available. Apenas os membros do grupo recebem o plugin. -
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.
Pythonclient = 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 deavailablemanteria esses membros emavailable.
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.
- Percorra as páginas de
GET /v1/organizations/plugins?limit=100até quenext_pagesejanull(consulte Paginação). Leia oreache ocontent_scande cada plugin nessa lista em toda execução: uma alteração apenas emcontent_scan, como um veredito que chega depois, não alteraupdated_at.updated_atnormalmente 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) alteraupdated_atquando se torna a versão servida, não necessariamente quando é armazenada. Para notar uma, comparelatest_version_idcom 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. - Sinalize cada plugin cujo
reachsejaremote(ele declara um servidor MCP ou uma CLI), ou cujocontent_scan.assessmentsejawarn,failouunknown. Umwarntambém pode ser uma verificação com falha que foi permitida no claude.ai. Deixewarnde 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 quandolatest_version_idfor diferente deserved_version_id(consulte Listar as versões de um plugin). - 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. - 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.
| Campo | Descrição |
|---|---|
id | Com o prefixo plugin_. |
name | Vem 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_version | Os 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_id | Com 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_pinned | false 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_id | Com o prefixo marketplace_. |
created_by | Quem 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_inherited | De 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_scan | O 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. |
components | Os 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. |
reach | contained, privileged ou remote. Consulte Alcance. |
updated_at | Muda 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
descriptionque você lê pode ter mais de 500 caracteres, o limite para um manifesto enviado. Um envio cujoplugin.jsondefine taldescriptionretorna400. - Nos arquivos que você baixa,
.claude-plugin/plugin.jsonpode ter umdescriptiondiferente, ou nenhum.
O objeto content_scan:
| Campo | Descrição |
|---|---|
status | processing 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. |
assessment | Definido 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. |
reason | Para 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. |
reason | Significado |
|---|---|
covert-usage-telemetry | Instrui o Claude a enviar informações sobre o membro ou seu uso para um endereço externo sem avisá-lo. |
undisclosed-data-destination | Envia arquivos, e-mails, documentos ou outro conteúdo para um destino externo fixo que não é mostrado ao membro e que ele não controla. |
remote-code-instruction-loader | Instrui o Claude a baixar e executar, ou seguir instruções de, conteúdo externo que pode mudar depois que o plugin é instalado. |
credential-exposure | Contém credenciais ativas ou coleta credenciais ou tokens do ambiente do membro. |
guardrail-tampering | Enfraquece as proteções do membro, por exemplo, pré-aprovando todos os pedidos de permissão. |
system-prompt-spoofing | Imita ou tenta substituir as instruções de sistema de Claude. |
covert-record-tampering | Altera, oculta ou exclui discretamente informações que o membro veria de outra forma. |
covert-behavior-override | Altera o comportamento do Claude além do propósito do plugin e oculta a alteração do membro. |
hidden-code-execution | Executa código incluído no pacote enquanto instrui o Claude a não revelar o que ele faz. |
undisclosed-promotion-injection | Insere conteúdo promocional não divulgado na saída do Claude. |
hidden-identity-gate | Altera ou interrompe seu comportamento dependendo de qual conta o executa, sem dizer por quê. |
destructive-persistence | Pode excluir ou corromper os arquivos do membro, ou instalar programas que permanecem após o plugin. |
unanalyzable-binary | Inclui um programa compilado ou ilegível, de modo que a verificação não pôde confirmar o que ele faz. |
other | Qualquer outra preocupação, incluindo uma mais recente do que esta lista. |
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:
| Status | Causa | O que fazer |
|---|---|---|
| 404 | marketplace_id não é um marketplace da sua organização. | Obtenha o ID em Listar marketplaces. |
| 400 | O 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_taken | O 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_taken | O 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_pending | O 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:
| Status | Causa | O que fazer |
|---|---|---|
| 400 | O 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_..."}. |
| 404 | served_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_taken | O 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:
| Status | Causa | O que fazer |
|---|---|---|
| 400 | O 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_taken | O 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_pending | A 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"
}| Campo | Descrição |
|---|---|
name | O nome do marketplace. Fixo durante toda a sua existência. |
owner | Mesmo formato que no plugin. |
source | manual, github, gitlab ou public_git. Consulte Marketplaces. |
sync_status | Resultado 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_at | Quando 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_sha | O 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_preference | Marketplaces 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"
}
]
}
]
}| Campo | Descrição |
|---|---|
valid | true quando marketplace.json está bem formado e nenhum plugin seria ignorado. Avisos não o tornam false. |
ref | O 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_sha | O 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_count | Quantos plugins marketplace.json declara; 0 quando não pôde ser lido. |
manifest_error, manifest_error_code | Definido 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_errors | Um {name, error, error_code} por plugin que uma sincronização ignoraria. |
plugin_warnings | Um {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:
| Status | Causa | O que fazer |
|---|---|---|
| 400 | Em 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. |
| 413 | Em 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.
| Status | Significado |
|---|---|
| 400 | Entrada 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). |
| 401 | Cabeçalho x-api-key ausente, ou a chave não é reconhecida. |
| 403 | A 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.) |
| 404 | Recurso 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. |
| 409 | Um nome já está em uso, o content_scan de uma versão indica processing, ou um upload conflitante está em andamento. |
| 413 | O 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. |
| 500 | Erro interno. |
| 503 | Temporá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_code | Status | Significado e o que fazer |
|---|---|---|
plugin_name_taken | 409 | O 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_taken | 409 | O 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_pending | 503 | Os arquivos foram armazenados, mas as skills do plugin ainda não puderam ser disponibilizadas aos membros. Consulte Repetindo uploads. |
scan_pending | 409 | O content_scan da versão indica processing. Tente novamente quando a verificação terminar. |
scan_failed | 400 | O 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_blocked | 400 | A chave de criptografia gerenciada pelo cliente da sua organização está indisponível. Consulte Chaves de criptografia gerenciadas pelo cliente. |
unsupported_charset | 400 | Em 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 incluix-should-retry: false: não reenvie a criação (um reenvio retorna409 plugin_name_taken); em vez disso, faça o upload dos mesmos arquivos como uma versão dedetails.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 incluirx-should-retry: true, e não reenvie quando incluirfalse.
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.
| Evento | Emitido quando |
|---|---|
claude_plugin_created | Um 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_created | Uma versão é armazenada. Versões armazenadas por uma sincronização do Git são atribuídas a um system_actor. |
claude_plugin_updated | Uma nova versão é enviada para um plugin existente. |
claude_plugin_served_version_updated | A versão servida muda. |
claude_plugin_deleted | Um plugin é excluído individualmente, aqui ou no claude.ai. |
plugin_installation_preference_updated | Uma configuração de instalação é definida ou removida. |
marketplace_created | O primeiro upload cria o marketplace da biblioteca. |
marketplace_updated | A 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_deleted | Um marketplace é excluído no claude.ai junto com seus plugins (sem eventos por plugin). |
claude_plugin_archive_accessed | O arquivo de um plugin pertencente a um membro é baixado. |
claude_plugin_security_scan_completed | Uma 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_notesecomponentsretornados comonull. - Downloads de arquivos, criações, criações de versão e alterações da versão servida retornam
400comcmek_key_disabledoucmek_key_network_blocked. - Excluir um plugin no marketplace da biblioteca retorna
400 cmek_key_disablede 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?