---
title: API Plugins
url: https://platform.claude.com/docs/it/manage-claude/plugins-api
description: "Inventaria e gestisci i plugin nella tua organizzazione Claude Enterprise: carica plugin e versioni, scegli la versione distribuita ai membri, controlla chi può usare ciascun plugin, scarica i file dei plugin per la revisione e convalida un marketplace prima di collegarlo."
---
L'API Plugins ti consente di inventariare ogni plugin nella tua organizzazione Claude Enterprise, pubblicare plugin e nuove versioni dalle tue pipeline, scegliere quale versione viene distribuita ai membri, controllare chi può usare ciascun plugin, scaricare i file dei plugin per la revisione e verificare un marketplace Git prima di collegarlo.
Per i report sull'*utilizzo* dei plugin (quali plugin e skill usano i membri e con quale frequenza), consulta [API Analytics](https://platform.claude.com/docs/it/manage-claude/analytics-api).
**Richiesta una chiave API Admin con scope**
Questi endpoint richiedono una chiave API Admin con lo "scope" (ambito) `read:plugins` (per gli endpoint `GET`, inclusi i download degli archivi) o lo scope `write:plugins` (per gli endpoint `POST` e `DELETE`, eccetto la convalida del marketplace, consentita da entrambi gli scope); [Scope](https://platform.claude.com/docs/it/manage-claude/plugins-api#scopes) contiene i dettagli, inclusi altri due scope di lettura che funzionano anch'essi. Consulta [Creare una chiave API Admin](https://platform.claude.com/docs/it/manage-claude/admin-api-keys#create-a-key-for-a-claude-enterprise-organization) per sapere dove il tuo proprietario principale ne crea una. Passa la chiave nell'header `x-api-key` in ogni richiesta, insieme all'header [`anthropic-version`](https://platform.claude.com/docs/it/api/versioning) e all'header beta mostrato nella nota seguente.
L'API Plugins è in **beta** ed è disponibile solo per le organizzazioni Claude Enterprise. Non è disponibile per le organizzazioni Claude Platform (Claude Console), né per le organizzazioni con la predisposizione HIPAA abilitata.
Ogni richiesta deve includere l'[header beta](https://platform.claude.com/docs/it/api/beta-headers) `anthropic-beta: ce-plugins-2026-09-01` (gli SDK e la CLI `ant` lo inviano per te). Una richiesta senza di esso restituisce `404`, esattamente come se l'endpoint non esistesse.
## Endpoint
L'API espone 18 endpoint distribuiti su cinque risorse:
| Risorsa | Endpoint |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Plugin**: elenca ogni plugin nell'organizzazione, caricane uno nuovo, cercane uno, scegli la versione distribuita ai membri (rollback o promozione), eliminane uno | `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}` |
| **Versioni dei plugin**: elenca la cronologia delle versioni di un plugin, carica una nuova versione, cercane una, scarica i file di una versione | `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` |
| **Impostazioni di installazione**: leggi chi può usare un plugin di proprietà dell'organizzazione, impostalo per l'intera organizzazione o per un gruppo, rimuovi una delle due impostazioni | `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}` |
| **Condivisioni**: leggi con chi un membro ha condiviso il proprio plugin (sola lettura) | `GET /v1/organizations/plugins/{plugin_id}/shares` |
| **Marketplace di plugin**: trova l'ID di un marketplace, cercane uno, configura l'impostazione di installazione predefinita per i suoi plugin, verifica il contenuto del marketplace prima di collegarlo | `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` |
Questa versione non include le skill autonome (skill che un membro scrive nell'editor delle skill o carica come singola skill in claude.ai). Non compaiono nell'inventario e non possono essere create qui. Anche i plugin pubblicati da Anthropic non sono inventariati; il loro utilizzo è riportato dalle [API Analytics](https://platform.claude.com/docs/it/manage-claude/analytics-api). I marketplace vengono creati, collegati ai repository ed eliminati in claude.ai, non tramite questa API.
## Prerequisiti
* La tua organizzazione deve avere un piano Claude Enterprise.
* Il tuo proprietario principale crea una chiave API Admin con lo scope `read:plugins`, lo scope `write:plugins` o entrambi in [claude.ai > Impostazioni dell'organizzazione > API](https://claude.ai/admin-settings/api-access). Consulta [Creare una chiave API Admin](https://platform.claude.com/docs/it/manage-claude/admin-api-keys#create-a-key-for-a-claude-enterprise-organization).
* Ogni richiesta include tre header: `x-api-key`, `anthropic-version: 2023-06-01` e `anthropic-beta: ce-plugins-2026-09-01`.
Gli SDK Python, TypeScript, C#, Go, Java, PHP e Ruby espongono questi endpoint sotto `client.beta.organization` (csharp, go: `client.Beta.Organization`; java: `client.beta().organization()`; php: `$client->beta->organization`), e la [CLI `ant`](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/quickstart) sotto `ant beta:organization`; inviano per te gli header `anthropic-version` e `anthropic-beta`. Gli esempi in questa pagina usano il client predefinito di ciascun SDK che, come la CLI, legge la chiave Admin API dalla variabile d'ambiente `ANTHROPIC_API_KEY`; gli esempi curl leggono la chiave dalla stessa variabile e la passano nell'header `x-api-key`. Quando un SDK o la CLI recupera altre pagine per te, `limit` imposta la dimensione della pagina, non il totale (consulta [Paginazione](https://platform.claude.com/docs/it/manage-claude/plugins-api#pagination)).
Le chiavi API appartengono all'organizzazione e continuano a funzionare anche dopo che la persona che le ha create se ne va. Non condividerle e non inserirle nel controllo del codice sorgente.
## Avvio rapido
Elenca i plugin nei marketplace della tua organizzazione, dal più recente:
```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)
# Recupera automaticamente altre pagine quando necessario.
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,
);
// Solo questa pagina; per la successiva, richiama list() con 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"
}
```
In questo esempio il plugin è fissato a una versione precedente: una versione più recente (`latest_version_id`) è archiviata ma non ancora distribuita.
## Scope
| Scope | Concede |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read:plugins` | Ogni endpoint `GET` in questa pagina, inclusi i download degli archivi, più la convalida del marketplace. |
| `write:plugins` | Ogni endpoint `POST` e `DELETE` in questa pagina: creare un plugin, creare una versione, cambiare la versione distribuita, eliminare un plugin, configurare e rimuovere le impostazioni di installazione e configurare il valore predefinito di un marketplace, più la convalida del marketplace. Non concede le letture. |
| `read:org_audit` | Uno scope di sola lettura per le integrazioni di audit di sicurezza: ogni endpoint `GET` in questa pagina, inclusi i download degli archivi, più gli endpoint di lettura della [gestione utenti](https://platform.claude.com/docs/it/manage-claude/user-management) e della [Compliance API](https://platform.claude.com/docs/it/manage-claude/compliance-api). Non concede la convalida del marketplace né alcuna scrittura. |
| `read:compliance_org_data` | Lo scope della Compliance API per i metadati dell'organizzazione (nomi, tipi, ruoli e gruppi) e le impostazioni effettive. Concede ogni endpoint `GET` in questa pagina, esattamente come `read:org_audit`, quindi una Compliance Access Key può leggere i plugin senza una seconda chiave. Non concede la convalida del marketplace né alcuna scrittura. |
Una chiave può avere più scope. Un'integrazione che carica un plugin e poi lo rilegge necessita sia di `read:plugins` sia di `write:plugins`. Ovunque questa pagina indichi che un endpoint richiede lo scope `read:plugins`, funziona anche una chiave con `read:org_audit` o `read:compliance_org_data`.
### Accesso ai file dei plugin dei membri
Ciascuno di questi scope di lettura (`read:plugins`, `read:org_audit` e `read:compliance_org_data`) può scaricare i file dei plugin nei marketplace personali dei membri, inclusi i file che le impostazioni di amministrazione di claude.ai non mostrano, e una chiave `read:org_audit` o `read:compliance_org_data` associata alla tua organizzazione padre può farlo in qualsiasi organizzazione sottostante che abbia accesso a questa API, passando `organization_id` (consulta [Leggere un'altra organizzazione sotto lo stesso padre](https://platform.claude.com/docs/it/manage-claude/plugins-api#reading-another-organization-under-the-same-parent)). Ogni download di questo tipo registra un evento `claude_plugin_archive_accessed` nel [Compliance API Activity Feed](https://platform.claude.com/docs/it/manage-claude/compliance-activity-feed), che identifica la chiave, il plugin, la versione e il membro (consulta [Eventi dell'Activity Feed](https://platform.claude.com/docs/it/manage-claude/plugins-api#activity-feed-events)). I download dei plugin di proprietà dell'organizzazione non vengono registrati.
### Leggere un'altra organizzazione sotto lo stesso padre
Le chiavi `read:plugins` e `write:plugins` leggono e scrivono solo nell'organizzazione in cui sono state create. Se la tua azienda ha diverse organizzazioni Claude collegate sotto un'unica organizzazione padre, una chiave `read:org_audit` o `read:compliance_org_data` che il proprietario principale dell'organizzazione padre ha creato per tutte le organizzazioni collegate (consulta [Creare una chiave API Admin](https://platform.claude.com/docs/it/manage-claude/admin-api-keys#create-a-key-for-a-claude-enterprise-organization)) può anche leggere qualsiasi di esse che abbia accesso a questa API: passa l'ID di quell'organizzazione nel parametro di query `organization_id` su qualsiasi endpoint `GET` in questa pagina. L'ID è l'UUID dell'organizzazione mostrato nelle impostazioni di claude.ai (è accettata anche la sua forma con prefisso `org_`). Senza il parametro, la chiave legge l'organizzazione in cui è stata creata. Un `404` significa che l'organizzazione indicata non si trova sotto l'organizzazione padre della chiave o che l'API non è disponibile per essa; un valore che non è un UUID o un ID `org_` restituisce `400`. Qualsiasi altra chiave che indichi un'organizzazione diversa dalla propria riceve `404`. Le scritture non accettano `organization_id`.
## Concetti chiave
### Plugin e componenti
Un **plugin** è un pacchetto che estende Claude per i membri della tua organizzazione. Contiene qualsiasi combinazione di questi componenti:
| Componente | Che cos'è |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Skill | Istruzioni e file che Claude carica quando un'attività lo richiede. |
| Comando | Un prompt salvato che un membro esegue digitando `/` seguito dal nome del comando. |
| Agente | Un assistente ausiliario con le proprie istruzioni, a cui Claude può affidare parte di un'attività. |
| Hook | Un comando che viene eseguito automaticamente quando si verifica un evento in una sessione, ad esempio prima che Claude usi uno strumento. |
| Server MCP | Una connessione da Claude a strumenti e dati in un altro sistema (Model Context Protocol). |
| CLI | Un programma a riga di comando che il plugin consente a Claude di eseguire. |
Ogni plugin ha un manifest in `.claude-plugin/plugin.json`. Il `name` del manifest diventa il `name` del plugin: un identificatore in minuscolo univoco all'interno del suo marketplace.
### Marketplace
Un **marketplace** è un contenitore di plugin. Ogni marketplace ha un proprietario e un'origine.
* **Proprietario.** L'organizzazione possiede i propri marketplace. Ogni membro può anche avere marketplace personali.
* **Origine.** `manual` significa che i plugin vengono caricati, in claude.ai o, per un marketplace dell'organizzazione, tramite questa API. `github`, `gitlab` e `public_git` significano che i plugin sono sincronizzati da un repository Git collegato dal proprietario. Non è possibile caricare nulla in un marketplace sincronizzato, e questa API non può eliminarne i plugin, perché la sincronizzazione successiva annullerebbe entrambe le modifiche. Modifica invece il repository.
Il "library marketplace" (marketplace della libreria) della tua organizzazione è il marketplace `manual` di proprietà dell'organizzazione in cui finiscono i caricamenti quando non specifichi un marketplace. Viene creato la prima volta che vi si carica qualcosa.
### Plugin di proprietà dell'organizzazione e dei membri
L'`owner.type` di un plugin indica in quale marketplace si trova:
* `organization`: puoi gestirlo tramite questa API, tranne per il fatto che un plugin in un marketplace sincronizzato da Git non può ricevere caricamenti né essere eliminato qui.
* `user`: si trova nel marketplace personale di un membro. Puoi leggerne i dettagli e scaricarne i file, ed eliminarlo se il suo marketplace è `manual`. Il caricamento di versioni e la scelta della versione distribuita restituiscono `403`. La condivisione è gestita solo dal membro, in claude.ai.
La rimozione di un membro dall'organizzazione non rimuove i suoi plugin. Restano nell'inventario sotto lo `user_id` del membro, e il filtro `owner_user_id` li trova ancora, così puoi esaminare e rimuovere i contenuti di un membro che se n'è andato. Vengono rimossi dall'inventario quando l'account del membro viene eliminato.
### Versioni e versione distribuita
Ogni caricamento crea una nuova **version** (versione) immutabile, che provenga da questa API, da claude.ai o da una sincronizzazione Git. Un plugin ha due puntatori alle sue versioni:
* `latest_version_id`: la versione più recente.
* `served_version_id`: la "served version" (versione distribuita), ovvero quella distribuita ai membri.
Per impostazione predefinita `served_version_pinned` è `false`: la versione distribuita normalmente segue quella più recente. Quando la scansione dei contenuti è attiva, una versione salvata in claude.ai potrebbe **attendere** la propria scansione dei contenuti: viene archiviata ma non distribuita subito. Questa pagina usa "attendere" solo per una versione salvata in claude.ai, non per una che un membro o un amministratore pubblica in un plugin. Mentre la scansione è attiva, una versione in attesa viene distribuita solo dopo che la sua scansione si completa con `pass` o `warn`. Mentre una versione è in attesa, `served_version_id` indica una versione precedente a `latest_version_id`. Non eseguire il polling finché i due ID non coincidono: potrebbero restare diversi, ad esempio quando la scansione fallisce.
La scelta di una versione con `POST /v1/organizations/plugins/{plugin_id}` esegue il **pin** (fissaggio) del plugin (`served_version_pinned: true`). Lo stesso accade quando un amministratore sceglie una versione in claude.ai, o accetta la richiesta di un membro di pubblicare nel plugin. Da quel momento, i nuovi caricamenti vengono archiviati e fanno avanzare `latest_version_id`, ma i membri mantengono la versione fissata finché non punti `served_version_id` a un'altra. Un plugin i cui due puntatori differiscono ha una versione archiviata che non viene distribuita.
Questo consente a una pipeline di rilascio di caricare ogni build, testarla e poi promuoverla. Per fare in modo che sia la tua pipeline a decidere quando ogni build viene distribuita, fissa il plugin una volta impostando `served_version_id` sulla sua versione corrente; da quel momento, promuovi ogni build che vuoi distribuire. Con la scansione dei contenuti attiva, quel primo fissaggio restituisce `409 scan_pending` finché la scansione della versione corrente non è completata, e `400 scan_failed` se la scansione si è completata con `fail` o `unknown`, o è andata in errore (`warn` è accettato). Un plugin fissato attualmente non può essere sbloccato, né qui né in claude.ai.
Per eseguire il rollback, imposta `served_version_id` su una versione precedente. Per avanzare, procedi allo stesso modo.
Queste regole descrivono i plugin di proprietà dell'organizzazione. La versione distribuita di un plugin di proprietà di un membro è controllata dal suo proprietario in claude.ai.
### Impostazioni di installazione
Le "installation settings" (impostazioni di installazione) decidono chi può usare un plugin di proprietà dell'organizzazione. Ogni impostazione ha uno di quattro valori, contenuti nei campi denominati `installation_preference` (e, negli oggetti plugin e marketplace, `organization_installation_preference` e `default_installation_preference`):
| Valore | I membri vedono |
| --------------- | ------------------------------------------------ |
| `required` | Il plugin è installato e non può essere rimosso. |
| `auto_install` | Il plugin è installato e può essere rimosso. |
| `available` | Il plugin può essere installato su richiesta. |
| `not_available` | Il plugin è nascosto. |
Un plugin può avere un'impostazione a livello di organizzazione e un'impostazione per gruppo (i gruppi di controllo degli accessi basato sui ruoli gestiti in [Gestione utenti](https://platform.claude.com/docs/it/manage-claude/user-management#groups)). Un membro ottiene un valore secondo queste regole:
1. Il valore a livello di organizzazione è l'impostazione a livello di organizzazione del plugin stesso, se ne ha una, altrimenti il valore predefinito del suo marketplace, altrimenti `not_available`. Il plugin riporta questo valore in `organization_installation_preference`, con `organization_installation_preference_inherited: true` finché proviene dal valore predefinito del marketplace.
2. Un membro che non appartiene a nessun gruppo con un'impostazione per il plugin ottiene il valore a livello di organizzazione.
3. Un membro che appartiene a uno o più gruppi con un'impostazione ottiene invece la più permissiva tra le impostazioni di quei gruppi, in ordine `required`, `auto_install`, `available`, `not_available`.
L'impostazione di un gruppo sostituisce il valore a livello di organizzazione per i suoi membri; non si aggiunge a esso. Ad esempio, se il valore a livello di organizzazione è `required` e il gruppo Pilot ha `available`, i membri di Pilot ottengono `available`. Quando sposti un plugin da un gruppo pilota all'intera organizzazione, imposta il valore a livello di organizzazione e poi rimuovi l'impostazione del gruppo. Impostare il valore a livello di organizzazione impedisce al plugin di ereditare il valore predefinito del suo marketplace; [rimuovere l'impostazione a livello di organizzazione](https://platform.claude.com/docs/it/manage-claude/plugins-api#remove-an-installation-setting) riporta il plugin a quel valore predefinito.
Un plugin creato tramite questa API parte senza impostazioni proprie, quindi eredita il valore predefinito del suo marketplace: `not_available` a meno che qualcuno non abbia configurato un valore predefinito. L'eliminazione di un gruppo rimuove le sue impostazioni da ogni plugin.
### Condivisioni
Le "shares" (condivisioni) decidono chi può usare un plugin di proprietà di un membro. Il proprietario lo condivide in claude.ai con tutti i membri, con un gruppo o con membri specifici. Questa API elenca le condivisioni ma non può modificarle.
Se la tua organizzazione ha disattivato un tipo di condivisione nelle impostazioni di claude.ai, le condivisioni di quel tipo compaiono ancora nell'elenco ma non danno accesso a nessuno finché quell'impostazione è disattivata; l'elenco stesso non mostra se lo è.
### Scansione dei contenuti
La "content scanning" (scansione dei contenuti) è un'impostazione dell'organizzazione in claude.ai. Quando è attiva, le versioni appena archiviate vengono scansionate (claude.ai ne esenta alcune) e il risultato è riportato in `content_scan`; una versione che non è stata scansionata, ad esempio una archiviata prima dell'attivazione della scansione, ha `content_scan: null`. La scansione non è offerta alle organizzazioni che usano chiavi di crittografia gestite dal cliente o la conservazione zero dei dati.
Mentre la scansione è attiva, un plugin viene distribuito ai membri solo quando la scansione della sua versione distribuita è `completed` con `pass` o `warn`. Mentre la scansione è in corso, o dopo che fallisce, va in errore o non raggiunge un verdetto, il plugin viene negato ai membri, e una versione precedente non viene distribuita al suo posto. Una versione mai scansionata (`content_scan: null`) viene distribuita normalmente.
Una versione che carichi tramite questa API non attende mai la propria scansione dei contenuti. Quando diventa la versione distribuita, i membri perdono il plugin finché la sua scansione non viene superata, e ne restano privi se la scansione fallisce. Se i membri devono mantenere la versione corrente mentre ne viene scansionata una nuova, fissa prima il plugin (consulta [Versioni e versione distribuita](https://platform.claude.com/docs/it/manage-claude/plugins-api#versions-and-the-served-version)).
Mentre una versione salvata in claude.ai attende la propria scansione, la versione distribuita non cambia. Quando il tuo caricamento tramite API diventa la versione distribuita, qualsiasi attesa termina: la versione in attesa viene distribuita solo se qualcuno la sceglie. Per vedere la scansione di una versione in attesa, leggi la versione (consulta [Elenca le versioni di un plugin](https://platform.claude.com/docs/it/manage-claude/plugins-api#list-a-plugins-versions)).
Dopo un caricamento, `content_scan.status` è `processing` e il verdetto arriva in modo asincrono. Leggi la versione per vederlo; l'oggetto plugin mostra solo la scansione della sua versione distribuita. Cambiare la versione distribuita con una versione la cui scansione è ancora in corso restituisce `409 scan_pending`; con una la cui scansione è fallita, `400 scan_failed`.
### Reach
`reach` riassume, in un unico valore, fin dove arriva una versione sui computer dei membri e oltre:
| Valore | Significato |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `remote` | Dichiara un server MCP o una CLI, qualunque altra cosa dichiari. |
| `privileged` | Non dichiara alcun server MCP o CLI, ma dichiara un hook, un monitor (un comando in background che continua a essere eseguito durante una sessione), un server LSP (Language Server Protocol) o impostazioni che il plugin applica all'app del membro, oppure contiene una skill, un comando o qualsiasi altro file Markdown il cui frontmatter pre-approva strumenti (`allowed-tools`). Questi vengono eseguiti, o hanno effetto, sul computer del membro. |
| `contained` | Non dichiara alcun server MCP, CLI, hook, monitor, server LSP o impostazioni dell'app, e nessuno dei suoi file Markdown pre-approva strumenti (ad esempio, un plugin che contiene solo skill, comandi e agenti, nessuno con `allowed-tools`). |
`reach` tiene conto di tutto ciò che la versione dichiara, inclusi monitor, server LSP e impostazioni dell'app, che `components` non elenca, quindi una versione con un elenco `components` vuoto può comunque essere `privileged`. È `null` per una versione archiviata prima che i componenti venissero registrati, e per una versione la cui portata non è stata determinata perché non è stato possibile leggere il `SKILL.md` di una delle sue skill, o uno dei suoi file di comando; tratta `null` come non classificato.
### Requisiti di caricamento
I caricamenti seguono le stesse regole dei caricamenti di plugin in claude.ai, quindi gli stessi archivi sono accettati in entrambi i posti.
* Il caricamento è un singolo archivio `.zip` o `.plugin`, oppure un insieme di file singoli. Un archivio può racchiudere tutto in un'unica cartella di primo livello.
* Deve contenere esattamente un manifest, in `.claude-plugin/plugin.json`, che deve dichiarare un `name`. Un `SKILL.md` isolato senza manifest viene rifiutato.
* Un `SKILL.md` di primo livello il cui frontmatter dichiara componenti del plugin viene unito al manifest; `plugin.json` prevale ovunque entrambi impostino un valore.
* `name` può contenere lettere minuscole (di qualsiasi alfabeto), cifre e trattini, fino a 64 caratteri. Lettere maiuscole, spazi, trattini bassi e altra punteggiatura vengono rifiutati.
* `displayName` ha al massimo 64 caratteri e `description` al massimo 500.
* Ogni `SKILL.md` necessita di un frontmatter YAML valido con `name` e `description`, nessuno dei quali deve contenere tag XML come ``. Due skill, o due comandi, non possono condividere un nome.
* Nessun file può trovarsi in una directory `bin/` di primo livello.
* Nessun file `.zip` annidato. I server MCP pacchettizzati (`.mcpb`, `.dxt`) sono consentiti.
* I percorsi dei file devono essere relativi, non contenere `..` e usare solo lettere, cifre, spazi e `_ . - / ( ) ,`.
* Il corpo della richiesta e l'archivio non compresso hanno ciascuno un massimo di 200 MB; un corpo della richiesta oltre il limite restituisce `413` (`request_too_large`) anziché `400`. Un caricamento ha al massimo 5.000 file, una profondità di percorso di 12, percorsi di 472 caratteri e nomi di file o cartelle di 255 caratteri.
* Gli archivi ZIP devono usare la compressione DEFLATE o STORE, e non possono essere crittografati né contenere collegamenti simbolici.
* Un marketplace contiene al massimo 500 elementi, contando i suoi plugin e le eventuali skill autonome che i membri vi conservano. Questo limite e il limite di 5.000 file sono valori attuali che potrebbero essere aumentati.
## Flussi di lavoro di esempio
### Pubblicare ogni build da una pipeline di rilascio
Carica ogni build con tag dalla CI e lascia che sia la pipeline a decidere quando una build viene distribuita.
1. Trova il marketplace in cui caricare con `GET /v1/organizations/plugin_marketplaces?owner_type=organization`, oppure ometti `marketplace_id` per usare il marketplace della libreria.
2. Al primo rilascio, [crea il plugin](https://platform.claude.com/docs/it/manage-claude/plugins-api#create-a-plugin) con `POST /v1/organizations/plugins`. A ogni rilascio successivo, registra il `latest_version_id` del plugin, poi [carica una versione](https://platform.claude.com/docs/it/manage-claude/plugins-api#create-a-version) con `POST /v1/organizations/plugins/{plugin_id}/versions`. Se la risposta del caricamento va persa, leggi il plugin e riprova solo se `latest_version_id` è invariato (consulta [Ripetere i caricamenti](https://platform.claude.com/docs/it/manage-claude/plugins-api#retrying-uploads)).
3. Per mantenere i membri sulla versione corrente mentre ogni nuova build viene verificata, fissa il plugin una volta impostando `served_version_id` sulla sua versione corrente. Da quel momento ogni caricamento viene archiviato senza essere distribuito, e il fissaggio non può essere annullato: ogni build che vuoi distribuire richiede il passaggio 5.
4. Quando la scansione dei contenuti è attiva, interroga periodicamente `GET /v1/organizations/plugins/{plugin_id}/versions/{version}` finché `content_scan.status` non è più `processing`, e promuovi solo quando è `completed` con `pass` o `warn`.
5. [Promuovi la build](https://platform.claude.com/docs/it/manage-claude/plugins-api#change-the-served-version) con `POST /v1/organizations/plugins/{plugin_id}` e `{"served_version_id": ""}`. Per eseguire il rollback, invia allo stesso modo l'ID della versione precedente.
### Distribuire un plugin a un gruppo pilota, poi a tutti
1. Cerca l'ID del gruppo pilota con `GET /v1/organizations/rbac_groups`. Quella chiamata richiede lo scope `read:rbac_groups`, che richiede una chiave creata per tutte le organizzazioni collegate (consulta [Gestione utenti](https://platform.claude.com/docs/it/manage-claude/user-management#groups)). I passaggi successivi richiedono `write:plugins`, che agisce solo sull'organizzazione in cui è stata creata la sua chiave, quindi in un'azienda con diverse organizzazioni collegate, crea questa chiave nell'organizzazione che contiene il plugin e assegnale entrambi gli scope, oppure usa per quei passaggi una seconda chiave creata lì.
2. [Assegna al gruppo una propria impostazione](https://platform.claude.com/docs/it/manage-claude/plugins-api#set-an-installation-setting), ad esempio `auto_install`, con `POST /v1/organizations/plugins/{plugin_id}/installation_settings/{target}`, dove `{target}` è l'ID `rbac_group_` del gruppo, mentre il valore a livello di organizzazione resta `not_available`. Solo i membri del gruppo ottengono il plugin.
3. Al termine della fase pilota, imposta il valore a livello di organizzazione con la chiamata seguente, poi rimuovi l'impostazione del gruppo in modo che il gruppo segua di nuovo l'organizzazione. Impostare il valore a livello di organizzazione impedisce al plugin di ereditare il valore predefinito del suo marketplace; [rimuovere l'impostazione a livello di organizzazione](https://platform.claude.com/docs/it/manage-claude/plugins-api#remove-an-installation-setting) in seguito riporta il plugin a quel valore predefinito.
```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}"
```
Quindi rimuovi l'impostazione del gruppo con `DELETE /v1/organizations/plugins/{plugin_id}/installation_settings/{target}`, dove `{target}` è l'ID del gruppo. L'impostazione di un gruppo sostituisce il valore a livello di organizzazione per i suoi membri anziché aggiungersi a esso, quindi un'impostazione di gruppo residua pari a `available` manterrebbe quei membri su `available`.
### Mantenere sincronizzato un inventario di sicurezza
Esegui un job notturno che segnali i plugin che raggiungono risorse esterne alla sessione del membro o che non superano la scansione dei contenuti.
1. Scorri le pagine di [`GET /v1/organizations/plugins?limit=100`](https://platform.claude.com/docs/it/manage-claude/plugins-api#list-plugins) finché `next_page` non è `null` (consulta [Paginazione](https://platform.claude.com/docs/it/manage-claude/plugins-api#pagination)). Leggi `reach` e `content_scan` di ogni plugin da quell'elenco a ogni esecuzione: un verdetto di scansione che arriva in seguito non modifica `updated_at`. `updated_at` normalmente ti indica quali plugin hanno nuovi contenuti o una nuova versione distribuita dall'ultima esecuzione (vale la pena scaricare di nuovo l'archivio). Una versione in attesa (consulta [Versioni e versione distribuita](https://platform.claude.com/docs/it/manage-claude/plugins-api#versions-and-the-served-version)) modifica `updated_at` quando diventa la versione distribuita, non necessariamente quando viene archiviata. Per accorgertene, confronta `latest_version_id` con il valore della tua ultima esecuzione. Il nuovo elenco completo è anche ciò che rileva le rimozioni, perché un plugin rimosso da una sincronizzazione Git o dall'eliminazione di un account scompare senza un evento.
2. Segnala ogni plugin il cui `reach` è `remote` (dichiara un server MCP o una CLI), o il cui `content_scan.assessment` è `fail` o `unknown`. Questi campi descrivono la versione distribuita. Per verificare anche una versione più recente che non viene distribuita, elenca le versioni del plugin quando `latest_version_id` differisce da `served_version_id` (consulta [Elenca le versioni di un plugin](https://platform.claude.com/docs/it/manage-claude/plugins-api#list-a-plugins-versions)).
3. Per ogni plugin segnalato, scarica l'archivio della versione distribuita per la revisione con `GET /v1/organizations/plugins/{plugin_id}/versions/{served_version_id}/content` (consulta [Scarica i file di una versione](https://platform.claude.com/docs/it/manage-claude/plugins-api#download-a-versions-files)). Scarica anche, tramite il suo ID, qualsiasi versione non distribuita che soddisfi il criterio del passaggio 2.
4. Per sottrarre un plugin ai membri mentre lo esamini, consulta [Eliminare un plugin](https://platform.claude.com/docs/it/manage-claude/plugins-api#delete-a-plugin) per l'opzione reversibile (per i plugin di proprietà dell'organizzazione) e quella permanente.
## Plugin
L'oggetto plugin descrive un plugin in uno dei marketplace della tua organizzazione o nel marketplace personale di un membro (la risposta di [Avvio rapido](https://platform.claude.com/docs/it/manage-claude/plugins-api#quick-start) ne mostra uno completo). I suoi campi `display_name`, `description`, `manifest_version`, `content_scan`, `components` e `reach` descrivono la sua versione **distribuita**, quindi una sola chiamata di elenco mostra cosa viene distribuito ai membri.
| Campo | Descrizione |
| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Con prefisso `plugin_`. |
| `name` | Dal manifest. Univoco all'interno del suo marketplace, non nell'intera organizzazione. Fisso per un plugin di proprietà dell'organizzazione; cambia se un membro rinomina il proprio plugin in claude.ai. |
| `display_name`, `description`, `manifest_version` | I valori `displayName`, `description` e `version` del manifest della versione distribuita; ciascuno è `null` quando il manifest non lo dichiara. `manifest_version` è normalizzato per la visualizzazione: una `v` o `V` iniziale viene rimossa, quindi un `version` del manifest pari a `"v1.4.0"` viene restituito come `"1.4.0"`. È inoltre `null` per un valore che non sembra un numero di versione, come `"latest"`, e per una versione del plugin creata prima che claude.ai iniziasse a registrare questo campo ad agosto 2026. Un caricamento non viene mai rifiutato a causa del suo `version`, e `manifest_version` non è univoco. |
| `served_version_id`, `latest_version_id` | Con prefisso `pluginver_`: la versione distribuita ai membri e la versione più recente. Consulta [Versioni e versione distribuita](https://platform.claude.com/docs/it/manage-claude/plugins-api#versions-and-the-served-version). |
| `served_version_pinned` | `false` finché il plugin non viene fissato (consulta [Versioni e versione distribuita](https://platform.claude.com/docs/it/manage-claude/plugins-api#versions-and-the-served-version)); `true` da quel momento in poi. |
| `owner` | `{"type": "organization"}`, oppure `{"type": "user", "user_id": "user_..."}` per il marketplace personale di un membro. |
| `marketplace_id` | Con prefisso `marketplace_`. |
| `created_by` | Chi ha creato il plugin: `{"type": "user_actor", "user_id": "user_...", "email_address": "..."}` per una persona in claude.ai (`email_address` può essere `null`), oppure `{"type": "api_actor", "api_key_id": "apikey_..."}` per una chiave API. Potrebbero comparire altri tipi di attore. `null` quando non è registrato alcun creatore, ad esempio per i plugin sincronizzati da Git. |
| `organization_installation_preference`, `organization_installation_preference_inherited` | Per i plugin di proprietà dell'organizzazione: il valore a livello di organizzazione e se proviene dal valore predefinito del marketplace (consulta [Impostazioni di installazione](https://platform.claude.com/docs/it/manage-claude/plugins-api#installation-settings)). Per i plugin di proprietà di un membro: entrambi `null`. |
| `content_scan` | Il risultato della scansione della versione distribuita, un oggetto con `status`, `assessment` e `reason` (descritti dopo questa tabella). `null` quando non è mai stata scansionata. |
| `components` | I componenti della versione distribuita, ciascuno `{"type", "name", "description"}` con `type` uno tra `skill`, `mcp_server`, `command`, `agent`, `hook` o `cli`, elencati in quell'ordine di tipo e poi per nome. Per un server MCP, `name` è la sua chiave nel manifest; per un hook, l'evento su cui viene eseguito; per una CLI, il nome dell'eseguibile. `description` è sempre `null` per server MCP, hook e CLI. `null` quando non registrato. |
| `reach` | `contained`, `privileged` o `remote`. Consulta [Reach](https://platform.claude.com/docs/it/manage-claude/plugins-api#reach). |
| `updated_at` | Cambia quando cambia la versione distribuita, quando il plugin viene fissato e normalmente quando viene archiviata una nuova versione. Una versione in attesa (consulta [Versioni e versione distribuita](https://platform.claude.com/docs/it/manage-claude/plugins-api#versions-and-the-served-version)) lo modifica quando diventa la versione distribuita, non necessariamente quando viene archiviata. Non cambia per le impostazioni di installazione, le condivisioni o i nuovi risultati di scansione. |
L'oggetto `content_scan`:
| Campo | Descrizione |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | `processing` mentre la scansione è in corso, `completed` quando è terminata, oppure `errored` quando non è stato possibile completarla (o, occasionalmente, quando non è stato possibile leggerne il risultato per questa risposta, nel qual caso una lettura successiva potrebbe riportarlo). Ai membri non viene distribuita una versione la cui scansione è `processing` o `errored`; caricando di nuovo il contenuto come nuova versione si ottiene una nuova scansione. |
| `assessment` | Impostato quando `status` è `completed`: `pass` (nulla rilevato), `warn` (rilevato qualcosa che non blocca l'uso), `fail` (rilevato qualcosa che blocca l'uso) o `unknown` (nessun verdetto). Altrimenti `null`. |
| `reason` | Per `warn` e `fail`, il problema principale, tratto dall'elenco seguente. Altrimenti `null`, e `null` anche su una scansione meno recente, precedente alla registrazione dei motivi. |
| `reason` | Significato |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `covert-usage-telemetry` | Indica a Claude di inviare informazioni sul membro o sul suo utilizzo a un indirizzo esterno senza informarlo. |
| `undisclosed-data-destination` | Invia file, email, documenti o altri contenuti a una destinazione esterna fissa che non viene mostrata al membro e che il membro non controlla. |
| `remote-code-instruction-loader` | Indica a Claude di scaricare ed eseguire, o di seguire istruzioni provenienti da, contenuti esterni che possono cambiare dopo l'installazione del plugin. |
| `credential-exposure` | Contiene credenziali attive, o raccoglie credenziali o token dall'ambiente del membro. |
| `guardrail-tampering` | Indebolisce le protezioni del membro, ad esempio pre-approvando ogni richiesta di autorizzazione. |
| `system-prompt-spoofing` | Imita o tenta di sostituire le istruzioni di sistema di Claude. |
| `covert-record-tampering` | Modifica, nasconde o elimina silenziosamente informazioni che il membro altrimenti vedrebbe. |
| `covert-behavior-override` | Modifica il comportamento di Claude oltre lo scopo del plugin e nasconde la modifica al membro. |
| `hidden-code-execution` | Esegue codice incluso dicendo a Claude di non rivelare cosa fa. |
| `undisclosed-promotion-injection` | Inserisce contenuti promozionali non dichiarati nell'output di Claude. |
| `hidden-identity-gate` | Modifica o interrompe il proprio comportamento a seconda dell'account che lo esegue, senza spiegarne il motivo. |
| `destructive-persistence` | Può eliminare o danneggiare i file del membro, o installare programmi che rimangono dopo il plugin. |
| `unanalyzable-binary` | Include un programma compilato o illeggibile, quindi la scansione non ha potuto verificare cosa fa. |
| `other` | Qualsiasi altro problema, incluso uno più recente di questo elenco. |
Un `plugin_id` privo del prefisso `plugin_` restituisce `400`. Un `plugin_id` che ha il prefisso ma non viene risolto, appartiene a un'altra organizzazione o si riferisce a una skill autonoma restituisce `404`.
### Elencare i plugin
`GET /v1/organizations/plugins` elenca ogni plugin nella tua organizzazione, nei marketplace dell'organizzazione e nei marketplace personali dei membri, ordinati per `created_at` in ordine decrescente. Filtra per `owner_type` (`organization` o `user`), `owner_user_id` (con prefisso `user_`; i plugin di un membro, anche dopo che il membro ha lasciato l'organizzazione), `marketplace_id` e `created_at[gte]`, `created_at[gt]`, `created_at[lte]`, `created_at[lt]` (timestamp RFC 3339). I filtri si combinano con AND. Un `marketplace_id` o `owner_user_id` che non corrisponde a nulla nella tua organizzazione restituisce una pagina vuota, non un errore. La risposta ha la forma mostrata in [Avvio rapido](https://platform.claude.com/docs/it/manage-claude/plugins-api#quick-start). Richiede lo scope `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)
# Recupera automaticamente altre pagine quando necessario.
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,
);
// Solo questa pagina; per la successiva, richiama list() con 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
```
### Crea un plugin
`POST /v1/organizations/plugins` crea un plugin di proprietà dell'organizzazione e la sua prima versione in un'unica chiamata; la versione diventa la "served version" (versione servita). Il corpo è `multipart/form-data`: `files[]` è un singolo archivio `.zip` o `.plugin`, oppure una parte per file, dove il nome file di ciascuna parte è il percorso del file all'interno del plugin (ad esempio `.claude-plugin/plugin.json`). I campi facoltativi sono `marketplace_id` (un marketplace `manual` di proprietà dell'organizzazione; per impostazione predefinita è il marketplace della tua libreria, che viene creato al primo utilizzo) e `release_notes` (fino a 5.000 caratteri, mostrate nella cronologia delle versioni di claude.ai e restituite sulla versione). I campi `name`, `display_name`, `description` e `manifest_version` del plugin provengono dal manifest caricato, e il caricamento deve soddisfare i [requisiti di caricamento](https://platform.claude.com/docs/it/manage-claude/plugins-api#upload-requirements). Quando la "content scanning" (scansione dei contenuti) è attiva, il campo `content_scan.status` della risposta è `processing` e il verdetto arriva in modo asincrono. Restituisce il plugin. Richiede lo "scope" (ambito) `write:plugins`.
Carica un archivio:
```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();
// Costruisci a mano la parte `files[]` così l'archivio viene inviato con il suo nome file,
// come richiesto dal caricamento.
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"
}
```
Carica singoli file in un marketplace specifico. Allega ciascun file con il suo percorso all'interno del plugin (il suffisso `;filename=` nell'esempio cURL, gli argomenti del nome file negli esempi degli SDK); un file inviato con il solo nome di base fa sì che il manifest non venga trovato. Gli SDK TypeScript e Java e la CLI `ant` non possono ancora allegare file con un percorso, quindi quegli esempi caricano invece il plugin come un unico archivio nel 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
# La CLI invia ogni file solo con il suo nome base,
# quindi carica il plugin come un unico archivio.
ant beta:organization:plugins create \
--file dist/sales-toolkit.zip \
--marketplace-id marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r
```
```python Python
client = anthropic.Anthropic()
# Una tupla (filename, file) mantiene il percorso di ogni file nel plugin;
# un oggetto file semplice verrebbe inviato solo con il suo 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();
// L'SDK TypeScript invia ogni file con il suo nome base,
// quindi carica il plugin come un unico archivio.
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 mantiene il percorso di ogni file all'interno del plugin; senza di esso, un FileStream
// viene inviato solo con il suo 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 mantiene il percorso di ogni file nel plugin come filename della parte;
// un *os.File semplice verrebbe inviato col solo nome base e il manifest non verrebbe trovato.
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();
// I setter `files` su PluginCreateParams accettano un solo nome file per l'intera
// lista, quindi carica il plugin come un unico archivio: una singola parte costruita
// a mano che riporta il nome file dell'archivio, richiesto dal caricamento.
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
# Un FilePart con filename: mantiene il percorso di ogni file nel plugin;
# un Pathname semplice verrebbe inviato solo con il suo 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}"
```
Oltre a un `400` per un caricamento che viola i [requisiti di caricamento](https://platform.claude.com/docs/it/manage-claude/plugins-api#upload-requirements) (`413` per un corpo della richiesta superiore a 200 MB) e alle risposte comuni (un `403` quando `marketplace_id` è il marketplace personale di un membro; consulta [Risposte di errore](https://platform.claude.com/docs/it/manage-claude/plugins-api#error-responses)), una creazione può non riuscire con:
| Stato | Causa | Cosa fare |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 404 | `marketplace_id` non è un marketplace della tua organizzazione. | Prendi l'ID da [Elenca i marketplace](https://platform.claude.com/docs/it/manage-claude/plugins-api#list-marketplaces). |
| 400 | Il marketplace è sincronizzato da Git, oppure contiene già 500 plugin e skill. | Carica in un marketplace `manual`, oppure modifica invece il repository. |
| 409 `plugin_name_taken` | Il nome è già in uso in quel marketplace. | Prosegui con `details.plugin_id` (caricandovi una versione), oppure modifica il `name` del manifest. |
| 409 `skill_name_taken` | Il plugin sta per essere inserito nel marketplace della libreria e una delle sue skill ha il nome di una skill dell'organizzazione. | Rinomina la skill, oppure rimuovi la skill dell'organizzazione in claude.ai. |
| 409 (nessun `error_code`) | Un altro caricamento con lo stesso nome nello stesso marketplace è ancora in corso. | Riprova a breve. |
| 503 `registration_pending` | Il plugin è stato creato ma la sua registrazione non è stata completata. | Non inviare di nuovo la richiesta; carica gli stessi file come versione di `details.plugin_id` (consulta [Ripetere i caricamenti](https://platform.claude.com/docs/it/manage-claude/plugins-api#retrying-uploads)). |
### Ottieni un plugin
`GET /v1/organizations/plugins/{plugin_id}` restituisce un plugin. Richiede lo scope `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}"
```
### Modifica la versione servita
`POST /v1/organizations/plugins/{plugin_id}` modifica quale versione di un plugin di proprietà dell'organizzazione viene servita ai membri. Passa una versione precedente per eseguire un rollback, oppure una più recente per promuovere una build che era stata archiviata senza essere servita. Questo fissa il plugin, e un plugin fissato attualmente non può essere sbloccato, né qui né in claude.ai (consulta [Versioni e versione distribuita](https://platform.claude.com/docs/it/manage-claude/plugins-api#versions-and-the-served-version)). L'unico campo aggiornabile è `served_version_id`, ed è obbligatorio. La modifica raggiunge i membri prima che la risposta venga restituita e non crea una versione. Quando la scansione dei contenuti è attiva, la versione deve essere una che può essere servita ai membri (consulta [Scansione dei contenuti](https://platform.claude.com/docs/it/manage-claude/plugins-api#content-scanning)). Passare la versione già servita su un plugin fissato non cambia nulla; passarla su un plugin non fissato lo fissa su di essa, quindi i caricamenti successivi smettono di essere serviti automaticamente. Il fissaggio pone fine anche a qualsiasi attesa: una versione che era in attesa della sua scansione dei contenuti rimane archiviata e viene servita solo se qualcuno la sceglie. Restituisce il plugin. Richiede lo scope `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"
}
```
Oltre alle risposte comuni (un `403` per un plugin di proprietà di un membro, e `409 scan_pending` o `400 scan_failed` per una versione che non può essere servita ai membri; consulta [Risposte di errore](https://platform.claude.com/docs/it/manage-claude/plugins-api#error-responses)), la richiesta può non riuscire con:
| Stato | Causa | Cosa fare |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | Il corpo omette `served_version_id`, lo imposta su `null` o contiene qualsiasi altro campo; oppure il valore non ha il prefisso `pluginver_` o è `latest`. | Invia esattamente `{"served_version_id": "pluginver_…"}`. |
| 404 | `served_version_id` non è una versione di questo plugin. | Prendi l'ID da [Elenca le versioni di un plugin](https://platform.claude.com/docs/it/manage-claude/plugins-api#list-a-plugins-versions). |
| 409 (nessun `error_code`) | Un caricamento su questo plugin o un'altra modifica della versione servita è ancora in corso. | Riprova a breve. |
| 409 `skill_name_taken` | Il plugin si trova nel marketplace della libreria e la versione contiene una skill il cui nome è ora usato da una skill dell'organizzazione. | Scegli un'altra versione, oppure rinomina una delle skill. |
### Elimina un plugin
`DELETE /v1/organizations/plugins/{plugin_id}` elimina definitivamente un plugin e tutte le versioni che contiene, esattamente come fa l'eliminazione da parte di un amministratore in claude.ai. Funziona su qualsiasi plugin in un marketplace `manual`, incluso il plugin di un membro, anche se quel membro ha nel frattempo lasciato l'organizzazione. Quando l'eliminazione restituisce una risposta, il plugin, le sue versioni e i relativi file non compaiono più in nessuna lettura, e il plugin non viene più servito ai membri. Le impostazioni di installazione di un plugin di proprietà dell'organizzazione vengono rimosse insieme a esso; le condivisioni di un plugin di proprietà di un membro vengono revocate, e il plugin scompare anche per il suo proprietario. Un plugin in un marketplace sincronizzato da Git restituisce `400`: rimuovilo dal repository, oppure rimuovi il marketplace in claude.ai. Richiede lo scope `write:plugins`.
L'eliminazione non può essere annullata e non esiste un'eliminazione per singola versione. Per nascondere invece in modo reversibile un plugin di proprietà dell'organizzazione, imposta la sua impostazione di installazione a livello di organizzazione su `not_available` (un plugin che ereditava il valore predefinito del suo marketplace ottiene un'impostazione propria, e [rimuovere quell'impostazione a livello di organizzazione](https://platform.claude.com/docs/it/manage-claude/plugins-api#remove-an-installation-setting) in seguito riporta il plugin al valore predefinito), e rimuovi (o imposta su `not_available`) ogni impostazione di gruppo elencata da `GET /v1/organizations/plugins/{plugin_id}/installation_settings`, perché l'impostazione di un gruppo sovrascrive il valore a livello di organizzazione per i suoi membri. Invia queste scritture una dopo l'altra, non in parallelo (consulta [Imposta un'impostazione di installazione](https://platform.claude.com/docs/it/manage-claude/plugins-api#set-an-installation-setting)). Un plugin di proprietà di un membro non può essere nascosto tramite questa API se non eliminandolo, e solo se il suo marketplace è `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" }
```
## Versioni dei plugin
Una versione di un plugin è uno "snapshot" (istantanea) immutabile dei file di un plugin provenienti da un singolo caricamento (la risposta di [Crea una versione](https://platform.claude.com/docs/it/manage-claude/plugins-api#create-a-version) mostra un oggetto completo). I suoi campi rispecchiano i campi della versione servita del plugin (`display_name`, `description`, `manifest_version`, `content_scan`, `components`, `reach`) per questa versione, più `release_notes` (come fornite con il caricamento; mostrate nella cronologia delle versioni di claude.ai) e `created_by` (chi l'ha caricata).
Un `{version}` privo del prefisso `pluginver_` restituisce `400` (tranne il valore letterale `latest` dove indicato). Uno che ha il prefisso ma non identifica una versione di quel plugin restituisce `404`.
### Elenca le versioni di un plugin
`GET /v1/organizations/plugins/{plugin_id}/versions` elenca le versioni di un plugin, ordinate per `created_at` in ordine decrescente; il primo elemento è la versione identificata da `latest_version_id`. `limit` va da 1 a 1.000. Richiede lo scope `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
)
# Recupera automaticamente altre pagine quando necessario.
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,
);
// Solo questa pagina; per la successiva, chiama di nuovo list() con 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
```
### Crea una versione
`POST /v1/organizations/plugins/{plugin_id}/versions` aggiunge una versione a un plugin di proprietà dell'organizzazione in un marketplace `manual`. Il corpo è `multipart/form-data`, con gli stessi campi `files[]` e `release_notes`, gli stessi [requisiti di caricamento](https://platform.claude.com/docs/it/manage-claude/plugins-api#upload-requirements) e gli stessi errori relativi a file, manifest, archivio e dimensioni di [Crea un plugin](https://platform.claude.com/docs/it/manage-claude/plugins-api#create-a-plugin). Il nome caricato (il `name` del manifest) deve essere uguale al `name` del plugin. Se il plugin non è fissato, la nuova versione viene normalmente servita non appena viene archiviata; se è fissato, la versione viene archiviata ma non servita finché non modifichi la versione servita impostandola su di essa. Per verificarlo, confronta l'`id` della risposta con il `served_version_id` del plugin. Restituisce la versione. Richiede lo scope `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();
// Costruisci a mano la parte `files[]` così l'archivio viene inviato con il suo nome file,
// come richiesto dal caricamento.
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"
}
```
Oltre a un `400` per un caricamento che viola i [requisiti di caricamento](https://platform.claude.com/docs/it/manage-claude/plugins-api#upload-requirements) (`413` per un corpo della richiesta superiore a 200 MB) e alle risposte comuni (un `403` per un plugin di proprietà di un membro; consulta [Risposte di errore](https://platform.claude.com/docs/it/manage-claude/plugins-api#error-responses)), la richiesta può non riuscire con:
| Stato | Causa | Cosa fare |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | Il plugin si trova in un marketplace sincronizzato da Git, oppure il nome caricato è diverso da quello del plugin. | Modifica invece il repository, oppure correggi il `name` del manifest. |
| 409 (nessun `error_code`) | Un altro caricamento su questo plugin, o una modifica della versione servita, è ancora in corso. | Riprova a breve. |
| 409 `skill_name_taken` | Il plugin si trova nel marketplace della libreria e la versione aggiunge una skill con il nome di una skill dell'organizzazione. | Rinomina la skill, oppure rimuovi la skill dell'organizzazione in claude.ai. |
| 503 `registration_pending` | La versione è stata archiviata ma la sua registrazione non è stata completata. | Invia di nuovo la stessa richiesta quando la risposta contiene `x-should-retry: true` (consulta [Ripetere i caricamenti](https://platform.claude.com/docs/it/manage-claude/plugins-api#retrying-uploads)). |
### Ottieni una versione
`GET /v1/organizations/plugins/{plugin_id}/versions/{version}` restituisce una versione. `{version}` è un ID di versione, oppure `latest` per la versione identificata da `latest_version_id` al momento della richiesta. Richiede lo scope `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}"
```
### Scarica i file di una versione
`GET /v1/organizations/plugins/{plugin_id}/versions/{version}/content` scarica i file di una versione come archivio `.zip` archiviato (`Content-Type: application/zip`). L'archivio viene restituito indipendentemente dal risultato della scansione dei contenuti, così puoi ispezionare le versioni nascoste ai membri. Viene servito esattamente come è stato archiviato, quindi per un plugin di proprietà dell'organizzazione in un marketplace `manual` puoi ricaricarlo senza modifiche come nuova versione, a condizione che soddisfi gli attuali requisiti di caricamento. `{version}` deve essere un ID di versione, non `latest`: leggi prima il `served_version_id` o il `latest_version_id` del plugin, oppure risolvi `latest` con `GET /v1/organizations/plugins/{plugin_id}/versions/latest`. Il nome file in `Content-Disposition` deriva dal nome del plugin e non è univoco; assegna ai file salvati un nome basato sull'ID del plugin e della versione. Richiede lo scope `read:plugins`.
Il download dell'archivio di un plugin **di proprietà di un membro** registra un evento `claude_plugin_archive_accessed` nell'Activity Feed della Compliance API, che identifica tramite ID la chiave (come `api_actor`), il plugin e il suo marketplace, la versione e il membro proprietario; non contiene nomi. Il download dell'archivio di un plugin di proprietà dell'organizzazione non registra nulla.
```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() restituirebbe l'intero archivio come un'unica stringa, quindi prendi la
// risposta grezza e copiane il corpo su disco a blocchi.
$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)
# L'SDK restituisce l'archivio già letto in memoria, come StringIO.
File.binwrite("#{plugin_id}_#{version_id}.zip", archive.string)
```
## Impostazioni di installazione dei plugin
Questi endpoint si applicano ai plugin di proprietà dell'organizzazione. Restituiscono `404` per un plugin di proprietà di un membro, che ha invece delle [condivisioni](https://platform.claude.com/docs/it/manage-claude/plugins-api#plugin-shares). `{target}` è il valore letterale `organization` per l'impostazione a livello di organizzazione del plugin, oppure l'ID `rbac_group_` di un gruppo per l'impostazione di quel gruppo; qualsiasi altro valore restituisce `400`. Gli ID dei gruppi provengono da `GET /v1/organizations/rbac_groups` (scope `read:rbac_groups`; consulta [Gestione degli utenti](https://platform.claude.com/docs/it/manage-claude/user-management#groups)). Un'impostazione non ha un proprio `id`: viene indirizzata tramite `(plugin_id, target)`, e su di essa non viene registrato alcun attore (l'attore si trova nel relativo evento di attività `plugin_installation_preference_updated`).
### Elenca le impostazioni di installazione di un plugin
`GET /v1/organizations/plugins/{plugin_id}/installation_settings` elenca le impostazioni di un plugin di proprietà dell'organizzazione, ordinate per `created_at` in ordine decrescente: la sua impostazione a livello di organizzazione (assente finché eredita il valore predefinito del suo marketplace) e l'impostazione di ciascun gruppo. Filtra per `target_type` (`organization` o `rbac_group`). Richiede lo scope `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"
)
# Recupera automaticamente altre pagine quando necessario.
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',
);
// Solo questa pagina; per la successiva, chiama di nuovo list() con 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
```
### Imposta un'impostazione di installazione
`POST /v1/organizations/plugins/{plugin_id}/installation_settings/{target}` imposta l'impostazione di installazione di un target per un plugin di proprietà dell'organizzazione, creandola o modificando il valore che ha già. L'unico campo del corpo è `installation_preference` (`required`, `auto_install`, `available` o `not_available`), ed è obbligatorio. Impostare il valore che il target ha già non cambia nulla. Impostare il target `organization` fa sì che il plugin smetta di ereditare il valore predefinito del suo marketplace (`organization_installation_preference_inherited` diventa `false`), anche quando il valore è uguale a quello predefinito, quindi il plugin non segue più le modifiche successive al valore predefinito del marketplace. Per riportare il plugin al valore predefinito del suo marketplace, [rimuovi l'impostazione a livello di organizzazione](https://platform.claude.com/docs/it/manage-claude/plugins-api#remove-an-installation-setting); le impostazioni di gruppo non vengono modificate. Un target di gruppo deve essere un gruppo che la tua organizzazione può vedere in `GET /v1/organizations/rbac_groups`, altrimenti la richiesta restituisce `404`. La modifica non altera l'`updated_at` del plugin; viene registrata nell'Activity Feed. Restituisce l'impostazione. Richiede lo scope `write:plugins`.
Invia le scritture delle impostazioni di installazione di un plugin una alla volta. Se più scritture per lo stesso plugin arrivano contemporaneamente, il server le gestisce una dopo l'altra e può rispondere ad alcune di esse con `503` invece di applicarle. Quel `503` contiene `x-should-retry: true`, e la scrittura può essere ripetuta in sicurezza: attendi un secondo o due, quindi inviala di nuovo.
```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"
}
```
### Rimuovi un'impostazione di installazione
`DELETE /v1/organizations/plugins/{plugin_id}/installation_settings/{target}` rimuove l'impostazione di installazione di un target per un plugin di proprietà dell'organizzazione. Con `{target}` uguale a `organization` rimuove l'impostazione a livello di organizzazione del plugin. Il plugin eredita quindi di nuovo il valore predefinito del suo marketplace (`organization_installation_preference_inherited` diventa `true`) e segue le modifiche successive a quel valore predefinito; le impostazioni di gruppo non vengono modificate. Con l'ID `rbac_group_` di un gruppo rimuove l'impostazione di quel gruppo: i membri del gruppo ricadono sul valore a livello di organizzazione, o sull'impostazione di un altro dei loro gruppi. Un target che non ha un'impostazione propria restituisce `404`; ciò include il target `organization` di un plugin che eredita già il valore predefinito del suo marketplace. La modifica non altera l'`updated_at` del plugin; viene registrata nell'Activity Feed. La risposta contiene la chiave composita al posto di un `id`; per il target `organization` il suo `target` è `{"type": "organization"}`. Richiede lo scope `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" }
}
```
## Condivisioni dei plugin
Le condivisioni esistono solo sui plugin di proprietà dei membri e sono di sola lettura in questa API (consulta [Condivisioni](https://platform.claude.com/docs/it/manage-claude/plugins-api#shares)).
### Elenca le condivisioni di un plugin
`GET /v1/organizations/plugins/{plugin_id}/shares` elenca con chi il proprietario di un plugin di proprietà di un membro lo ha condiviso, in ordine decrescente per `granted_at`: tutti i membri (`organization`), un gruppo (`rbac_group`) o un membro specifico (`organization_member`). Filtra per `target_type`. Un plugin che il suo proprietario non ha condiviso restituisce un elenco vuoto; un plugin di proprietà dell'organizzazione restituisce `404`. Le condivisioni sono di sola lettura in questa API, e una condivisione elencata concede l'accesso solo finché quel tipo di condivisione è attivato per la tua organizzazione in claude.ai (consulta [Condivisioni](https://platform.claude.com/docs/it/manage-claude/plugins-api#shares)). `granted_at` indica quando è stata concessa la condivisione; se il proprietario modifica successivamente la condivisione in claude.ai, indica il momento di tale modifica. Richiede lo scope `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")
# Recupera automaticamente altre pagine quando necessario.
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',
);
// Solo questa pagina; per la successiva, richiama list() con 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
}
```
## Marketplace dei plugin
Questa API legge i [marketplace](https://platform.claude.com/docs/it/manage-claude/plugins-api#marketplaces) e imposta l'impostazione di installazione predefinita di un marketplace dell'organizzazione; i marketplace stessi vengono creati, collegati a un repository ed eliminati in 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 | Descrizione |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Il nome del marketplace. Fisso per tutta la sua durata. |
| `owner` | Stessa struttura del plugin. |
| `source` | `manual`, `github`, `gitlab` o `public_git`. Consulta [Marketplace](https://platform.claude.com/docs/it/manage-claude/plugins-api#marketplaces). |
| `sync_status` | Esito della sincronizzazione più recente: `success`, `in_progress`, `failed_content`, `failed_transient`, `failed_auth` o `failed_limits`. `null` finché non viene tentata una prima sincronizzazione, cosa che non avviene mai per un marketplace la cui origine è `manual`. |
| `last_sync_ended_at` | Quando è terminato il tentativo di sincronizzazione più recente, qualunque sia stato il suo esito; per un repository collegato che non è ancora stato sincronizzato, quando è stato creato il marketplace. `null` per un marketplace che non è sincronizzato. |
| `last_sync_read_sha` | Il commit che l'ultima sincronizzazione ha letto dal repository. Non è necessariamente il commit da cui provengono le versioni servite. `null` per un marketplace che non è sincronizzato. |
| `default_installation_preference` | Marketplace dell'organizzazione: il valore a livello di organizzazione per ogni plugin al suo interno privo di un'impostazione propria (`not_available` se mai impostato). Marketplace personali: `null`. |
Un `marketplace_id` privo del prefisso `marketplace_` restituisce `400`. Uno che ha il prefisso ma non viene risolto, o che appartiene a un'altra organizzazione, restituisce `404`.
### Elenca i marketplace
`GET /v1/organizations/plugin_marketplaces` elenca i marketplace della tua organizzazione e i marketplace personali dei membri, ordinati per `created_at` in ordine decrescente. Usalo per trovare l'ID di un marketplace, per filtrare l'elenco dei plugin in base a esso o per caricarvi contenuti, prima che contenga qualsiasi plugin. Il marketplace della libreria compare non appena vi viene creato qualcosa per la prima volta, in claude.ai o tramite questa API. Filtra per `owner_type` (`organization` o `user`) e `source`. `limit` va da 1 a 1.000. Richiede lo scope `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"
)
# Recupera automaticamente altre pagine quando necessario.
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,
);
// Solo questa pagina; per la successiva, chiama di nuovo list() con 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
```
### Ottieni un marketplace
`GET /v1/organizations/plugin_marketplaces/{marketplace_id}` restituisce un marketplace. Richiede lo scope `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}"
```
### Imposta l'impostazione di installazione predefinita di un marketplace
`POST /v1/organizations/plugin_marketplaces/{marketplace_id}` imposta l'impostazione di installazione predefinita di un marketplace di proprietà dell'organizzazione. Ogni plugin nel marketplace privo di una propria impostazione a livello di organizzazione riporta questo valore predefinito come sua `organization_installation_preference`, inclusi i plugin aggiunti in seguito. Funziona per i marketplace `manual` e per quelli sincronizzati; il marketplace personale di un membro restituisce `403`. L'unico campo aggiornabile è `default_installation_preference`, ed è obbligatorio. Non può essere reimpostato su `null`: una volta che un marketplace ha un valore predefinito, lo mantiene, come in claude.ai. Una modifica viene registrata come un singolo evento `marketplace_updated` senza eventi per singolo plugin, e non altera l'`updated_at` di alcun plugin. Impostare il valore già impostato non modifica nulla, con un'eccezione: un marketplace il cui valore predefinito non è mai stato impostato riporta `not_available` ma non contiene alcuna impostazione, quindi la sua prima scrittura (anche `not_available`) conta come una modifica. Restituisce il marketplace. Richiede lo scope `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}"
```
### Convalida il contenuto di un marketplace
Due endpoint riportano cosa farebbe una sincronizzazione del contenuto del marketplace indicato, senza collegare né archiviare nulla: `POST /v1/organizations/plugin_marketplaces/validate_repository` legge un repository GitHub pubblico, e `POST /v1/organizations/plugin_marketplaces/validate_archive` legge un `.zip` della directory del marketplace che carichi tu. Entrambi restituiscono lo stesso report: se `marketplace.json` è ben formato, quali plugin verrebbero saltati e perché, e quali plugin verrebbero sincronizzati con alcuni contenuti esclusi. I controlli sono quelli eseguiti da una sincronizzazione reale. I problemi relativi al contenuto vengono restituiti nel report, non come errori HTTP: la richiesta riesce con `valid: false`, anche quando il repository o l'archivio non possono essere letti affatto. Una convalida conta come una lettura, e i due endpoint insieme sono inoltre limitati a 10 convalide al minuto per organizzazione (consulta [Limitazione della velocità](https://platform.claude.com/docs/it/manage-claude/plugins-api#rate-limiting)); non registrano nulla nell'Activity Feed. Una convalida può richiedere fino a 120 secondi prima di restituire una risposta, quindi imposta il timeout del tuo client su un valore superiore. Entrambi gli endpoint richiedono lo scope `read:plugins` o `write:plugins` (`read:org_audit` e `read:compliance_org_data` non li concedono).
Il repository, e qualsiasi origine di plugin esterna a esso su GitHub, vengono letti in modo anonimo, quindi un repository privato o un'origine di plugin privata viene segnalato come non trovato. Le origini di plugin su host diversi da GitHub non vengono recuperate; un plugin di questo tipo riceve normalmente un avviso `marketplace_validate_source_not_checked` e viene controllato quando il marketplace viene effettivamente sincronizzato. Se il repository è, o l'archivio indica, un marketplace che Anthropic sincronizza in ogni organizzazione, si applicano regole più rigide: ogni origine di plugin esterna al marketplace deve essere fissata a uno SHA di commit completo, le origini non fissate o su host non supportati vengono segnalate come errori del plugin, e il branch letto per impostazione predefinita è quello da cui quel marketplace si sincronizza.
`validate_repository` accetta un corpo JSON con due campi: `repository_url`, l'URL `https://` di un repository pubblico su github.com (obbligatorio), e `ref`, un nome di branch o uno SHA di commit completo di 40 caratteri (facoltativo; quando è omesso o `null`, viene usato il branch che leggerebbe una sincronizzazione, di solito il branch predefinito del repository). `validate_archive` accetta `multipart/form-data` con esattamente una parte, `archive`, inviata come parte file con un nome file: un `.zip` della directory del marketplace, di al massimo 32 MB, con il contenuto nella radice o racchiuso in una cartella (come produce il download da un host Git), solo con compressione DEFLATE o STORE. Non è accettato nessun altro campo del modulo.
Convalida un repository pubblico su un 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 | Descrizione |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `valid` | `true` quando `marketplace.json` è ben formato e nessun plugin verrebbe saltato. Gli avvisi non lo rendono `false`. |
| `ref` | Il branch che è stato letto, per nome; `null` quando non è stato indicato alcun branch ed è stato letto il branch predefinito, per uno SHA di commit o per un archivio. |
| `commit_sha` | Il commit che è stato convalidato. Per un archivio scaricato da un host Git, il commit che l'host ha registrato nel campo commento del file ZIP, se presente (non verificato). |
| `total_plugin_count` | Quanti plugin dichiara `marketplace.json`; `0` quando non è stato possibile leggerlo. |
| `manifest_error`, `manifest_error_code` | Impostati quando non è stato possibile convalidare nulla: l'origine non poteva essere letta, oppure `marketplace.json` è mancante, malformato o supera un limite. Una convalida che non è terminata entro 120 secondi riporta `manifest_error_code: "marketplace_validate_deadline_exceeded"`. |
| `plugin_errors` | Un `{name, error, error_code}` per ogni plugin che una sincronizzazione salterebbe. |
| `plugin_warnings` | Un `{name, warnings: [{message, error_code}]}` per ogni plugin che verrebbe sincronizzato con alcuni contenuti esclusi. |
Convalida invece una copia locale della directory del marketplace, come `.zip`; la risposta è lo stesso report:
```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();
// Passa un Path così la parte `archive` viene inviata con un nome file, richiesto da questo 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}"
```
I problemi relativi al contenuto non fanno mai fallire la richiesta. A parte le risposte comuni a tutti gli endpoint (un `403` per una chiave che ha solo `read:org_audit` o `read:compliance_org_data`; consulta [Risposte di errore](https://platform.claude.com/docs/it/manage-claude/plugins-api#error-responses) e [Limitazione della velocità](https://platform.claude.com/docs/it/manage-claude/plugins-api#rate-limiting)), la richiesta stessa può non riuscire con:
| Stato | Causa | Cosa fare |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| 400 | Su `validate_repository`: il corpo non è un oggetto JSON; `repository_url` è mancante, è più lungo di 2.048 caratteri, contiene credenziali o non è nel formato `https://github.com/{owner}/{repo}` (un suffisso `.git` è accettato; un altro host, un percorso più lungo come `/tree/main` della pagina di un branch, o una porta diversa da 443 o 80 non lo sono); `ref` è vuoto, è più lungo di 255 caratteri, contiene `..` o contiene un carattere diverso da lettere ASCII, cifre, `.`, `_`, `-`, `+` e `/`; oppure è presente un altro campo. Un `ref` che supera questi controlli ma indica un branch che il repository non ha non viene rifiutato: la richiesta riesce con `valid: false` e `manifest_error` indica che il branch non è stato trovato. Su `validate_archive`: il corpo non è `multipart/form-data`, la parte `archive` è mancante, ripetuta o non inviata come parte file con un nome file, oppure è presente un altro campo del modulo. | Correggi la richiesta e inviala di nuovo. |
| 413 | Su `validate_archive`: la parte `archive`, o la lunghezza del corpo dichiarata dalla richiesta, supera 32 MB. | Convalida invece il repository tramite URL, oppure riduci l'archivio. |
#### Codici del report
Ogni risultato in un report ha un codice stabile: `manifest_error_code` quando non è stato possibile convalidare nulla, `error_code` su ogni voce di `plugin_errors` ed `error_code` su ogni avviso. Quando un plugin presenta più problemi, `error_code` è quello del primo ed `error` unisce i relativi messaggi. Potrebbero essere aggiunti nuovi codici; un `manifest_error_code` non riconosciuto significa comunque che il contenuto non è stato convalidato, uno su una voce di `plugin_errors` significa comunque che il plugin verrebbe saltato, e uno su un avviso significa comunque che il plugin verrebbe sincronizzato. Questi codici indicano condizioni transitorie, quindi la stessa richiesta potrebbe riuscire in seguito: `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, di solito, `marketplace_validate_deadline_exceeded`.
## Valori non riconosciuti
Ogni valore stringa in questa pagina (tipi di componenti, `reach`, campi di scansione, `source` del marketplace, codici di errore) può acquisire nuovi valori in qualsiasi momento. Tratta un valore che non riconosci come faresti con qualsiasi stringa sconosciuta, anziché generare un errore.
## Limitazione della velocità
Le richieste di lettura (ogni endpoint `GET` in questa pagina) condividono un "rate limit" (limite di velocità) di **300 richieste al minuto** per organizzazione, e le richieste di scrittura (creazione di un plugin o di una versione, modifica della versione servita, eliminazione, impostazione o rimozione di un'impostazione di installazione e aggiornamento di un marketplace) condividono un limite di **60 richieste al minuto** per organizzazione. Una convalida di marketplace (con uno qualsiasi dei due endpoint) conta come una lettura, e le convalide sono inoltre limitate a 10 al minuto per organizzazione su entrambi gli endpoint; entrambi i limiti vengono verificati prima che venga letto il corpo della richiesta. Questi limiti vengono conteggiati su tutte le chiavi della tua organizzazione e sono separati dagli altri limiti dell'Admin API della tua organizzazione. Le richieste che superano un limite restituiscono **429 Too Many Requests** con un header `retry-after`. Le risposte includono gli header `anthropic-ratelimit-requests-*` per il limite applicabile (sulla convalida di marketplace, il suo limite di 10 al minuto; su un `429`, il limite che ha rifiutato la richiesta).
Un caricamento, una modifica della versione servita o una convalida possono anche restituire `429` con `retry-after` quando il servizio non ha momentaneamente capacità per un'altra operazione, e un caricamento restituisce `429` quando la tua organizzazione ha superato la propria frequenza di scansione dei contenuti. Gestisci tutti questi casi allo stesso modo: attendi il tempo indicato da `retry-after`, quindi riprova. Indipendentemente da questi limiti, invia le scritture delle impostazioni di installazione per lo stesso plugin una alla volta: quando ne arrivano diverse contemporaneamente, ad alcune può essere risposto con `503` e `x-should-retry: true`, e queste possono essere inviate di nuovo in sicurezza dopo un secondo o due (consulta [Imposta un'impostazione di installazione](https://platform.claude.com/docs/it/manage-claude/plugins-api#set-an-installation-setting)).
## Paginazione
Gli endpoint di elenco utilizzano un **"opaque cursor" (cursore opaco)**. La prima richiesta restituisce fino a `limit` righe più un cursore `next_page`; passa il cursore invariato come parametro `page` nella richiesta successiva e ripeti finché `next_page` non è `null`. Tratta la stringa del cursore come opaca: non analizzarla, modificarla o costruirla tu stesso. [Elencare i plugin](https://platform.claude.com/docs/it/manage-claude/plugins-api#list-plugins) può restituire una pagina con meno di `limit` plugin, o nessuno, mentre `next_page` è ancora impostato, quindi continua a richiedere pagine finché `next_page` non è `null`. Gli iteratori di elenco degli SDK Python, TypeScript, C#, Go, Java e Ruby e la CLI (tranne con `--format raw`) lo fanno per te. Richiedono la pagina successiva finché `next_page` è impostato, quindi una pagina corta o vuota non li interrompe. In PHP e curl, richiedi ogni pagina tu stesso e passa il suo `next_page` come `page`.
`limit` ha un valore predefinito di 20 e un minimo di 1. Il massimo è 100 per plugin, impostazioni di installazione e condivisioni, e 1.000 per versioni e marketplace. Ogni elenco è ordinato dal più recente.
## Risposte di errore
Le risposte di errore seguono la struttura standard documentata in [Errori](https://platform.claude.com/docs/it/api/errors). Quando contatti il supporto, indica il `request_id` presente nel corpo della risposta.
| Stato | Significato |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | Input non valido, oppure l'operazione non si applica a questo plugin o marketplace (vedi la sezione di ciascun endpoint). Viene restituito anche per un parametro di query che l'endpoint non riconosce e per un'organizzazione che non è un'organizzazione Claude Enterprise (`this endpoint is not supported for this organization type`). |
| 401 | Header `x-api-key` mancante, oppure la chiave non è riconosciuta. |
| 403 | Alla chiave manca lo scope richiesto, oppure la richiesta carica file nel plugin di un membro o in un marketplace personale, ne modifica la versione servita o ne imposta il valore predefinito. (L'eliminazione del plugin di un membro è consentita.) |
| 404 | Risorsa non trovata. Viene restituito anche quando la richiesta omette il valore `anthropic-beta` o quando l'API non è abilitata per la tua organizzazione, in modo che gli endpoint risultino inesistenti. |
| 409 | Un nome è già in uso, una scansione dei contenuti è ancora in corso oppure è in corso un caricamento in conflitto. |
| 413 | Il corpo della richiesta supera il limite di dimensione: 200 MB per un caricamento, 32 MB per la convalida del marketplace. |
| 429 | Superato il "rate limit" (limite di velocità). Vedi [Limitazione della velocità](https://platform.claude.com/docs/it/manage-claude/plugins-api#rate-limiting). |
| 500 | Errore interno. |
| 503 | Errore temporaneo. Viene restituito anche quando più scritture di impostazioni di installazione per lo stesso plugin arrivano contemporaneamente; inviale una alla volta. Riprova con "backoff" (attesa progressiva tra i tentativi), tranne che per `registration_pending` (vedi la tabella seguente). |
Quando uno stesso stato ha più cause che gestiresti in modo diverso, l'errore include anche `error.details.error_code` e, quando la causa riguarda un plugin o una versione, `error.details.plugin_id` o `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` | Stato | Significato e cosa fare |
| ----------------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin_name_taken` | 409 | Nel marketplace esiste già un plugin con questo nome. `details.plugin_id` è quel plugin. Se stai ripetendo una creazione di cui hai perso la risposta, prosegui con quel plugin. Quando `plugin_id` è assente, il nome è occupato da una skill autonoma: carica con un altro nome oppure elimina la skill in claude.ai. |
| `skill_name_taken` | 409 | Il plugin si trova nel marketplace della libreria e una delle sue skill ha lo stesso nome di una skill dell'organizzazione (una skill caricata da un amministratore per l'intera organizzazione in claude.ai). `details.skill_name` ne indica il nome. Rinomina o rimuovi una delle due. |
| `registration_pending` | 503 | I file sono stati archiviati, ma le skill del plugin non è stato ancora possibile renderle disponibili ai membri. Vedi [Ripetere i caricamenti](https://platform.claude.com/docs/it/manage-claude/plugins-api#retrying-uploads). |
| `scan_pending` | 409 | La scansione dei contenuti della versione è ancora in corso. Riprova al termine. |
| `scan_failed` | 400 | La scansione dei contenuti della versione non è stata superata, ha generato un errore o non ha prodotto un esito, quindi la versione non può essere servita. Scegli un'altra versione. |
| `cmek_key_disabled`, `cmek_key_network_blocked` | 400 | La chiave di crittografia gestita dal cliente della tua organizzazione non è disponibile. Vedi [Chiavi di crittografia gestite dal cliente](https://platform.claude.com/docs/it/manage-claude/plugins-api#customer-managed-encryption-keys). |
Potrebbero essere aggiunti nuovi codici. Tratta un codice che non riconosci come tratteresti il relativo stato.
### Ripetere i caricamenti
Nessun endpoint accetta un `Idempotency-Key`. La modifica della versione servita, l'impostazione di un'impostazione di installazione e l'impostazione di un valore predefinito del marketplace possono essere ripetute in sicurezza. Un'eliminazione ripetuta, o una rimozione ripetuta di un'impostazione di installazione, restituisce `404`.
Un caricamento che restituisce un errore non ha archiviato nulla, con un'eccezione: `503` con `error_code: "registration_pending"`. Dopo aver archiviato i file di un caricamento, il server registra le skill della nuova versione presso claude.ai, ed è questo che le rende utilizzabili dai membri; `registration_pending` significa che i file sono stati archiviati ma quest'ultimo passaggio non è stato completato. Caricare di nuovo gli stessi file lo completa (e archivia un'ulteriore versione identica):
* Su `POST /v1/organizations/plugins`, il plugin *è stato* creato e la risposta include `x-should-retry: false`: non inviare di nuovo la creazione (un nuovo invio restituisce `409 plugin_name_taken`); carica invece gli stessi file come versione di `details.plugin_id`.
* Su `POST /v1/organizations/plugins/{plugin_id}/versions`, la versione *è stata* archiviata (`details.plugin_version_id`); invia di nuovo la stessa richiesta quando la risposta include `x-should-retry: true`, e non farlo quando include `false`.
Se la risposta di una creazione va persa, ripetila: il nuovo tentativo restituisce `409 plugin_name_taken` con l'ID del plugin in `details.plugin_id`, e prosegui con quel plugin. Ripetere la creazione di una versione la cui risposta è andata persa archivia una seconda versione identica. Per evitarlo, registra il `latest_version_id` del plugin prima di ogni caricamento; se una risposta va persa, leggi il plugin e riprova solo se `latest_version_id` è invariato.
## Eventi dell'Activity Feed
Ogni scrittura effettuata tramite questa API viene registrata nella [Compliance API Activity Feed](https://platform.claude.com/docs/it/manage-claude/compliance-activity-feed) della tua organizzazione, attribuita alla chiave API come `api_actor` con il relativo ID `apikey_`. Lo stesso attore compare in `created_by` nei plugin e nelle versioni creati dalla chiave.
| Evento | Emesso quando |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `claude_plugin_created` | Un plugin viene creato tramite un caricamento (qui o in claude.ai) o tramite una richiesta di pubblicazione accettata. Un plugin creato da una sincronizzazione Git emette solo `claude_plugin_version_created`. |
| `claude_plugin_version_created` | Viene archiviata una versione. Le versioni archiviate da una sincronizzazione Git sono attribuite a un `system_actor`. |
| `claude_plugin_updated` | Viene caricata una nuova versione in un plugin esistente. |
| `claude_plugin_served_version_updated` | La versione servita cambia. |
| `claude_plugin_deleted` | Un plugin viene eliminato singolarmente, qui o in claude.ai. |
| `plugin_installation_preference_updated` | Un'impostazione di installazione viene impostata o rimossa. |
| `marketplace_created` | Il primo caricamento crea il marketplace della libreria. |
| `marketplace_updated` | L'impostazione di installazione predefinita di un marketplace cambia, oppure un amministratore o un proprietario avvia una sincronizzazione in claude.ai. |
| `marketplace_deleted` | Un marketplace viene eliminato in claude.ai insieme ai suoi plugin (nessun evento per singolo plugin). |
| `claude_plugin_archive_accessed` | Viene scaricato l'archivio di un plugin di proprietà di un membro. |
| `claude_plugin_security_scan_completed` | Una scansione dei contenuti termina. |
Gli ID di plugin, versioni e marketplace in questi eventi sono gli stessi ID restituiti da questa API. `plugin_installation_preference_updated` identifica il plugin tramite il suo `name` e il suo `marketplace_id` anziché tramite il suo `id`.
La modifica del valore predefinito di un marketplace registra un solo evento `marketplace_updated` e nessun evento per singolo plugin, anche se cambia il valore di ogni plugin che eredita il valore predefinito. Le letture non vengono registrate, ad eccezione dei download dell'archivio di un plugin di proprietà di un membro. Una scrittura che non modifica nulla non registra nulla.
Le condivisioni concesse o revocate in claude.ai compaiono nel feed come eventi `role_assignment_granted` e `role_assignment_revoked`. Questa API non segnala le eliminazioni: un plugin eliminato è semplicemente assente dall'elenco successivo. Un plugin rimosso da una sincronizzazione Git, dall'eliminazione del suo marketplace (un evento `marketplace_deleted`) o dall'eliminazione dell'account di un membro o dell'organizzazione non emette alcun evento per singolo plugin, quindi rielenca periodicamente l'intero inventario per individuare le rimozioni.
## Chiavi di crittografia gestite dal cliente
Se la tua organizzazione utilizza una ["customer-managed encryption key"](https://platform.claude.com/docs/it/manage-claude/cmek) (chiave di crittografia gestita dal cliente), i campi `description`, `release_notes`, `components` e i file di una versione vengono crittografati con essa. Finché la chiave non è disponibile:
* Le letture e gli elenchi continuano a funzionare, con `description`, `release_notes` e `components` restituiti come `null`.
* I download degli archivi, le creazioni, le creazioni di versioni e le modifiche della versione servita restituiscono `400` con `cmek_key_disabled` o `cmek_key_network_blocked`.
* L'eliminazione di un plugin nel marketplace della libreria restituisce `400 cmek_key_disabled` e non elimina nulla, perché le sue skill devono prima essere ritirate da claude.ai e per farlo serve la chiave. Le altre eliminazioni, le impostazioni di installazione e i valori predefiniti del marketplace funzionano normalmente.
Il ripristino della chiave risolve tutte queste condizioni.
## Vedi anche
Dove il tuo proprietario principale crea una chiave con scope definito.
Gli endpoint dei gruppi che forniscono gli ID `rbac_group_` utilizzati nelle impostazioni di installazione.
Dove vengono registrate le scritture sui plugin e i download degli archivi dei membri.
Report sull'utilizzo di plugin e skill per Claude Enterprise.