---
title: API de Plugins
url: https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api
description: "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ê inventarie todos os plugins da sua organização Claude Enterprise, publique plugins e novas versões a partir dos seus próprios pipelines, escolha qual versão é servida aos membros, controle quem pode usar cada plugin, baixe arquivos de plugins para revisão e verifique um marketplace Git antes de conectá-lo.
Para relatórios de *uso* de plugins (quais plugins e skills os membros usam e com que frequência), consulte [APIs de Analytics](https://platform.claude.com/docs/pt-BR/manage-claude/analytics-api).
**Chave de API de Admin com escopo obrigatória**
Esses endpoints exigem uma chave de API de Admin com o escopo `read:plugins` (para endpoints `GET`, incluindo downloads de arquivos compactados) ou o escopo `write:plugins` (para endpoints `POST` e `DELETE`, exceto a validação de marketplace, que aceita qualquer um dos dois escopos); [Escopos](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#scopes) traz os detalhes, incluindo dois outros escopos de leitura que também funcionam. Consulte [Criar uma chave de API de Admin](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api-keys#create-a-key-for-a-claude-enterprise-organization) para saber onde o proprietário principal da sua organização cria uma. Passe a chave no cabeçalho `x-api-key` em todas as requisições, junto com o cabeçalho [`anthropic-version`](https://platform.claude.com/docs/pt-BR/api/versioning) e o cabeçalho beta mostrado na nota a seguir.
A API de Plugins está em **beta** e está disponível apenas para organizações Claude Enterprise. Ela não está disponível para organizações da Claude Platform (Claude Console) nem para organizações com a prontidão para HIPAA ativada.
Toda requisição deve incluir o [cabeçalho beta](https://platform.claude.com/docs/pt-BR/api/beta-headers) `anthropic-beta: ce-plugins-2026-09-01` (os SDKs e a CLI `ant` o enviam para você). Uma requisição sem ele retorna `404`, exatamente como se o endpoint não existisse.
## Endpoints
A API expõe 18 endpoints distribuídos em cinco recursos:
| Recurso | Endpoints |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Plugins**: listar todos 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/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ão | `GET /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ções | `GET /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á-lo | `GET /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` |
Esta versão não inclui skills avulsas (skills que um membro escreve no editor de skills ou envia como uma única skill no claude.ai). Elas não aparecem no inventário e não podem ser criadas aqui. Plugins publicados pela Anthropic também não são inventariados; o uso deles é informado pelas [APIs de Analytics](https://platform.claude.com/docs/pt-BR/manage-claude/analytics-api). Marketplaces são criados, conectados a repositórios e excluídos no claude.ai, não por meio desta API.
## Pré-requisitos
* Sua organização deve estar em um plano Claude Enterprise.
* O proprietário principal da sua organização cria uma chave de API de Admin com o escopo `read:plugins`, o escopo `write:plugins` ou ambos em [claude.ai > Configurações da organização > API](https://claude.ai/admin-settings/api-access). Consulte [Criar uma chave de API de Admin](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api-keys#create-a-key-for-a-claude-enterprise-organization).
* Toda requisição carrega três cabeçalhos: `x-api-key`, `anthropic-version: 2023-06-01` e `anthropic-beta: ce-plugins-2026-09-01`.
Os SDKs de Python, TypeScript, C#, Go, Java, PHP e Ruby expõem esses endpoints em `client.beta.organization` (csharp, go: `client.Beta.Organization`; java: `client.beta().organization()`; php: `$client->beta->organization`), e a [CLI `ant`](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/quickstart) em `ant beta:organization`; eles enviam os cabeçalhos `anthropic-version` e `anthropic-beta` por você. Os exemplos desta página usam o cliente padrão de cada SDK, que, assim como a CLI, lê a chave de API de Admin da variável de ambiente `ANTHROPIC_API_KEY`; os exemplos em curl leem a chave da mesma variável e a passam no cabeçalho `x-api-key`. Quando 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#pagination)).
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:
```bash cURL
curl "https://api.anthropic.com/v1/organizations/plugins?owner_type=organization&limit=20" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01"
```
```bash CLI
ant beta:organization:plugins list --owner-type organization --limit 20
```
```python Python
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}")
```
```typescript TypeScript
const client = new Anthropic();
const plugins = await client.beta.organization.plugins.list({
owner_type: "organization",
limit: 20
});
for await (const plugin of plugins) {
console.log(`${plugin.id}: ${plugin.name}`);
}
```
```csharp C#
using Anthropic.Models.Beta.Organization.Plugins;
AnthropicClient client = new();
var page = await client.Beta.Organization.Plugins.List(
new() { OwnerType = OwnerType.Organization, Limit = 20 }
);
await foreach (var plugin in page.Paginate())
{
Console.WriteLine($"{plugin.ID}: {plugin.Name}");
}
```
```go Go
client := anthropic.NewClient()
plugins := client.Beta.Organization.Plugins.ListAutoPaging(context.Background(), anthropic.BetaOrganizationPluginListParams{
OwnerType: anthropic.BetaOrganizationPluginListParamsOwnerTypeOrganization,
Limit: anthropic.Int(20),
})
for plugins.Next() {
plugin := plugins.Current()
fmt.Printf("%s: %s\n", plugin.ID, plugin.Name)
}
if err := plugins.Err(); err != nil {
log.Fatal(err)
}
```
```java Java
import com.anthropic.models.beta.organization.plugins.PluginListParams;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var params = PluginListParams.builder()
.ownerType(PluginListParams.OwnerType.ORGANIZATION)
.limit(20)
.build();
var plugins = client.beta().organization().plugins().list(params);
for (var plugin : plugins.autoPager()) {
IO.println(plugin.id() + ": " + plugin.name());
}
}
```
```php PHP
use Anthropic\Beta\Organization\Plugins\PluginListParams\OwnerType;
// ...
$client = new Client();
$plugins = $client->beta->organization->plugins->list(
limit: 20,
ownerType: OwnerType::ORGANIZATION,
);
// Apenas esta página; para a próxima, chame list() novamente com page: $plugins->nextPage.
foreach ($plugins->getItems() as $plugin) {
echo "{$plugin->id}: {$plugin->name}\n";
}
```
```ruby Ruby
client = Anthropic::Client.new
page = client.beta.organization.plugins.list(owner_type: :organization, limit: 20)
page.auto_paging_each do |plugin|
puts "#{plugin.id}: #{plugin.name}"
end
```
```json
{
"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](https://platform.claude.com/docs/pt-BR/manage-claude/user-management) e da [Compliance API](https://platform.claude.com/docs/pt-BR/manage-claude/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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#reading-another-organization-under-the-same-parent)). Cada um desses downloads registra um evento `claude_plugin_archive_accessed` no [Activity Feed da Compliance API](https://platform.claude.com/docs/pt-BR/manage-claude/compliance-activity-feed), identificando a chave, o plugin, a versão e o membro (consulte [Eventos do Activity Feed](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#activity-feed-events)). Downloads de plugins de propriedade da organização não são registrados.
### Ler outra organização sob a mesma organização-mãe
Chaves `read:plugins` e `write:plugins` leem e escrevem apenas na organização em que foram criadas. Se sua empresa tiver várias organizações Claude vinculadas a uma organização-mãe, uma chave `read:org_audit` ou `read:compliance_org_data` que o proprietário principal da organização-mãe criou para todas as organizações vinculadas (consulte [Criar uma chave de API de Admin](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api-keys#create-a-key-for-a-claude-enterprise-organization)) também pode ler qualquer uma delas que tenha acesso a esta API: passe o ID dessa organização no parâmetro de consulta `organization_id` em qualquer endpoint `GET` desta página. O ID é o UUID da organização mostrado nas configurações do claude.ai (sua forma com o prefixo `org_` também é aceita). Sem o parâmetro, a chave lê a organização em que foi criada. Um `404` significa que a organização indicada não está sob a organização-mãe da chave ou que a API não está disponível para ela; um valor que não seja um UUID nem um ID `org_` retorna `400`. Qualquer outra chave que indique uma organização diferente da sua recebe `404`. Escritas não aceitam `organization_id`.
## Conceitos principais
### Plugins e componentes
Um **plugin** é um pacote que estende o Claude para os membros da sua organização. Ele contém qualquer combinação destes componentes:
| Componente | O que é |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Skill | Instruções e arquivos que o Claude carrega quando uma tarefa os exige. |
| Command | Um prompt salvo que um membro executa digitando `/` seguido do nome do comando. |
| Agent | 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 um evento acontece em uma sessão, como antes de o Claude usar uma ferramenta. |
| MCP server | 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.** `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 recente.
* `served_version_id`: a "served version" (versão servida), ou seja, a versão servida aos membros.
Por padrão, `served_version_pinned` é `false`: a versão servida normalmente acompanha a mais recente. Quando a verificação de conteúdo está ativada, uma versão salva no claude.ai pode **aguardar** sua verificação 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 verificação estiver ativada, uma versão em espera só é servida depois que sua verificação for concluída com `pass` ou `warn`. Enquanto uma versão aguarda, `served_version_id` indica uma versão anterior a `latest_version_id`. Não faça polling até que os dois IDs coincidam: eles podem permanecer diferentes, por exemplo, quando a verificação 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 faça upload de cada build, teste-o e depois o promova. Para que seu pipeline decida quando cada build é servido, fixe o plugin uma vez definindo `served_version_id` como sua versão atual; a partir daí, promova cada build que você quiser servir. Com a verificação de conteúdo ativada, essa primeira fixação retorna `409 scan_pending` até que a verificação da versão atual seja concluída, e `400 scan_failed` se a verificação tiver sido concluída com `fail` ou `unknown`, ou tiver dado erro (`warn` é aceito). Atualmente, um plugin fixado não pode ser desafixado, nem aqui nem no claude.ai.
Para reverter, defina `served_version_id` como uma versão anterior. Avance da mesma forma.
Essas regras descrevem plugins de propriedade da organização. A versão servida de um plugin de propriedade de um membro é controlada pelo seu proprietário no claude.ai.
### Configurações de instalação
As **installation settings** (configurações de instalação) decidem quem pode usar um plugin de propriedade da organização. Cada configuração tem um de quatro valores, contidos nos campos chamados `installation_preference` (e, nos objetos de plugin e de marketplace, `organization_installation_preference` e `default_installation_preference`):
| 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 por grupo (os grupos de controle de acesso baseado em funções gerenciados em [Gerenciamento de usuários](https://platform.claude.com/docs/pt-BR/manage-claude/user-management#groups)). Um membro recebe um valor de acordo com estas regras:
1. O valor para toda a organização é a configuração do próprio plugin para toda a organização, se houver; caso contrário, o padrão do seu marketplace; caso contrário, `not_available`. O plugin informa esse valor em `organization_installation_preference`, com `organization_installation_preference_inherited: true` enquanto ele vier do padrão do marketplace.
2. Um membro que não pertence a nenhum grupo com uma configuração para o plugin recebe o valor para toda a organização.
3. Um membro que pertence a um ou mais grupos com uma configuração recebe, em vez disso, a mais permissiva das configurações desses grupos, na ordem `required`, `auto_install`, `available`, `not_available`.
A configuração de um grupo substitui o valor para toda a organização para seus membros; ela não se soma a ele. Por exemplo, se o valor para toda a organização for `required` e o grupo Pilot tiver `available`, os membros do Pilot recebem `available`. Ao mover um plugin de um grupo piloto para toda a organização, defina o valor para toda a organização e depois remova a configuração do grupo. Definir o valor para toda a organização faz com que o plugin deixe de herdar o padrão do seu marketplace; [remover a configuração para toda a organização](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#remove-an-installation-setting) 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 **shares** (compartilhamentos) decidem quem pode usar um plugin de propriedade de um membro. O proprietário o compartilha no claude.ai com todos os membros, com um grupo ou com membros específicos. Esta API lista os compartilhamentos, mas não pode alterá-los.
Se sua organização tiver desativado um tipo de compartilhamento nas configurações do claude.ai, os compartilhamentos desse tipo ainda aparecem na lista, mas não dão acesso a ninguém enquanto essa configuração estiver desativada; a própria lista não mostra se ela está.
### Verificação de conteúdo
A "content scanning" (verificação de conteúdo) é uma configuração da organização no claude.ai. Quando ela está ativada, as versões recém-armazenadas são verificadas (o claude.ai isenta algumas) e o resultado é informado em `content_scan`; uma versão que não foi verificada, por exemplo, uma armazenada antes de a verificação ser ativada, tem `content_scan: null`. A verificação não é oferecida a organizações que usam chaves de criptografia gerenciadas pelo cliente ou retenção zero de dados.
Enquanto a verificação estiver ativada, um plugin só é servido aos membros quando a verificação da sua versão servida está `completed` com `pass` ou `warn`. Enquanto a verificação está em andamento, ou depois que ela falha, dá erro ou não chega a um veredito, o plugin fica indisponível para os membros, e uma versão anterior não é servida no lugar dele. Uma versão que nunca foi verificada (`content_scan: null`) é servida normalmente.
Uma versão que você envia por meio desta API nunca aguarda sua verificação de conteúdo. Quando ela se torna a versão servida, os membros perdem o plugin até que sua verificação seja aprovada, e continuam sem ele se a verificação falhar. Se os membros devem manter a versão atual enquanto uma nova é verificada, fixe o plugin primeiro (consulte [Versões e a versão servida](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#versions-and-the-served-version)).
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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#list-a-plugins-versions)).
Após um upload, `content_scan.status` é `processing` e o veredito chega de forma assíncrona. Leia a versão para vê-lo; o objeto do plugin mostra apenas a verificação da sua versão servida. Alterar a versão servida para uma versão cuja verificação ainda está em andamento retorna `409 scan_pending`; para uma cuja verificação falhou, `400 scan_failed`.
### Alcance
O `reach` ("reach", alcance) resume, em um único valor, até onde uma versão chega nas máquinas dos membros e além delas:
| Valor | Significado |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `remote` | Declara um MCP server ou uma CLI, independentemente do que mais declare. |
| `privileged` | Não declara MCP server 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) ou configurações que o plugin aplica ao aplicativo do membro, ou contém uma skill, um command 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 MCP server, CLI, hook, monitor, servidor LSP nem configurações de aplicativo, e nenhum de seus arquivos Markdown pré-aprova ferramentas (por exemplo, um plugin que contém apenas skills, commands e agents, nenhum com `allowed-tools`). |
`reach` considera tudo o que a versão declara, incluindo monitores, servidores LSP 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 command, não pôde ser lido; trate `null` como não classificado.
### Requisitos de upload
Os uploads seguem as mesmas regras dos uploads de plugins no claude.ai, então os mesmos arquivos compactados são aceitos nos dois lugares.
* O upload é um único arquivo compactado `.zip` ou `.plugin`, ou um conjunto de arquivos individuais. Um arquivo compactado pode envolver tudo em uma única pasta de nível superior.
* Ele deve conter exatamente um manifesto, em `.claude-plugin/plugin.json`, que deve declarar um `name`. Um `SKILL.md` isolado sem manifesto é rejeitado.
* Um `SKILL.md` de nível superior cujo frontmatter declara componentes de plugin é mesclado ao manifesto; `plugin.json` prevalece sempre que ambos definem um valor.
* `name` pode conter letras minúsculas (de qualquer alfabeto), dígitos e hifens, com até 64 caracteres. Letras maiúsculas, espaços, sublinhados e outras pontuações são rejeitados.
* `displayName` tem no máximo 64 caracteres e `description` no máximo 500.
* Todo `SKILL.md` precisa de um frontmatter YAML válido com `name` e `description`, nenhum dos dois contendo tags XML como ``. Duas skills, ou dois commands, não podem compartilhar um nome.
* Nenhum arquivo pode estar em um diretório `bin/` de nível superior.
* Nenhum arquivo `.zip` aninhado. MCP servers empacotados (`.mcpb`, `.dxt`) são permitidos.
* Os caminhos de arquivo devem ser relativos, não conter `..` e usar apenas letras, dígitos, espaços e `_ . - / ( ) ,`.
* O corpo da requisição e o arquivo compactado descompactado têm, cada um, no máximo 200 MB; um corpo de requisição acima do limite retorna `413` (`request_too_large`) em vez de `400`. Um upload tem no máximo 5.000 arquivos, profundidade de caminho de 12, caminhos de 472 caracteres e nomes de arquivos ou pastas de 255 caracteres.
* Arquivos ZIP devem usar compressão DEFLATE ou STORE e não podem ser criptografados nem conter links simbólicos.
* Um marketplace comporta no máximo 500 itens, contando seus plugins e quaisquer skills avulsas que os membros mantenham nele. Esse limite e o limite de 5.000 arquivos são valores atuais que podem ser aumentados.
## Fluxos de trabalho de exemplo
### Publicar cada build a partir de um pipeline de release
Faça upload de cada build com tag a partir do CI e deixe o pipeline decidir quando um build é servido.
1. Encontre o marketplace para o qual fazer upload com `GET /v1/organizations/plugin_marketplaces?owner_type=organization`, ou omita `marketplace_id` para usar o library marketplace.
2. No primeiro release, [crie o plugin](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#create-a-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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#create-a-version) 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#retrying-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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#change-the-served-version) com `POST /v1/organizations/plugins/{plugin_id}` e `{"served_version_id": ""}`. Para reverter, envie o ID da versão anterior da mesma forma.
### Liberar um plugin para um grupo piloto e depois para todos
1. Consulte o ID do grupo piloto com `GET /v1/organizations/rbac_groups`. Essa chamada precisa do escopo `read:rbac_groups`, que exige uma chave criada para todas as organizações vinculadas (consulte [Gerenciamento de usuários](https://platform.claude.com/docs/pt-BR/manage-claude/user-management#groups)). As próximas etapas precisam de `write:plugins`, que atua apenas na organização em que sua chave foi criada; portanto, em uma empresa com várias organizações vinculadas, crie essa chave na organização que contém o plugin e dê a ela os dois escopos, ou use uma segunda chave criada lá para essas etapas.
2. [Dê ao grupo sua própria configuração](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#set-an-installation-setting), 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#remove-an-installation-setting) posteriormente retorna o plugin a esse padrão.
```bash cURL
curl -X POST "https://api.anthropic.com/v1/organizations/plugins/plugin_01Hq3vX8kZcN2mB7pR4tY9wL/installation_settings/organization" \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01" \
-d '{"installation_preference": "required"}'
```
```bash CLI
ant beta:organization:plugins:installation-settings set \
--plugin-id plugin_01Hq3vX8kZcN2mB7pR4tY9wL \
--target organization \
--installation-preference required
```
```python Python
client = anthropic.Anthropic()
setting = client.beta.organization.plugins.installation_settings.set(
"organization",
plugin_id="plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
installation_preference="required",
)
print(f"plugin_id: {setting.plugin_id}")
print(f"installation_preference: {setting.installation_preference}")
```
```typescript TypeScript
const client = new Anthropic();
const setting = await client.beta.organization.plugins.installationSettings.set(
"organization",
{
plugin_id: "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
installation_preference: "required"
}
);
console.log(`plugin_id: ${setting.plugin_id}`);
console.log(`installation_preference: ${setting.installation_preference}`);
```
```csharp C#
using Anthropic.Models.Beta.Organization.Plugins.InstallationSettings;
AnthropicClient client = new();
var setting = await client.Beta.Organization.Plugins.InstallationSettings.Set(
"organization",
new()
{
PluginID = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
InstallationPreference = InstallationPreference.Required,
}
);
Console.WriteLine($"plugin_id: {setting.PluginID}");
Console.WriteLine($"installation_preference: {setting.InstallationPreference.Raw()}");
```
```go Go
client := anthropic.NewClient()
setting, err := client.Beta.Organization.Plugins.InstallationSettings.Set(
context.Background(),
"organization",
anthropic.BetaOrganizationPluginInstallationSettingSetParams{
PluginID: "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
InstallationPreference: anthropic.BetaOrganizationPluginInstallationSettingSetParamsInstallationPreferenceRequired,
},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("plugin_id: %s\n", setting.PluginID)
fmt.Printf("installation_preference: %s\n", setting.InstallationPreference)
```
```java Java
import com.anthropic.models.beta.organization.plugins.installationsettings.InstallationSettingSetParams;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var params = InstallationSettingSetParams.builder()
.pluginId("plugin_01Hq3vX8kZcN2mB7pR4tY9wL")
.installationPreference(InstallationSettingSetParams.InstallationPreference.REQUIRED)
.build();
var setting = client.beta().organization().plugins().installationSettings()
.set("organization", params);
IO.println("plugin_id: " + setting.pluginId());
IO.println("installation_preference: " + setting.installationPreference().asString());
}
```
```php PHP
use Anthropic\Beta\Organization\Plugins\InstallationSettings\InstallationSettingSetParams\InstallationPreference;
// ...
$client = new Client();
$setting = $client->beta->organization->plugins->installationSettings->set(
target: 'organization',
pluginID: 'plugin_01Hq3vX8kZcN2mB7pR4tY9wL',
installationPreference: InstallationPreference::REQUIRED,
);
echo "plugin_id: {$setting->pluginID}\n";
echo "installation_preference: {$setting->installationPreference}\n";
```
```ruby Ruby
client = Anthropic::Client.new
plugin_id = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
setting = client.beta.organization.plugins.installation_settings.set(
"organization",
plugin_id: plugin_id,
installation_preference: :required
)
puts "plugin_id: #{setting.plugin_id}"
puts "installation_preference: #{setting.installation_preference}"
```
Em seguida, remova a configuração do grupo com `DELETE /v1/organizations/plugins/{plugin_id}/installation_settings/{target}`, em que `{target}` é o ID do grupo. A configuração de um grupo substitui o valor para toda a organização para seus membros em vez de se somar a ele, então uma configuração de grupo remanescente de `available` manteria esses membros em `available`.
### Manter um inventário de segurança sincronizado
Execute um job noturno que sinalize plugins que alcançam além da sessão do membro ou que falham na verificação de conteúdo.
1. Percorra as páginas de [`GET /v1/organizations/plugins?limit=100`](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#list-plugins) até que `next_page` seja `null` (consulte [Paginação](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#pagination)). Leia o `reach` e o `content_scan` de cada plugin a partir dessa lista em toda execução: um veredito de verificação que chega depois não altera `updated_at`. `updated_at` normalmente informa quais plugins têm conteúdo novo ou uma nova versão servida desde a última execução (o que justifica um novo download do arquivo compactado). Uma versão em espera (consulte [Versões e a versão servida](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#versions-and-the-served-version)) altera `updated_at` quando se torna a versão servida, não necessariamente quando é armazenada. Para percebê-la, 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 MCP server ou uma CLI), ou cujo `content_scan.assessment` seja `fail` ou `unknown`. Esses campos descrevem a versão servida. Para verificar também uma versão mais recente 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#list-a-plugins-versions)).
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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#download-a-versions-files)). 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#delete-a-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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#quick-start) 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. `manifest_version` é normalizado para exibição: um `v` ou `V` inicial é removido, então um `version` de manifesto `"v1.4.0"` é retornado como `"1.4.0"`. Ele 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 esse 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#versions-and-the-served-version). |
| `served_version_pinned` | `false` até que o plugin seja fixado (consulte [Versões e a versão servida](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#versions-and-the-served-version)); `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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#installation-settings)). 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 MCP server, `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 MCP servers, hooks e CLIs. `null` quando não registrado. |
| `reach` | `contained`, `privileged` ou `remote`. Consulte [Alcance](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#reach). |
| `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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#versions-and-the-served-version)) o altera quando se torna a versão servida, não necessariamente quando é armazenada. Ele não muda para configurações de instalação, compartilhamentos ou novos resultados de verificação. |
O objeto `content_scan`:
| Campo | Descrição |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | `processing` enquanto a verificação está em andamento, `completed` quando ela terminou, ou `errored` quando ela não pôde terminar (ou, ocasionalmente, quando seu resultado não pôde ser lido para esta resposta, caso em que uma leitura posterior pode informá-lo). Os membros não recebem uma versão cuja verificação esteja `processing` ou `errored`; enviar o conteúdo novamente como uma nova versão gera uma nova verificação. |
| `assessment` | Definido quando `status` é `completed`: `pass` (nada encontrado), `warn` (algo encontrado que não bloqueia o uso), `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 do 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 é resolvido, pertence a outra organização ou se refere a uma skill avulsa retorna `404`.
### Listar plugins
`GET /v1/organizations/plugins` lista todos os plugins da sua organização, nos marketplaces da organização e nos marketplaces pessoais dos membros, ordenados por `created_at` em ordem decrescente. Filtre por `owner_type` (`organization` ou `user`), `owner_user_id` (com o prefixo `user_`; os plugins de um membro, inclusive depois que o membro sai da organização), `marketplace_id` e `created_at[gte]`, `created_at[gt]`, `created_at[lte]`, `created_at[lt]` (timestamps RFC 3339). Os filtros são combinados com AND. Um `marketplace_id` ou `owner_user_id` que não corresponde a nada na sua organização retorna uma página vazia, não um erro. A resposta tem o formato mostrado em [Início rápido](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#quick-start). Requer o escopo `read:plugins`.
```bash cURL
curl "https://api.anthropic.com/v1/organizations/plugins?owner_type=organization&limit=20" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01"
```
```bash CLI
ant beta:organization:plugins list --owner-type organization --limit 20
```
```python Python
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}")
```
```typescript TypeScript
const client = new Anthropic();
const plugins = await client.beta.organization.plugins.list({
owner_type: "organization",
limit: 20
});
for await (const plugin of plugins) {
console.log(`${plugin.id}: ${plugin.name}`);
}
```
```csharp C#
using Anthropic.Models.Beta.Organization.Plugins;
AnthropicClient client = new();
var page = await client.Beta.Organization.Plugins.List(
new() { OwnerType = OwnerType.Organization, Limit = 20 }
);
await foreach (var plugin in page.Paginate())
{
Console.WriteLine($"{plugin.ID}: {plugin.Name}");
}
```
```go Go
client := anthropic.NewClient()
plugins := client.Beta.Organization.Plugins.ListAutoPaging(context.Background(), anthropic.BetaOrganizationPluginListParams{
OwnerType: anthropic.BetaOrganizationPluginListParamsOwnerTypeOrganization,
Limit: anthropic.Int(20),
})
for plugins.Next() {
plugin := plugins.Current()
fmt.Printf("%s: %s\n", plugin.ID, plugin.Name)
}
if err := plugins.Err(); err != nil {
log.Fatal(err)
}
```
```java Java
import com.anthropic.models.beta.organization.plugins.PluginListParams;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var params = PluginListParams.builder()
.ownerType(PluginListParams.OwnerType.ORGANIZATION)
.limit(20)
.build();
var plugins = client.beta().organization().plugins().list(params);
for (var plugin : plugins.autoPager()) {
IO.println(plugin.id() + ": " + plugin.name());
}
}
```
```php PHP
use Anthropic\Beta\Organization\Plugins\PluginListParams\OwnerType;
// ...
$client = new Client();
$plugins = $client->beta->organization->plugins->list(
limit: 20,
ownerType: OwnerType::ORGANIZATION,
);
// Apenas esta página; para a próxima, chame list() novamente com page: $plugins->nextPage.
foreach ($plugins->getItems() as $plugin) {
echo "{$plugin->id}: {$plugin->name}\n";
}
```
```ruby Ruby
client = Anthropic::Client.new
page = client.beta.organization.plugins.list(owner_type: :organization, limit: 20)
page.auto_paging_each do |plugin|
puts "#{plugin.id}: #{plugin.name}"
end
```
### Criar um plugin
`POST /v1/organizations/plugins` cria um plugin de propriedade da organização e sua primeira versão em uma única chamada; a versão se torna a "served version" (versão servida). O corpo é `multipart/form-data`: `files[]` é um único arquivo compactado `.zip` ou `.plugin`, ou uma parte por arquivo, em que o nome de arquivo de cada parte é o caminho do arquivo dentro do plugin (por exemplo `.claude-plugin/plugin.json`). Os campos opcionais são `marketplace_id` (um marketplace `manual` de propriedade da organização; o padrão é o marketplace da sua biblioteca, que é criado no primeiro uso) e `release_notes` (até 5.000 caracteres, exibidas no histórico de versões do claude.ai e retornadas na versão). Os campos `name`, `display_name`, `description` e `manifest_version` do plugin vêm do manifesto enviado, e o upload deve atender aos [requisitos de upload](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#upload-requirements). Quando a "content scanning" (verificação de conteúdo) está ativada, o `content_scan.status` da resposta é `processing` e o veredito chega de forma assíncrona. Retorna o plugin. Requer o "scope" (escopo) `write:plugins`.
Enviar um arquivo compactado:
```bash cURL
curl -X POST "https://api.anthropic.com/v1/organizations/plugins" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01" \
-F "files[]=@dist/sales-toolkit.zip" \
-F "release_notes=First release"
```
```bash CLI
ant beta:organization:plugins create \
--file dist/sales-toolkit.zip \
--release-notes "First release"
```
```python Python
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}")
```
```typescript TypeScript
import fs from "node:fs";
const client = new Anthropic();
const plugin = await client.beta.organization.plugins.create({
files: [fs.createReadStream("dist/sales-toolkit.zip")],
release_notes: "First release"
});
console.log(`id: ${plugin.id}`);
console.log(`served_version_id: ${plugin.served_version_id}`);
```
```csharp C#
AnthropicClient client = new();
var plugin = await client.Beta.Organization.Plugins.Create(
new()
{
Files = [File.OpenRead("dist/sales-toolkit.zip")],
ReleaseNotes = "First release",
}
);
Console.WriteLine($"id: {plugin.ID}");
Console.WriteLine($"served_version_id: {plugin.ServedVersionID}");
```
```go Go
client := anthropic.NewClient()
archive, err := os.Open("dist/sales-toolkit.zip")
if err != nil {
log.Fatal(err)
}
defer archive.Close()
plugin, err := client.Beta.Organization.Plugins.New(context.Background(), anthropic.BetaOrganizationPluginNewParams{
Files: []io.Reader{archive},
ReleaseNotes: anthropic.String("First release"),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("id: %s\n", plugin.ID)
fmt.Printf("served_version_id: %s\n", plugin.ServedVersionID)
```
```java Java
import com.anthropic.core.MultipartField;
import com.anthropic.models.beta.organization.plugins.PluginCreateParams;
void main() throws Exception {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Monte a parte `files[]` manualmente para que o arquivo compactado seja enviado com seu nome,
// o que é exigido pelo upload.
var archive = MultipartField.>builder()
.value(List.of(Files.newInputStream(Path.of("dist/sales-toolkit.zip"))))
.filename("sales-toolkit.zip")
.contentType("application/octet-stream")
.build();
var params = PluginCreateParams.builder()
.files(archive)
.releaseNotes("First release")
.build();
var plugin = client.beta().organization().plugins().create(params);
IO.println("id: " + plugin.id());
IO.println("served_version_id: " + plugin.servedVersionId());
}
```
```php PHP
use Anthropic\Core\FileParam;
$client = new Client();
$plugin = $client->beta->organization->plugins->create(
files: [
FileParam::fromResource(fopen('dist/sales-toolkit.zip', 'r')),
],
releaseNotes: 'First release',
);
echo "id: {$plugin->id}\n";
echo "served_version_id: {$plugin->servedVersionID}\n";
```
```ruby Ruby
client = Anthropic::Client.new
plugin = client.beta.organization.plugins.create(
files: [Pathname("dist/sales-toolkit.zip")],
release_notes: "First release"
)
puts "id: #{plugin.id}"
puts "served_version_id: #{plugin.served_version_id}"
```
```json
{
"type": "plugin",
"id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
"name": "sales-toolkit",
"display_name": "Sales Toolkit",
"description": "Account research and call prep for the sales team.",
"served_version_id": "pluginver_01Km7tL4pR9xF5sU2zV3jP6q",
"served_version_pinned": false,
"latest_version_id": "pluginver_01Km7tL4pR9xF5sU2zV3jP6q",
"manifest_version": "1.4.0",
"owner": { "type": "organization" },
"marketplace_id": "marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r",
"created_by": { "type": "api_actor", "api_key_id": "apikey_01Nq9vN6rT2zH7uW4bX5mR8s" },
"organization_installation_preference": "available",
"organization_installation_preference_inherited": true,
"content_scan": { "status": "processing", "assessment": null, "reason": null },
"components": [
{
"type": "skill",
"name": "account-research",
"description": "Researches a customer account before a call."
},
{ "type": "mcp_server", "name": "crm", "description": null }
],
"reach": "remote",
"created_at": "2026-09-01T17:04:11Z",
"updated_at": "2026-09-01T17:04:11Z"
}
```
Envie arquivos individuais para um marketplace nomeado. Anexe cada arquivo sob seu caminho dentro do plugin (o sufixo `;filename=` no exemplo cURL, os argumentos de nome de arquivo nos exemplos de SDK); um arquivo enviado apenas com seu nome base faz com que o manifesto não seja encontrado. Os SDKs TypeScript e Java e a CLI `ant` ainda não conseguem anexar arquivos sob um caminho, então esses exemplos enviam o plugin como um único arquivo compactado para o marketplace:
```bash cURL
curl -X POST "https://api.anthropic.com/v1/organizations/plugins" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01" \
-F "files[]=@.claude-plugin/plugin.json;filename=.claude-plugin/plugin.json" \
-F "files[]=@skills/account-research/SKILL.md;filename=skills/account-research/SKILL.md" \
-F "marketplace_id=marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r"
```
```bash CLI
# A CLI envia cada arquivo apenas com seu nome base,
# então envie o plugin como um único arquivo compactado.
ant beta:organization:plugins create \
--file dist/sales-toolkit.zip \
--marketplace-id marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r
```
```python Python
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}")
```
```typescript TypeScript
import fs from "node:fs";
const client = new Anthropic();
// O SDK TypeScript envia cada arquivo com seu nome base,
// então envie o plugin como um único arquivo compactado.
const plugin = await client.beta.organization.plugins.create({
files: [fs.createReadStream("dist/sales-toolkit.zip")],
marketplace_id: "marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r"
});
console.log(`id: ${plugin.id}`);
console.log(`served_version_id: ${plugin.served_version_id}`);
```
```csharp C#
using Anthropic.Core;
AnthropicClient client = new();
// FileName mantém o caminho de cada arquivo dentro do plugin; sem ele, um FileStream
// é enviado apenas com seu nome base.
var plugin = await client.Beta.Organization.Plugins.Create(
new()
{
Files =
[
new BinaryContent
{
Stream = File.OpenRead(".claude-plugin/plugin.json"),
FileName = ".claude-plugin/plugin.json",
},
new BinaryContent
{
Stream = File.OpenRead("skills/account-research/SKILL.md"),
FileName = "skills/account-research/SKILL.md",
},
],
MarketplaceID = "marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r",
}
);
Console.WriteLine($"id: {plugin.ID}");
Console.WriteLine($"served_version_id: {plugin.ServedVersionID}");
```
```go Go
client := anthropic.NewClient()
manifest, err := os.Open(".claude-plugin/plugin.json")
if err != nil {
log.Fatal(err)
}
defer manifest.Close()
skillMd, err := os.Open("skills/account-research/SKILL.md")
if err != nil {
log.Fatal(err)
}
defer skillMd.Close()
// anthropic.File mantém o caminho de cada arquivo dentro do plugin como o filename da parte;
// um *os.File puro seria enviado com seu nome base e o manifesto não seria encontrado.
plugin, err := client.Beta.Organization.Plugins.New(context.Background(), anthropic.BetaOrganizationPluginNewParams{
Files: []io.Reader{
anthropic.File(manifest, ".claude-plugin/plugin.json", "application/json"),
anthropic.File(skillMd, "skills/account-research/SKILL.md", "text/markdown"),
},
MarketplaceID: anthropic.String("marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r"),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("id: %s\n", plugin.ID)
fmt.Printf("served_version_id: %s\n", plugin.ServedVersionID)
```
```java Java
import com.anthropic.core.MultipartField;
import com.anthropic.models.beta.organization.plugins.PluginCreateParams;
void main() throws Exception {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Os setters de `files` em PluginCreateParams aceitam um só nome de arquivo para toda a
// lista; então envie o plugin como um único arquivo compactado: uma só parte montada à mão
// que leva o nome do arquivo compactado, exigido pelo upload.
var archive = MultipartField.>builder()
.value(List.of(Files.newInputStream(Path.of("dist/sales-toolkit.zip"))))
.filename("sales-toolkit.zip")
.contentType("application/octet-stream")
.build();
var params = PluginCreateParams.builder()
.files(archive)
.marketplaceId("marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r")
.build();
var plugin = client.beta().organization().plugins().create(params);
IO.println("id: " + plugin.id());
IO.println("served_version_id: " + plugin.servedVersionId());
}
```
```php PHP
use Anthropic\Core\FileParam;
$client = new Client();
$plugin = $client->beta->organization->plugins->create(
files: [
FileParam::fromResource(
fopen('.claude-plugin/plugin.json', 'r'),
filename: '.claude-plugin/plugin.json',
),
FileParam::fromResource(
fopen('skills/account-research/SKILL.md', 'r'),
filename: 'skills/account-research/SKILL.md',
),
],
marketplaceID: 'marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r',
);
echo "id: {$plugin->id}\n";
echo "served_version_id: {$plugin->servedVersionID}\n";
```
```ruby Ruby
client = Anthropic::Client.new
# Um FilePart com filename: mantém o caminho de cada arquivo dentro do plugin;
# um Pathname simples seria enviado apenas com seu nome base.
plugin = client.beta.organization.plugins.create(
files: [
Anthropic::FilePart.new(
Pathname(".claude-plugin/plugin.json"),
filename: ".claude-plugin/plugin.json"
),
Anthropic::FilePart.new(
Pathname("skills/account-research/SKILL.md"),
filename: "skills/account-research/SKILL.md"
)
],
marketplace_id: "marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r"
)
puts "id: #{plugin.id}"
puts "served_version_id: #{plugin.served_version_id}"
```
Além de um `400` para um upload que viola os [requisitos de upload](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#upload-requirements) (`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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#error-responses)), 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#list-marketplaces). |
| 400 | O marketplace é sincronizado a partir do Git, ou já contém 500 plugins e skills. | Faça o upload para um marketplace `manual` ou, em vez disso, altere o repositório. |
| 409 `plugin_name_taken` | O nome já está em uso nesse marketplace. | Continue com `details.plugin_id` (envie uma versão para ele) ou 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 ainda está em andamento. | Tente novamente em breve. |
| 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#retrying-uploads)). |
### Obter um plugin
`GET /v1/organizations/plugins/{plugin_id}` retorna um plugin. Requer o escopo `read:plugins`.
```bash cURL
curl "https://api.anthropic.com/v1/organizations/plugins/plugin_01Hq3vX8kZcN2mB7pR4tY9wL" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01"
```
```bash CLI
ant beta:organization:plugins retrieve \
--plugin-id plugin_01Hq3vX8kZcN2mB7pR4tY9wL
```
```python Python
client = anthropic.Anthropic()
plugin = client.beta.organization.plugins.retrieve("plugin_01Hq3vX8kZcN2mB7pR4tY9wL")
print(f"id: {plugin.id}")
print(f"name: {plugin.name}")
```
```typescript TypeScript
const client = new Anthropic();
const plugin = await client.beta.organization.plugins.retrieve(
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
);
console.log(`id: ${plugin.id}`);
console.log(`name: ${plugin.name}`);
```
```csharp C#
AnthropicClient client = new();
var plugin = await client.Beta.Organization.Plugins.Retrieve("plugin_01Hq3vX8kZcN2mB7pR4tY9wL");
Console.WriteLine($"id: {plugin.ID}");
Console.WriteLine($"name: {plugin.Name}");
```
```go Go
client := anthropic.NewClient()
plugin, err := client.Beta.Organization.Plugins.Get(
context.Background(),
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
anthropic.BetaOrganizationPluginGetParams{},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("id: %s\n", plugin.ID)
fmt.Printf("name: %s\n", plugin.Name)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var plugin = client.beta().organization().plugins()
.retrieve("plugin_01Hq3vX8kZcN2mB7pR4tY9wL");
IO.println("id: " + plugin.id());
IO.println("name: " + plugin.name());
```
```php PHP
$client = new Client();
$plugin = $client->beta->organization->plugins->retrieve(
pluginID: 'plugin_01Hq3vX8kZcN2mB7pR4tY9wL',
);
echo "id: {$plugin->id}\n";
echo "name: {$plugin->name}\n";
```
```ruby Ruby
client = Anthropic::Client.new
plugin_id = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
plugin = client.beta.organization.plugins.retrieve(plugin_id)
puts "id: #{plugin.id}"
puts "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 atualmente não pode ser desafixado, nem aqui nem no claude.ai (consulte [Versões e a versão servida](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#versions-and-the-served-version)). O único campo atualizável é `served_version_id`, e ele é obrigatório. A alteração chega aos membros antes de a resposta retornar e não cria uma versão. Quando a verificação de conteúdo está ativada, a versão deve ser uma que possa ser servida aos membros (consulte [Verificação de conteúdo](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#content-scanning)). Passar a versão já servida em um plugin fixado não altera nada; passá-la em um plugin não fixado o fixa nela, de modo que uploads posteriores deixam de ser servidos automaticamente. Fixar 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`.
```bash cURL
curl -X POST "https://api.anthropic.com/v1/organizations/plugins/plugin_01Hq3vX8kZcN2mB7pR4tY9wL" \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01" \
-d '{"served_version_id": "pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p"}'
```
```bash CLI
ant beta:organization:plugins update \
--plugin-id plugin_01Hq3vX8kZcN2mB7pR4tY9wL \
--served-version-id pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p
```
```python Python
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}")
```
```typescript TypeScript
const client = new Anthropic();
const plugin = await client.beta.organization.plugins.update(
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
{ served_version_id: "pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p" }
);
console.log(`id: ${plugin.id}`);
console.log(`served_version_id: ${plugin.served_version_id}`);
```
```csharp C#
AnthropicClient client = new();
var plugin = await client.Beta.Organization.Plugins.Update(
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
new() { ServedVersionID = "pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p" }
);
Console.WriteLine($"id: {plugin.ID}");
Console.WriteLine($"served_version_id: {plugin.ServedVersionID}");
```
```go Go
client := anthropic.NewClient()
plugin, err := client.Beta.Organization.Plugins.Update(
context.Background(),
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
anthropic.BetaOrganizationPluginUpdateParams{
ServedVersionID: "pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p",
},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("id: %s\n", plugin.ID)
fmt.Printf("served_version_id: %s\n", plugin.ServedVersionID)
```
```java Java
import com.anthropic.models.beta.organization.plugins.PluginUpdateParams;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var params = PluginUpdateParams.builder()
.servedVersionId("pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p")
.build();
var plugin = client.beta().organization().plugins()
.update("plugin_01Hq3vX8kZcN2mB7pR4tY9wL", params);
IO.println("id: " + plugin.id());
IO.println("served_version_id: " + plugin.servedVersionId());
}
```
```php PHP
$client = new Client();
$plugin = $client->beta->organization->plugins->update(
pluginID: 'plugin_01Hq3vX8kZcN2mB7pR4tY9wL',
servedVersionID: 'pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p',
);
echo "id: {$plugin->id}\n";
echo "served_version_id: {$plugin->servedVersionID}\n";
```
```ruby Ruby
client = Anthropic::Client.new
plugin_id = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
plugin = client.beta.organization.plugins.update(
plugin_id,
served_version_id: "pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p"
)
puts "id: #{plugin.id}"
puts "served_version_id: #{plugin.served_version_id}"
```
```json
{
"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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#error-responses)), 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#list-a-plugins-versions). |
| 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#remove-an-installation-setting) 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#set-an-installation-setting)). 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`.
```bash cURL
curl -X DELETE "https://api.anthropic.com/v1/organizations/plugins/plugin_01Hq3vX8kZcN2mB7pR4tY9wL" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01"
```
```bash CLI
ant beta:organization:plugins delete --plugin-id plugin_01Hq3vX8kZcN2mB7pR4tY9wL
```
```python Python
client = anthropic.Anthropic()
deleted_plugin = client.beta.organization.plugins.delete(
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
)
print(f"id: {deleted_plugin.id}")
```
```typescript TypeScript
const client = new Anthropic();
const deletedPlugin = await client.beta.organization.plugins.delete(
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
);
console.log(`id: ${deletedPlugin.id}`);
```
```csharp C#
AnthropicClient client = new();
var deletedPlugin = await client.Beta.Organization.Plugins.Delete(
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
);
Console.WriteLine($"id: {deletedPlugin.ID}");
```
```go Go
client := anthropic.NewClient()
deletedPlugin, err := client.Beta.Organization.Plugins.Delete(
context.Background(),
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
anthropic.BetaOrganizationPluginDeleteParams{},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("id: %s\n", deletedPlugin.ID)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var deletedPlugin = client.beta().organization().plugins()
.delete("plugin_01Hq3vX8kZcN2mB7pR4tY9wL");
IO.println("id: " + deletedPlugin.id());
```
```php PHP
$client = new Client();
$deletedPlugin = $client->beta->organization->plugins->delete(
pluginID: 'plugin_01Hq3vX8kZcN2mB7pR4tY9wL',
);
echo "id: {$deletedPlugin->id}\n";
```
```ruby Ruby
client = Anthropic::Client.new
plugin_id = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
deleted_plugin = client.beta.organization.plugins.delete(plugin_id)
puts "id: #{deleted_plugin.id}"
```
```json
{ "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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#create-a-version) mostra um objeto completo). Seus campos espelham os campos de versão servida do plugin (`display_name`, `description`, `manifest_version`, `content_scan`, `components`, `reach`) para esta versão, além de `release_notes` (conforme fornecidas com o upload; exibidas no histórico de versões do claude.ai) e `created_by` (quem a enviou).
Um `{version}` sem o prefixo `pluginver_` retorna `400` (exceto o literal `latest` onde indicado). Um que tenha o prefixo, mas não identifique uma versão desse plugin, retorna `404`.
### Listar as versões de um plugin
`GET /v1/organizations/plugins/{plugin_id}/versions` lista as versões de um plugin, ordenadas por `created_at` em ordem decrescente; o primeiro item é a versão identificada por `latest_version_id`. `limit` vai de 1 a 1.000. Requer o escopo `read:plugins`.
```bash cURL
curl "https://api.anthropic.com/v1/organizations/plugins/plugin_01Hq3vX8kZcN2mB7pR4tY9wL/versions?limit=50" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01"
```
```bash CLI
ant beta:organization:plugins:versions list \
--plugin-id plugin_01Hq3vX8kZcN2mB7pR4tY9wL \
--limit 50
```
```python Python
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}")
```
```typescript TypeScript
const client = new Anthropic();
const versions = await client.beta.organization.plugins.versions.list(
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
{ limit: 50 }
);
for await (const version of versions) {
console.log(`${version.id}: ${version.manifest_version}`);
}
```
```csharp C#
AnthropicClient client = new();
var page = await client.Beta.Organization.Plugins.Versions.List(
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
new() { Limit = 50 }
);
await foreach (var version in page.Paginate())
{
Console.WriteLine($"{version.ID}: {version.ManifestVersion}");
}
```
```go Go
client := anthropic.NewClient()
versions := client.Beta.Organization.Plugins.Versions.ListAutoPaging(
context.Background(),
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
anthropic.BetaOrganizationPluginVersionListParams{
Limit: anthropic.Int(50),
},
)
for versions.Next() {
version := versions.Current()
fmt.Printf("%s: %s\n", version.ID, version.ManifestVersion)
}
if err := versions.Err(); err != nil {
log.Fatal(err)
}
```
```java Java
import com.anthropic.models.beta.organization.plugins.versions.VersionListParams;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var params = VersionListParams.builder()
.limit(50)
.build();
var versions = client.beta().organization().plugins().versions()
.list("plugin_01Hq3vX8kZcN2mB7pR4tY9wL", params);
for (var version : versions.autoPager()) {
IO.println(version.id() + ": " + version.manifestVersion().orElse(null));
}
}
```
```php PHP
$client = new Client();
$versions = $client->beta->organization->plugins->versions->list(
pluginID: 'plugin_01Hq3vX8kZcN2mB7pR4tY9wL',
limit: 50,
);
// Apenas esta página; para a próxima, chame list() novamente com page: $versions->nextPage.
foreach ($versions->getItems() as $version) {
echo "{$version->id}: {$version->manifestVersion}\n";
}
```
```ruby Ruby
client = Anthropic::Client.new
plugin_id = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
page = client.beta.organization.plugins.versions.list(plugin_id, limit: 50)
page.auto_paging_each do |version|
puts "#{version.id}: #{version.manifest_version}"
end
```
### 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#upload-requirements) e erros de arquivo, manifesto, arquivo compactado e tamanho que [Criar um plugin](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#create-a-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`.
```bash cURL
curl -X POST "https://api.anthropic.com/v1/organizations/plugins/plugin_01Hq3vX8kZcN2mB7pR4tY9wL/versions" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01" \
-F "files[]=@dist/sales-toolkit.zip" \
-F "release_notes=Adds the call-prep command."
```
```bash CLI
ant beta:organization:plugins:versions create \
--plugin-id plugin_01Hq3vX8kZcN2mB7pR4tY9wL \
--file dist/sales-toolkit.zip \
--release-notes "Adds the call-prep command."
```
```python Python
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}")
```
```typescript TypeScript
import fs from "node:fs";
const client = new Anthropic();
const version = await client.beta.organization.plugins.versions.create(
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
{
files: [fs.createReadStream("dist/sales-toolkit.zip")],
release_notes: "Adds the call-prep command."
}
);
console.log(`id: ${version.id}`);
console.log(`manifest_version: ${version.manifest_version}`);
```
```csharp C#
AnthropicClient client = new();
var version = await client.Beta.Organization.Plugins.Versions.Create(
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
new()
{
Files = [File.OpenRead("dist/sales-toolkit.zip")],
ReleaseNotes = "Adds the call-prep command.",
}
);
Console.WriteLine($"id: {version.ID}");
Console.WriteLine($"manifest_version: {version.ManifestVersion}");
```
```go Go
client := anthropic.NewClient()
archive, err := os.Open("dist/sales-toolkit.zip")
if err != nil {
log.Fatal(err)
}
defer archive.Close()
version, err := client.Beta.Organization.Plugins.Versions.New(
context.Background(),
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
anthropic.BetaOrganizationPluginVersionNewParams{
Files: []io.Reader{archive},
ReleaseNotes: anthropic.String("Adds the call-prep command."),
},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("id: %s\n", version.ID)
fmt.Printf("manifest_version: %s\n", version.ManifestVersion)
```
```java Java
import com.anthropic.core.MultipartField;
import com.anthropic.models.beta.organization.plugins.versions.VersionCreateParams;
void main() throws Exception {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Monte a parte `files[]` manualmente para que o arquivo compactado seja enviado com seu nome,
// o que é exigido pelo upload.
var archive = MultipartField.>builder()
.value(List.of(Files.newInputStream(Path.of("dist/sales-toolkit.zip"))))
.filename("sales-toolkit.zip")
.contentType("application/octet-stream")
.build();
var params = VersionCreateParams.builder()
.files(archive)
.releaseNotes("Adds the call-prep command.")
.build();
var version = client.beta().organization().plugins().versions()
.create("plugin_01Hq3vX8kZcN2mB7pR4tY9wL", params);
IO.println("id: " + version.id());
IO.println("manifest_version: " + version.manifestVersion().orElse(null));
}
```
```php PHP
use Anthropic\Core\FileParam;
$client = new Client();
$version = $client->beta->organization->plugins->versions->create(
pluginID: 'plugin_01Hq3vX8kZcN2mB7pR4tY9wL',
files: [
FileParam::fromResource(fopen('dist/sales-toolkit.zip', 'r')),
],
releaseNotes: 'Adds the call-prep command.',
);
echo "id: {$version->id}\n";
echo "manifest_version: {$version->manifestVersion}\n";
```
```ruby Ruby
client = Anthropic::Client.new
plugin_id = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
version = client.beta.organization.plugins.versions.create(
plugin_id,
files: [Pathname("dist/sales-toolkit.zip")],
release_notes: "Adds the call-prep command."
)
puts "id: #{version.id}"
puts "manifest_version: #{version.manifest_version}"
```
```json
{
"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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#upload-requirements) (`413` para um corpo de requisição acima de 200 MB) e das respostas compartilhadas (um `403` para um plugin de propriedade de um membro; consulte [Respostas de erro](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#error-responses)), 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#retrying-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`.
```bash cURL
curl "https://api.anthropic.com/v1/organizations/plugins/plugin_01Hq3vX8kZcN2mB7pR4tY9wL/versions/latest" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01"
```
```bash CLI
ant beta:organization:plugins:versions retrieve \
--plugin-id plugin_01Hq3vX8kZcN2mB7pR4tY9wL \
--version latest
```
```python Python
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}")
```
```typescript TypeScript
const client = new Anthropic();
const version = await client.beta.organization.plugins.versions.retrieve("latest", {
plugin_id: "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
});
console.log(`id: ${version.id}`);
console.log(`manifest_version: ${version.manifest_version}`);
```
```csharp C#
AnthropicClient client = new();
var version = await client.Beta.Organization.Plugins.Versions.Retrieve(
"latest",
new() { PluginID = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL" }
);
Console.WriteLine($"id: {version.ID}");
Console.WriteLine($"manifest_version: {version.ManifestVersion}");
```
```go Go
client := anthropic.NewClient()
version, err := client.Beta.Organization.Plugins.Versions.Get(
context.Background(),
"latest",
anthropic.BetaOrganizationPluginVersionGetParams{
PluginID: "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("id: %s\n", version.ID)
fmt.Printf("manifest_version: %s\n", version.ManifestVersion)
```
```java Java
import com.anthropic.models.beta.organization.plugins.versions.VersionRetrieveParams;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var params = VersionRetrieveParams.builder()
.pluginId("plugin_01Hq3vX8kZcN2mB7pR4tY9wL")
.build();
var version = client.beta().organization().plugins().versions()
.retrieve("latest", params);
IO.println("id: " + version.id());
IO.println("manifest_version: " + version.manifestVersion().orElse(null));
}
```
```php PHP
$client = new Client();
$version = $client->beta->organization->plugins->versions->retrieve(
version: 'latest',
pluginID: 'plugin_01Hq3vX8kZcN2mB7pR4tY9wL',
);
echo "id: {$version->id}\n";
echo "manifest_version: {$version->manifestVersion}\n";
```
```ruby Ruby
client = Anthropic::Client.new
plugin_id = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
version = client.beta.organization.plugins.versions.retrieve("latest", plugin_id: plugin_id)
puts "id: #{version.id}"
puts "manifest_version: #{version.manifest_version}"
```
### Baixar os arquivos de uma versão
`GET /v1/organizations/plugins/{plugin_id}/versions/{version}/content` baixa os arquivos de uma versão como o arquivo compactado `.zip` armazenado (`Content-Type: application/zip`). O arquivo compactado é retornado independentemente do resultado da verificação de conteúdo, para que você possa inspecionar versões retidas dos membros. Ele é servido exatamente como foi armazenado, então, para um plugin de propriedade da organização em um marketplace `manual`, você pode reenviá-lo sem alterações como uma nova versão, desde que ele atenda aos requisitos de upload atuais. `{version}` deve ser um ID de versão, não `latest`: leia primeiro o `served_version_id` ou o `latest_version_id` do plugin, ou resolva `latest` com `GET /v1/organizations/plugins/{plugin_id}/versions/latest`. O nome de arquivo em `Content-Disposition` é derivado do nome do plugin e não é único; nomeie os arquivos salvos pelo ID do plugin e da versão. Requer o escopo `read:plugins`.
Baixar o arquivo compactado de um plugin **de propriedade de um membro** registra um evento `claude_plugin_archive_accessed` no Activity Feed da Compliance API, identificando a chave (como `api_actor`), o plugin e seu marketplace, a versão e o membro proprietário por ID; ele não contém nomes. Baixar o arquivo compactado de um plugin de propriedade da organização não registra nada.
```bash cURL
curl "https://api.anthropic.com/v1/organizations/plugins/plugin_01Hq3vX8kZcN2mB7pR4tY9wL/versions/pluginver_01Km7tL4pR9xF5sU2zV3jP6q/content" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01" \
-o plugin_01Hq3vX8kZcN2mB7pR4tY9wL_pluginver_01Km7tL4pR9xF5sU2zV3jP6q.zip
```
```bash CLI
ant beta:organization:plugins:versions download \
--plugin-id plugin_01Hq3vX8kZcN2mB7pR4tY9wL \
--version pluginver_01Km7tL4pR9xF5sU2zV3jP6q \
--output plugin_01Hq3vX8kZcN2mB7pR4tY9wL_pluginver_01Km7tL4pR9xF5sU2zV3jP6q.zip
```
```python Python
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")
```
```typescript TypeScript
import { writeFile } from "node:fs/promises";
const client = new Anthropic();
const pluginId = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL";
const versionId = "pluginver_01Km7tL4pR9xF5sU2zV3jP6q";
const response = await client.beta.organization.plugins.versions.download(versionId, {
plugin_id: pluginId
});
if (!response.body) {
throw new Error("The download returned no body");
}
await writeFile(`${pluginId}_${versionId}.zip`, response.body);
```
```csharp C#
AnthropicClient client = new();
using var response = await client.Beta.Organization.Plugins.Versions.Download(
"pluginver_01Km7tL4pR9xF5sU2zV3jP6q",
new() { PluginID = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL" }
);
using var content = await response.ReadAsStream();
using var file = File.Create(
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL_pluginver_01Km7tL4pR9xF5sU2zV3jP6q.zip"
);
await content.CopyToAsync(file);
```
```go Go
client := anthropic.NewClient()
response, err := client.Beta.Organization.Plugins.Versions.Download(
context.Background(),
"pluginver_01Km7tL4pR9xF5sU2zV3jP6q",
anthropic.BetaOrganizationPluginVersionDownloadParams{
PluginID: "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
},
)
if err != nil {
log.Fatal(err)
}
defer response.Body.Close()
out, err := os.Create("plugin_01Hq3vX8kZcN2mB7pR4tY9wL_pluginver_01Km7tL4pR9xF5sU2zV3jP6q.zip")
if err != nil {
log.Fatal(err)
}
defer out.Close()
if _, err := io.Copy(out, response.Body); err != nil {
log.Fatal(err)
}
```
```java Java
import com.anthropic.core.http.HttpResponse;
import com.anthropic.models.beta.organization.plugins.versions.VersionDownloadParams;
void main() throws Exception {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var params = VersionDownloadParams.builder()
.pluginId("plugin_01Hq3vX8kZcN2mB7pR4tY9wL")
.build();
try (HttpResponse response = client.beta().organization().plugins().versions()
.download("pluginver_01Km7tL4pR9xF5sU2zV3jP6q", params)) {
Files.copy(
response.body(),
Path.of("plugin_01Hq3vX8kZcN2mB7pR4tY9wL_pluginver_01Km7tL4pR9xF5sU2zV3jP6q.zip"),
StandardCopyOption.REPLACE_EXISTING);
}
}
```
```php PHP
$client = new Client();
// download() retornaria o arquivo compactado inteiro como uma única string, então pegue a
// resposta bruta e copie o corpo dela para o disco em partes.
$response = $client->beta->organization->plugins->versions->raw->download(
version: 'pluginver_01Km7tL4pR9xF5sU2zV3jP6q',
params: ['pluginID' => 'plugin_01Hq3vX8kZcN2mB7pR4tY9wL'],
);
$archive = $response->getBody();
$file = fopen('plugin_01Hq3vX8kZcN2mB7pR4tY9wL_pluginver_01Km7tL4pR9xF5sU2zV3jP6q.zip', 'wb');
while (!$archive->eof()) {
fwrite($file, $archive->read(1024 * 1024));
}
fclose($file);
```
```ruby Ruby
client = Anthropic::Client.new
plugin_id = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
version_id = "pluginver_01Km7tL4pR9xF5sU2zV3jP6q"
archive = client.beta.organization.plugins.versions.download(version_id, plugin_id: plugin_id)
# O SDK retorna o arquivo já lido na memória, como um StringIO.
File.binwrite("#{plugin_id}_#{version_id}.zip", archive.string)
```
## Configurações de instalação de plugin
Estes endpoints se aplicam a plugins de propriedade da organização. Eles retornam `404` para um plugin de propriedade de um membro, que tem [compartilhamentos](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#plugin-shares) em vez disso. `{target}` é o literal `organization` para a configuração do plugin para toda a organização, ou o ID `rbac_group_` de um grupo para a configuração desse grupo; qualquer outro valor retorna `400`. Os IDs de grupo vêm de `GET /v1/organizations/rbac_groups` (escopo `read:rbac_groups`; consulte [Gerenciamento de usuários](https://platform.claude.com/docs/pt-BR/manage-claude/user-management#groups)). Uma configuração não tem um `id` próprio: ela é endereçada por `(plugin_id, target)`, e nenhum ator é registrado nela (o ator está em seu evento de atividade `plugin_installation_preference_updated`).
### Listar as configurações de instalação de um plugin
`GET /v1/organizations/plugins/{plugin_id}/installation_settings` lista as configurações que um plugin de propriedade da organização possui, ordenadas por `created_at` em ordem decrescente: sua própria configuração para toda a organização (ausente enquanto ele herda o padrão de seu marketplace) e a configuração de cada grupo. Filtre por `target_type` (`organization` ou `rbac_group`). Requer o escopo `read:plugins`.
```bash cURL
curl "https://api.anthropic.com/v1/organizations/plugins/plugin_01Hq3vX8kZcN2mB7pR4tY9wL/installation_settings" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01"
```
```bash CLI
ant beta:organization:plugins:installation-settings list \
--plugin-id plugin_01Hq3vX8kZcN2mB7pR4tY9wL
```
```python Python
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}")
```
```typescript TypeScript
const client = new Anthropic();
const settings = await client.beta.organization.plugins.installationSettings.list(
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
);
for await (const setting of settings) {
console.log(`${setting.plugin_id}: ${setting.installation_preference}`);
}
```
```csharp C#
AnthropicClient client = new();
var page = await client.Beta.Organization.Plugins.InstallationSettings.List(
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
);
await foreach (var setting in page.Paginate())
{
Console.WriteLine($"{setting.PluginID}: {setting.InstallationPreference.Raw()}");
}
```
```go Go
client := anthropic.NewClient()
settings := client.Beta.Organization.Plugins.InstallationSettings.ListAutoPaging(
context.Background(),
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
anthropic.BetaOrganizationPluginInstallationSettingListParams{},
)
for settings.Next() {
setting := settings.Current()
fmt.Printf("%s: %s\n", setting.PluginID, setting.InstallationPreference)
}
if err := settings.Err(); err != nil {
log.Fatal(err)
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var settings = client.beta().organization().plugins().installationSettings()
.list("plugin_01Hq3vX8kZcN2mB7pR4tY9wL");
for (var setting : settings.autoPager()) {
IO.println(setting.pluginId() + ": " + setting.installationPreference().asString());
}
```
```php PHP
$client = new Client();
$settings = $client->beta->organization->plugins->installationSettings->list(
pluginID: 'plugin_01Hq3vX8kZcN2mB7pR4tY9wL',
);
// Apenas esta página; para a próxima, chame list() novamente com page: $settings->nextPage.
foreach ($settings->getItems() as $setting) {
echo "{$setting->pluginID}: {$setting->installationPreference}\n";
}
```
```ruby Ruby
client = Anthropic::Client.new
plugin_id = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
page = client.beta.organization.plugins.installation_settings.list(plugin_id)
page.auto_paging_each do |setting|
puts "#{setting.plugin_id}: #{setting.installation_preference}"
end
```
### 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#remove-an-installation-setting); 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.
```bash cURL
curl -X POST "https://api.anthropic.com/v1/organizations/plugins/plugin_01Hq3vX8kZcN2mB7pR4tY9wL/installation_settings/rbac_group_01F3xQqQzXyWvUtSrQpOnMlK" \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01" \
-d '{"installation_preference": "available"}'
```
```bash CLI
ant beta:organization:plugins:installation-settings set \
--plugin-id plugin_01Hq3vX8kZcN2mB7pR4tY9wL \
--target rbac_group_01F3xQqQzXyWvUtSrQpOnMlK \
--installation-preference available
```
```python Python
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}")
```
```typescript TypeScript
const client = new Anthropic();
const setting = await client.beta.organization.plugins.installationSettings.set(
"rbac_group_01F3xQqQzXyWvUtSrQpOnMlK",
{
plugin_id: "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
installation_preference: "available"
}
);
console.log(`plugin_id: ${setting.plugin_id}`);
console.log(`installation_preference: ${setting.installation_preference}`);
```
```csharp C#
using Anthropic.Models.Beta.Organization.Plugins.InstallationSettings;
AnthropicClient client = new();
var setting = await client.Beta.Organization.Plugins.InstallationSettings.Set(
"rbac_group_01F3xQqQzXyWvUtSrQpOnMlK",
new()
{
PluginID = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
InstallationPreference = InstallationPreference.Available,
}
);
Console.WriteLine($"plugin_id: {setting.PluginID}");
Console.WriteLine($"installation_preference: {setting.InstallationPreference.Raw()}");
```
```go Go
client := anthropic.NewClient()
setting, err := client.Beta.Organization.Plugins.InstallationSettings.Set(
context.Background(),
"rbac_group_01F3xQqQzXyWvUtSrQpOnMlK",
anthropic.BetaOrganizationPluginInstallationSettingSetParams{
PluginID: "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
InstallationPreference: anthropic.BetaOrganizationPluginInstallationSettingSetParamsInstallationPreferenceAvailable,
},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("plugin_id: %s\n", setting.PluginID)
fmt.Printf("installation_preference: %s\n", setting.InstallationPreference)
```
```java Java
import com.anthropic.models.beta.organization.plugins.installationsettings.InstallationSettingSetParams;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var params = InstallationSettingSetParams.builder()
.pluginId("plugin_01Hq3vX8kZcN2mB7pR4tY9wL")
.installationPreference(InstallationSettingSetParams.InstallationPreference.AVAILABLE)
.build();
var setting = client.beta().organization().plugins().installationSettings()
.set("rbac_group_01F3xQqQzXyWvUtSrQpOnMlK", params);
IO.println("plugin_id: " + setting.pluginId());
IO.println("installation_preference: " + setting.installationPreference().asString());
}
```
```php PHP
use Anthropic\Beta\Organization\Plugins\InstallationSettings\InstallationSettingSetParams\InstallationPreference;
// ...
$client = new Client();
$setting = $client->beta->organization->plugins->installationSettings->set(
target: 'rbac_group_01F3xQqQzXyWvUtSrQpOnMlK',
pluginID: 'plugin_01Hq3vX8kZcN2mB7pR4tY9wL',
installationPreference: InstallationPreference::AVAILABLE,
);
echo "plugin_id: {$setting->pluginID}\n";
echo "installation_preference: {$setting->installationPreference}\n";
```
```ruby Ruby
client = Anthropic::Client.new
plugin_id = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
group_id = "rbac_group_01F3xQqQzXyWvUtSrQpOnMlK"
setting = client.beta.organization.plugins.installation_settings.set(
group_id,
plugin_id: plugin_id,
installation_preference: :available
)
puts "plugin_id: #{setting.plugin_id}"
puts "installation_preference: #{setting.installation_preference}"
```
```json
{
"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`.
```bash cURL
curl -X DELETE "https://api.anthropic.com/v1/organizations/plugins/plugin_01Hq3vX8kZcN2mB7pR4tY9wL/installation_settings/rbac_group_01F3xQqQzXyWvUtSrQpOnMlK" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01"
```
```bash CLI
ant beta:organization:plugins:installation-settings remove \
--plugin-id plugin_01Hq3vX8kZcN2mB7pR4tY9wL \
--target rbac_group_01F3xQqQzXyWvUtSrQpOnMlK
```
```python Python
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}")
```
```typescript TypeScript
const client = new Anthropic();
const removedSetting = await client.beta.organization.plugins.installationSettings.remove(
"rbac_group_01F3xQqQzXyWvUtSrQpOnMlK",
{ plugin_id: "plugin_01Hq3vX8kZcN2mB7pR4tY9wL" }
);
console.log(`plugin_id: ${removedSetting.plugin_id}`);
```
```csharp C#
AnthropicClient client = new();
var removedSetting = await client.Beta.Organization.Plugins.InstallationSettings.Remove(
"rbac_group_01F3xQqQzXyWvUtSrQpOnMlK",
new() { PluginID = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL" }
);
Console.WriteLine($"plugin_id: {removedSetting.PluginID}");
```
```go Go
client := anthropic.NewClient()
removedSetting, err := client.Beta.Organization.Plugins.InstallationSettings.Remove(
context.Background(),
"rbac_group_01F3xQqQzXyWvUtSrQpOnMlK",
anthropic.BetaOrganizationPluginInstallationSettingRemoveParams{
PluginID: "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("plugin_id: %s\n", removedSetting.PluginID)
```
```java Java
import com.anthropic.models.beta.organization.plugins.installationsettings.InstallationSettingRemoveParams;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var params = InstallationSettingRemoveParams.builder()
.pluginId("plugin_01Hq3vX8kZcN2mB7pR4tY9wL")
.build();
var removedSetting = client.beta().organization().plugins().installationSettings()
.remove("rbac_group_01F3xQqQzXyWvUtSrQpOnMlK", params);
IO.println("plugin_id: " + removedSetting.pluginId());
}
```
```php PHP
$client = new Client();
$removedSetting = $client->beta->organization->plugins->installationSettings->remove(
target: 'rbac_group_01F3xQqQzXyWvUtSrQpOnMlK',
pluginID: 'plugin_01Hq3vX8kZcN2mB7pR4tY9wL',
);
echo "plugin_id: {$removedSetting->pluginID}\n";
```
```ruby Ruby
client = Anthropic::Client.new
plugin_id = "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
group_id = "rbac_group_01F3xQqQzXyWvUtSrQpOnMlK"
removed_setting = client.beta.organization.plugins.installation_settings.remove(
group_id,
plugin_id: plugin_id
)
puts "plugin_id: #{removed_setting.plugin_id}"
```
```json
{
"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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#shares)).
### 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#shares)). `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`.
```bash cURL
curl "https://api.anthropic.com/v1/organizations/plugins/plugin_01Mr2wP7sU3aJ8vX5cY6nS9t/shares" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01"
```
```bash CLI
ant beta:organization:plugins:shares list \
--plugin-id plugin_01Mr2wP7sU3aJ8vX5cY6nS9t
```
```python Python
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}")
```
```typescript TypeScript
const client = new Anthropic();
const shares = await client.beta.organization.plugins.shares.list(
"plugin_01Mr2wP7sU3aJ8vX5cY6nS9t"
);
for await (const share of shares) {
console.log(`plugin_id: ${share.plugin_id}`);
}
```
```csharp C#
AnthropicClient client = new();
var page = await client.Beta.Organization.Plugins.Shares.List("plugin_01Mr2wP7sU3aJ8vX5cY6nS9t");
await foreach (var share in page.Paginate())
{
Console.WriteLine($"plugin_id: {share.PluginID}");
}
```
```go Go
client := anthropic.NewClient()
shares := client.Beta.Organization.Plugins.Shares.ListAutoPaging(
context.Background(),
"plugin_01Mr2wP7sU3aJ8vX5cY6nS9t",
anthropic.BetaOrganizationPluginShareListParams{},
)
for shares.Next() {
share := shares.Current()
fmt.Printf("plugin_id: %s\n", share.PluginID)
}
if err := shares.Err(); err != nil {
log.Fatal(err)
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var shares = client.beta().organization().plugins().shares()
.list("plugin_01Mr2wP7sU3aJ8vX5cY6nS9t");
for (var share : shares.autoPager()) {
IO.println("plugin_id: " + share.pluginId());
}
```
```php PHP
$client = new Client();
$shares = $client->beta->organization->plugins->shares->list(
pluginID: 'plugin_01Mr2wP7sU3aJ8vX5cY6nS9t',
);
// Apenas esta página; para a próxima, chame list() novamente com page: $shares->nextPage.
foreach ($shares->getItems() as $share) {
echo "plugin_id: {$share->pluginID}\n";
}
```
```ruby Ruby
client = Anthropic::Client.new
plugin_id = "plugin_01Mr2wP7sU3aJ8vX5cY6nS9t"
page = client.beta.organization.plugins.shares.list(plugin_id)
page.auto_paging_each do |share|
puts "plugin_id: #{share.plugin_id}"
end
```
```json
{
"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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#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.
```json
{
"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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#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 acontece 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`.
```bash cURL
curl "https://api.anthropic.com/v1/organizations/plugin_marketplaces?owner_type=organization" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01"
```
```bash CLI
ant beta:organization:plugin-marketplaces list --owner-type organization
```
```python Python
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}")
```
```typescript TypeScript
const client = new Anthropic();
const marketplaces = await client.beta.organization.pluginMarketplaces.list({
owner_type: "organization"
});
for await (const marketplace of marketplaces) {
console.log(`${marketplace.id}: ${marketplace.name}`);
}
```
```csharp C#
using Anthropic.Models.Beta.Organization.PluginMarketplaces;
AnthropicClient client = new();
var page = await client.Beta.Organization.PluginMarketplaces.List(
new() { OwnerType = OwnerType.Organization }
);
await foreach (var marketplace in page.Paginate())
{
Console.WriteLine($"{marketplace.ID}: {marketplace.Name}");
}
```
```go Go
client := anthropic.NewClient()
marketplaces := client.Beta.Organization.PluginMarketplaces.ListAutoPaging(
context.Background(),
anthropic.BetaOrganizationPluginMarketplaceListParams{
OwnerType: anthropic.BetaOrganizationPluginMarketplaceListParamsOwnerTypeOrganization,
},
)
for marketplaces.Next() {
marketplace := marketplaces.Current()
fmt.Printf("%s: %s\n", marketplace.ID, marketplace.Name)
}
if err := marketplaces.Err(); err != nil {
log.Fatal(err)
}
```
```java Java
import com.anthropic.models.beta.organization.pluginmarketplaces.PluginMarketplaceListParams;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var params = PluginMarketplaceListParams.builder()
.ownerType(PluginMarketplaceListParams.OwnerType.ORGANIZATION)
.build();
var marketplaces = client.beta().organization().pluginMarketplaces().list(params);
for (var marketplace : marketplaces.autoPager()) {
IO.println(marketplace.id() + ": " + marketplace.name());
}
}
```
```php PHP
use Anthropic\Beta\Organization\PluginMarketplaces\PluginMarketplaceListParams\OwnerType;
// ...
$client = new Client();
$marketplaces = $client->beta->organization->pluginMarketplaces->list(
ownerType: OwnerType::ORGANIZATION,
);
// Apenas esta página; para a próxima, chame list() novamente com page: $marketplaces->nextPage.
foreach ($marketplaces->getItems() as $marketplace) {
echo "{$marketplace->id}: {$marketplace->name}\n";
}
```
```ruby Ruby
client = Anthropic::Client.new
page = client.beta.organization.plugin_marketplaces.list(owner_type: :organization)
page.auto_paging_each do |marketplace|
puts "#{marketplace.id}: #{marketplace.name}"
end
```
### Obter um marketplace
`GET /v1/organizations/plugin_marketplaces/{marketplace_id}` retorna um marketplace. Requer o escopo `read:plugins`.
```bash cURL
curl "https://api.anthropic.com/v1/organizations/plugin_marketplaces/marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01"
```
```bash CLI
ant beta:organization:plugin-marketplaces retrieve \
--marketplace-id marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r
```
```python Python
client = anthropic.Anthropic()
marketplace = client.beta.organization.plugin_marketplaces.retrieve(
"marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r"
)
print(f"id: {marketplace.id}")
print(f"name: {marketplace.name}")
```
```typescript TypeScript
const client = new Anthropic();
const marketplace = await client.beta.organization.pluginMarketplaces.retrieve(
"marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r"
);
console.log(`id: ${marketplace.id}`);
console.log(`name: ${marketplace.name}`);
```
```csharp C#
AnthropicClient client = new();
var marketplace = await client.Beta.Organization.PluginMarketplaces.Retrieve(
"marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r"
);
Console.WriteLine($"id: {marketplace.ID}");
Console.WriteLine($"name: {marketplace.Name}");
```
```go Go
client := anthropic.NewClient()
marketplace, err := client.Beta.Organization.PluginMarketplaces.Get(
context.Background(),
"marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r",
anthropic.BetaOrganizationPluginMarketplaceGetParams{},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("id: %s\n", marketplace.ID)
fmt.Printf("name: %s\n", marketplace.Name)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var marketplace = client.beta().organization().pluginMarketplaces()
.retrieve("marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r");
IO.println("id: " + marketplace.id());
IO.println("name: " + marketplace.name());
```
```php PHP
$client = new Client();
$marketplace = $client->beta->organization->pluginMarketplaces->retrieve(
marketplaceID: 'marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r',
);
echo "id: {$marketplace->id}\n";
echo "name: {$marketplace->name}\n";
```
```ruby Ruby
client = Anthropic::Client.new
marketplace_id = "marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r"
marketplace = client.beta.organization.plugin_marketplaces.retrieve(marketplace_id)
puts "id: #{marketplace.id}"
puts "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`.
```bash cURL
curl -X POST "https://api.anthropic.com/v1/organizations/plugin_marketplaces/marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r" \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01" \
-d '{"default_installation_preference": "available"}'
```
```bash CLI
ant beta:organization:plugin-marketplaces update \
--marketplace-id marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r \
--default-installation-preference available
```
```python Python
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}")
```
```typescript TypeScript
const client = new Anthropic();
const marketplace = await client.beta.organization.pluginMarketplaces.update(
"marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r",
{ default_installation_preference: "available" }
);
console.log(`id: ${marketplace.id}`);
console.log(`default_installation_preference: ${marketplace.default_installation_preference}`);
```
```csharp C#
using Anthropic.Models.Beta.Organization.PluginMarketplaces;
AnthropicClient client = new();
var marketplace = await client.Beta.Organization.PluginMarketplaces.Update(
"marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r",
new() { DefaultInstallationPreference = DefaultInstallationPreference.Available }
);
Console.WriteLine($"id: {marketplace.ID}");
Console.WriteLine(
$"default_installation_preference: {marketplace.DefaultInstallationPreference?.Raw()}"
);
```
```go Go
client := anthropic.NewClient()
marketplace, err := client.Beta.Organization.PluginMarketplaces.Update(
context.Background(),
"marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r",
anthropic.BetaOrganizationPluginMarketplaceUpdateParams{
DefaultInstallationPreference: anthropic.BetaOrganizationPluginMarketplaceUpdateParamsDefaultInstallationPreferenceAvailable,
},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("id: %s\n", marketplace.ID)
fmt.Printf("default_installation_preference: %s\n", marketplace.DefaultInstallationPreference)
```
```java Java
import com.anthropic.models.beta.organization.pluginmarketplaces.PluginMarketplaceUpdateParams;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var params = PluginMarketplaceUpdateParams.builder()
.defaultInstallationPreference(PluginMarketplaceUpdateParams.DefaultInstallationPreference.AVAILABLE)
.build();
var marketplace = client.beta().organization().pluginMarketplaces()
.update("marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r", params);
IO.println("id: " + marketplace.id());
IO.println("default_installation_preference: "
+ marketplace.defaultInstallationPreference().map(preference -> preference.asString()).orElse(null));
}
```
```php PHP
use Anthropic\Beta\Organization\PluginMarketplaces\PluginMarketplaceUpdateParams\DefaultInstallationPreference;
// ...
$client = new Client();
$marketplace = $client->beta->organization->pluginMarketplaces->update(
marketplaceID: 'marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r',
defaultInstallationPreference: DefaultInstallationPreference::AVAILABLE,
);
echo "id: {$marketplace->id}\n";
echo "default_installation_preference: {$marketplace->defaultInstallationPreference}\n";
```
```ruby Ruby
client = Anthropic::Client.new
marketplace_id = "marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r"
marketplace = client.beta.organization.plugin_marketplaces.update(
marketplace_id,
default_installation_preference: :available
)
puts "id: #{marketplace.id}"
puts "default_installation_preference: #{marketplace.default_installation_preference}"
```
### Validar o conteúdo de um marketplace
Dois endpoints informam o que uma sincronização do conteúdo de marketplace fornecido faria, sem conectar nem armazenar nada: `POST /v1/organizations/plugin_marketplaces/validate_repository` lê um repositório público do GitHub, e `POST /v1/organizations/plugin_marketplaces/validate_archive` lê um `.zip` do diretório do marketplace que você envia. Ambos retornam o mesmo relatório: se `marketplace.json` está bem formado, quais plugins seriam ignorados e por quê, e quais plugins seriam sincronizados com parte de seu conteúdo deixada de fora. As verificações são as mesmas que uma sincronização real executa. Problemas com o conteúdo voltam no relatório, não como erros HTTP: a requisição é bem-sucedida com `valid: false`, mesmo quando o repositório ou o arquivo compactado não pode ser lido de forma alguma. Uma validação conta como uma leitura, e os dois endpoints juntos são adicionalmente limitados a 10 validações por minuto por organização (consulte [Limitação de taxa](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#rate-limiting)); eles não registram nada no Activity Feed. Uma validação pode levar até 120 segundos para retornar, então defina o timeout do seu cliente acima disso. Ambos os endpoints exigem o escopo `read:plugins` ou `write:plugins` (`read:org_audit` e `read:compliance_org_data` não os concedem).
O repositório, e qualquer origem de plugin fora dele no GitHub, são lidos anonimamente, então um repositório privado ou uma origem de plugin privada é informado como não encontrado. Origens de plugin em hosts que não sejam o GitHub não são buscadas; esse tipo de plugin normalmente recebe um aviso `marketplace_validate_source_not_checked` e é verificado quando o marketplace é de fato sincronizado. Se o repositório for, ou o arquivo compactado nomear, um marketplace que a Anthropic sincroniza em todas as organizações, regras mais rígidas se aplicam: toda origem de plugin fora do marketplace deve estar fixada em um SHA de commit completo, origens não fixadas ou em hosts não suportados são informadas como erros de plugin, e o branch lido por padrão é aquele a partir do qual esse marketplace é sincronizado.
`validate_repository` recebe um corpo JSON com dois campos: `repository_url`, a URL `https://` de um repositório público no github.com (obrigatório), e `ref`, um nome de branch ou um SHA de commit completo de 40 caracteres (opcional; quando omitido ou `null`, é usado o branch que uma sincronização leria, geralmente o branch padrão do repositório). `validate_archive` recebe `multipart/form-data` com exatamente uma parte, `archive`, enviada como uma parte de arquivo com um nome de arquivo: um `.zip` do diretório do marketplace, com no máximo 32 MB, com seu conteúdo na raiz ou envolvido em uma única pasta (como o download de um host Git produz), apenas com compressão DEFLATE ou STORE. Nenhum outro campo de formulário é aceito.
Validar um repositório público em um branch:
```bash cURL
curl -X POST "https://api.anthropic.com/v1/organizations/plugin_marketplaces/validate_repository" \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01" \
-d '{"repository_url": "https://github.com/example-org/claude-plugins", "ref": "release-candidate"}'
```
```bash CLI
ant beta:organization:plugin-marketplaces validate-repository \
--repository-url https://github.com/example-org/claude-plugins \
--ref release-candidate
```
```python Python
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}")
```
```typescript TypeScript
const client = new Anthropic();
const report = await client.beta.organization.pluginMarketplaces.validateRepository({
repository_url: "https://github.com/example-org/claude-plugins",
ref: "release-candidate"
});
console.log(`valid: ${report.valid}`);
console.log(`total_plugin_count: ${report.total_plugin_count}`);
```
```csharp C#
AnthropicClient client = new();
var report = await client.Beta.Organization.PluginMarketplaces.ValidateRepository(
new()
{
RepositoryUrl = "https://github.com/example-org/claude-plugins",
Ref = "release-candidate",
}
);
Console.WriteLine($"valid: {report.Valid.ToString().ToLowerInvariant()}");
Console.WriteLine($"total_plugin_count: {report.TotalPluginCount}");
```
```go Go
client := anthropic.NewClient()
report, err := client.Beta.Organization.PluginMarketplaces.ValidateRepository(
context.Background(),
anthropic.BetaOrganizationPluginMarketplaceValidateRepositoryParams{
RepositoryURL: "https://github.com/example-org/claude-plugins",
Ref: anthropic.String("release-candidate"),
},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("valid: %t\n", report.Valid)
fmt.Printf("total_plugin_count: %d\n", report.TotalPluginCount)
```
```java Java
import com.anthropic.models.beta.organization.pluginmarketplaces.PluginMarketplaceValidateRepositoryParams;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var params = PluginMarketplaceValidateRepositoryParams.builder()
.repositoryUrl("https://github.com/example-org/claude-plugins")
.ref("release-candidate")
.build();
var report = client.beta().organization().pluginMarketplaces().validateRepository(params);
IO.println("valid: " + report.valid());
IO.println("total_plugin_count: " + report.totalPluginCount());
}
```
```php PHP
$client = new Client();
$report = $client->beta->organization->pluginMarketplaces->validateRepository(
repositoryURL: 'https://github.com/example-org/claude-plugins',
ref: 'release-candidate',
);
echo 'valid: ' . ($report->valid ? 'true' : 'false') . "\n";
echo "total_plugin_count: {$report->totalPluginCount}\n";
```
```ruby Ruby
client = Anthropic::Client.new
report = client.beta.organization.plugin_marketplaces.validate_repository(
repository_url: "https://github.com/example-org/claude-plugins",
ref: "release-candidate"
)
puts "valid: #{report.valid}"
puts "total_plugin_count: #{report.total_plugin_count}"
```
```json
{
"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` | Definidos quando nada pôde ser validado: a origem não pôde ser lida, ou `marketplace.json` está ausente, malformado ou acima de um limite. Uma validação que não terminou em 120 segundos informa `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:
```bash cURL
curl -X POST "https://api.anthropic.com/v1/organizations/plugin_marketplaces/validate_archive" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: ce-plugins-2026-09-01" \
-F "archive=@marketplace.zip"
```
```bash CLI
ant beta:organization:plugin-marketplaces validate-archive \
--archive marketplace.zip
```
```python Python
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}")
```
```typescript TypeScript
import fs from "node:fs";
const client = new Anthropic();
const report = await client.beta.organization.pluginMarketplaces.validateArchive({
archive: fs.createReadStream("marketplace.zip")
});
console.log(`valid: ${report.valid}`);
console.log(`total_plugin_count: ${report.total_plugin_count}`);
```
```csharp C#
AnthropicClient client = new();
var report = await client.Beta.Organization.PluginMarketplaces.ValidateArchive(
new() { Archive = File.OpenRead("marketplace.zip") }
);
Console.WriteLine($"valid: {report.Valid.ToString().ToLowerInvariant()}");
Console.WriteLine($"total_plugin_count: {report.TotalPluginCount}");
```
```go Go
client := anthropic.NewClient()
archive, err := os.Open("marketplace.zip")
if err != nil {
log.Fatal(err)
}
defer archive.Close()
report, err := client.Beta.Organization.PluginMarketplaces.ValidateArchive(
context.Background(),
anthropic.BetaOrganizationPluginMarketplaceValidateArchiveParams{
Archive: archive,
},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("valid: %t\n", report.Valid)
fmt.Printf("total_plugin_count: %d\n", report.TotalPluginCount)
```
```java Java
import com.anthropic.models.beta.organization.pluginmarketplaces.PluginMarketplaceValidateArchiveParams;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Passe um Path para que a parte `archive` seja enviada com um nome de arquivo, exigido por este endpoint.
var params = PluginMarketplaceValidateArchiveParams.builder()
.archive(Path.of("marketplace.zip"))
.build();
var report = client.beta().organization().pluginMarketplaces().validateArchive(params);
IO.println("valid: " + report.valid());
IO.println("total_plugin_count: " + report.totalPluginCount());
}
```
```php PHP
use Anthropic\Core\FileParam;
$client = new Client();
$report = $client->beta->organization->pluginMarketplaces->validateArchive(
archive: FileParam::fromResource(fopen('marketplace.zip', 'r')),
);
echo 'valid: ' . ($report->valid ? 'true' : 'false') . "\n";
echo "total_plugin_count: {$report->totalPluginCount}\n";
```
```ruby Ruby
client = Anthropic::Client.new
report = client.beta.organization.plugin_marketplaces.validate_archive(
archive: Pathname("marketplace.zip")
)
puts "valid: #{report.valid}"
puts "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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#error-responses) e [Limitação de taxa](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#rate-limiting)), 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` da página de um branch, ou uma porta diferente de 443 ou 80 não sã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 requisição é bem-sucedida com `valid: false` e `manifest_error` informa 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 requisiçã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, então a mesma requisição pode ser bem-sucedida mais tarde: `marketplace_host_rate_limited`, `marketplace_host_server_error`, `marketplace_host_timeout`, `marketplace_host_unreachable`, `marketplace_repo_access_denied`, `marketplace_sync_transient_fetch_budget_exhausted`, `marketplace_validate_network_error` e, geralmente, `marketplace_validate_deadline_exceeded`.
## Valores não reconhecidos
Todo valor de string nesta página (tipos de componente, `reach`, campos de verificação, `source` de marketplace, códigos de erro) pode ganhar novos valores a qualquer momento. Trate um valor que você não reconhece como trataria qualquer string desconhecida, em vez de falhar.
## Limitação de taxa
As requisições de leitura (todos os endpoints `GET` desta página) compartilham um "rate limit" (limite de taxa) de **300 requisições por minuto** por organização, e as requisições de gravação (criar um plugin ou versão, alterar a versão servida, excluir, definir ou remover uma configuração de instalação e atualizar um marketplace) compartilham um limite de **60 requisições por minuto** por organização. Uma validação de marketplace (em qualquer um dos endpoints) conta como uma leitura, e as validações são adicionalmente limitadas a 10 por minuto por organização somando os dois endpoints; ambos os limites são verificados antes de o corpo da requisição ser lido. Esses limites são contabilizados em todas as chaves da sua organização e são separados dos outros limites da Admin API da sua organização. Requisições acima de um limite retornam **429 Too Many Requests** com um cabeçalho `retry-after`. As respostas incluem cabeçalhos `anthropic-ratelimit-requests-*` para o limite aplicável (na validação de marketplace, seu limite de 10 por minuto; em um `429`, o limite que recusou a requisição).
Um upload, uma alteração de versão servida ou uma validação também pode retornar `429` com `retry-after` quando o serviço momentaneamente não tem capacidade para mais uma operação, e um upload retorna `429` quando sua organização excedeu sua taxa de verificação de conteúdo. Trate todos esses casos da mesma forma: aguarde o `retry-after` e tente novamente. Independentemente desses limites, envie as gravações de configuração de instalação para o mesmo plugin uma de cada vez: quando várias chegam ao mesmo tempo, algumas podem ser respondidas com `503` e `x-should-retry: true`, e é seguro enviá-las novamente após um ou dois segundos (consulte [Definir uma configuração de instalação](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#set-an-installation-setting)).
## 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#list-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](https://platform.claude.com/docs/pt-BR/api/errors). 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, uma verificação de conteúdo ainda está em execução 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#rate-limiting). |
| 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`:
```json
{
"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 | Já existe um plugin com este nome no marketplace. `details.plugin_id` é esse plugin. Se você estiver repetindo uma criação cuja resposta foi perdida, continue com esse plugin. Quando `plugin_id` estiver ausente, o nome pertence a uma skill independente: faça o upload com outro nome ou exclua a skill no claude.ai. |
| `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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#retrying-uploads). |
| `scan_pending` | 409 | A verificação de conteúdo da versão ainda está em execução. Tente novamente quando ela terminar. |
| `scan_failed` | 400 | A verificação de conteúdo da versão falhou, apresentou erro ou não chegou a um veredito, portanto a versão 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](https://platform.claude.com/docs/pt-BR/manage-claude/plugins-api#customer-managed-encryption-keys). |
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, tente novamente: a nova tentativa retorna `409 plugin_name_taken` com o ID do plugin em `details.plugin_id`, e você continua com esse plugin. Repetir uma criação de versão cuja resposta foi perdida armazena uma segunda versão idêntica. Para evitar isso, registre o `latest_version_id` do plugin antes de cada upload; se uma resposta for perdida, leia o plugin e tente novamente somente se `latest_version_id` não tiver mudado.
## Eventos do Activity Feed
Toda gravação feita por meio desta API é registrada no [Compliance API Activity Feed](https://platform.claude.com/docs/pt-BR/manage-claude/compliance-activity-feed) da sua organização, atribuída à chave de API como um `api_actor` que contém seu ID `apikey_`. O mesmo ator aparece em `created_by` nos plugins e nas versões que a chave cria.
| 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. `plugin_installation_preference_updated` identifica o plugin por seu `name` e `marketplace_id` em vez de seu `id`.
Alterar o padrão de um marketplace registra um evento `marketplace_updated` e nenhum evento por plugin, mesmo que isso altere o valor de todos os plugins que herdam o padrão. Leituras não são registradas, exceto downloads do arquivo de um plugin pertencente a um membro. Uma gravação que não altera nada não registra nada.
Compartilhamentos concedidos ou retirados no claude.ai aparecem no feed como eventos `role_assignment_granted` e `role_assignment_revoked`. Esta API não informa exclusões: um plugin excluído simplesmente não aparece na próxima listagem. Um plugin removido por uma sincronização do Git, pela exclusão de seu marketplace (um evento `marketplace_deleted`) ou pela exclusão da conta de um membro ou da organização não emite nenhum evento por plugin; portanto, liste novamente o inventário completo periodicamente para detectar remoções.
## Chaves de criptografia gerenciadas pelo cliente
Se sua organização usa uma ["customer-managed encryption key" (chave de criptografia gerenciada pelo cliente)](https://platform.claude.com/docs/pt-BR/manage-claude/cmek), 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.