API Plugins

L’API Plugins ti consente di fare quanto segue:

• Inventariare i plugin nella tua organizzazione Claude Enterprise
• Pubblicare plugin e nuove versioni dalle tue pipeline
• Scegliere quale versione viene fornita ai membri
• Controllare chi può usare ciascun plugin
• Scaricare i file dei plugin per la revisione
• 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.

Endpoint

L’API espone 18 endpoint distribuiti su cinque risorse:

I plugin pubblicati da Anthropic non sono inventariati; il loro utilizzo è riportato dalle API Analytics. 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 Admin API con lo scope read:plugins, lo scope write:plugins o entrambi in claude.ai > Impostazioni organizzazione > API. Consulta Creare una chiave per un’organizzazione Claude Enterprise.
• Ogni richiesta include tre header: x-api-key, anthropic-version: 2026-10-21 e anthropic-beta: ce-plugins-2026-09-01.

In Python, TypeScript, C#, Go, Java, PHP e Ruby, l’SDK espone questi endpoint sotto client.beta.organization, e la CLI ant sotto ant beta:organization; inviano gli header anthropic-version e anthropic-beta per te. Gli esempi in questa pagina leggono la chiave Admin API dalla variabile d’ambiente ANTHROPIC_API_KEY. Quando un SDK o la CLI recupera altre pagine per te, limit imposta la dimensione della pagina, non il totale (consulta Paginazione).

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:

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

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

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). Ogni download di questo tipo registra un evento claude_plugin_archive_accessed nell’Activity Feed della Compliance API, che identifica la chiave, il plugin, la versione e il membro (consulta Eventi dell’Activity Feed). 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 l’organizzazione in cui sono state create. Alcune aziende hanno diverse organizzazioni Claude collegate sotto un’unica organizzazione padre. Una chiave read:org_audit o read:compliance_org_data creata per tutte le organizzazioni collegate può leggere anche qualsiasi organizzazione collegata che abbia accesso a questa API. Per leggerne una, passa il suo ID 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. Una chiave senza un’organizzazione propria deve sempre passare organization_id. Un 404 significa che l’organizzazione indicata non si trova sotto il padre della chiave oppure 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:

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 versione fornita ai membri

Per impostazione predefinita served_version_pinned è false: la versione fornita 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 memorizzata ma non fornita 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 fornita solo quando il suo content_scan indica completed con pass o warn. Mentre una versione è in attesa, served_version_id indica una versione precedente rispetto a latest_version_id. Non eseguire il polling finché i due ID non coincidono: potrebbero rimanere 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 la tua pipeline determini quando ogni build viene fornita, fissa il plugin una volta impostando served_version_id sulla sua versione corrente; da quel momento, promuovi ogni build che vuoi fornire. Con la scansione dei contenuti attiva, quella prima fissazione restituisce 409 scan_pending finché il content_scan della versione corrente indica processing, e 400 scan_failed se la scansione indica fail, unknown o errored (warn è accettato). Un plugin fissato 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 impostazioni di installazione determinano 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):

Un plugin può avere un’impostazione a livello di organizzazione e un’impostazione per ciascun gruppo (i gruppi di controllo degli accessi basato sui ruoli gestiti in Gestione utenti). 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 Pilota ha available, i membri di Pilota 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 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 condivisioni determinano 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, ai membri viene fornito un plugin solo quando la scansione della sua versione fornita è completed con pass o warn. Mentre la scansione è processing o errored, oppure indica fail o unknown, il plugin viene negato ai membri e non viene fornita al suo posto una versione precedente. Una versione mai scansionata (content_scan: null) viene fornita normalmente.

Una versione che carichi tramite questa API non attende mai la propria scansione dei contenuti. Quando diventa la versione fornita, i membri perdono il plugin finché il suo content_scan non indica completed con pass o warn. Se i membri devono mantenere la versione corrente mentre ne viene scansionata una nuova, fissa prima il plugin (consulta Versioni e versione distribuita).

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

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 servita. Mentre la scansione è attiva, cambiare la versione servita in una versione il cui content_scan riporta processing restituisce 409 scan_pending, e cambiarla in una la cui scansione riporta fail, unknown o errored restituisce 400 scan_failed.

Scansioni non riuscite consentite in claude.ai

In claude.ai, i proprietari dell’organizzazione possono consentire una versione la cui scansione non è riuscita. Lo stesso possono fare i membri il cui ruolo personalizzato può gestire le Librerie. Questa API può quindi riportare quella scansione come completed con warn e il reason della scansione non riuscita. In tal caso si applicano le regole di warn: la versione può essere servita ai membri e puoi renderla la versione servita. Nulla nella risposta indica che è stata consentita, quindi un warn è un avviso oppure una scansione non riuscita che è stata consentita. Consentire una versione la cui scansione riporta warn non modifica il suo content_scan. Quando una versione smette di essere consentita, questa API riporta il verdetto della sua scansione completata più recente. Una versione servita la cui scansione riporta quindi fail o unknown viene negata ai membri.

Portata

reach riassume, in un unico valore, fin dove arriva una versione sui computer dei membri e oltre:

reach tiene conto di tutto ciò che la versione dichiara, inclusi monitor, server LSP, workflow 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. Il valore viene normalmente calcolato quando una versione viene archiviata, secondo le regole di quel momento. Una versione precedente può quindi essere contained laddove gli stessi file archiviati oggi sarebbero privileged.

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. Una description che il manifest prende da quel SKILL.md viene troncata ai suoi primi 500 caratteri.
• 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 <example>. 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 decompresso sono ciascuno al 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 caricamento che crea un plugin restituisce 400 quando il marketplace contiene già 1.000 plugin. Vengono conteggiati anche i plugin che questa API non elenca, quindi il limite può essere raggiunto anche quando Elencare i plugin ne mostra meno di 1.000 in quel marketplace. Anthropic può aumentare il limite di 5.000 file.

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 determinare quando una build viene fornita.

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 con POST /v1/organizations/plugins. A ogni rilascio successivo, registra il latest_version_id del plugin, poi carica una versione 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).
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 con POST /v1/organizations/plugins/{plugin_id} e {"served_version_id": "<the new version's 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 (consulta Gruppi e ruoli in Gestione utenti). 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 un’unica chiave nell’organizzazione che contiene il plugin e assegnale entrambi gli scope, oppure usa una seconda chiave creata lì per quei passaggi.

2. Assegna al gruppo una propria impostazione, 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 in seguito riporta il plugin a quel valore predefinito.

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

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

   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 segnala i plugin che arrivano oltre la sessione del membro o la cui scansione dei contenuti indica warn, fail o unknown.

1. Scorri le pagine di GET /v1/organizations/plugins?limit=100 finché next_page non è null (consulta Paginazione). Leggi reach e content_scan di ciascun plugin da quell’elenco a ogni esecuzione: una modifica al solo content_scan, come un verdetto che arriva in seguito, non aggiorna updated_at. updated_at normalmente ti indica quali plugin hanno nuovi contenuti o una nuova versione servita dall’ultima esecuzione (per cui vale la pena scaricare di nuovo l’archivio). Una versione in attesa (consulta Versioni e versione distribuita) aggiorna updated_at quando diventa la versione servita, non necessariamente quando viene memorizzata. 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 è warn, fail o unknown. Un warn può anche essere una scansione non riuscita consentita in claude.ai. Escludi warn solo se accetti ogni scansione non riuscita che viene consentita lì. Questi campi descrivono la versione servita. Per verificare anche una versione più recente non servita, elenca le versioni del plugin quando latest_version_id differisce da served_version_id (consulta Elencare le versioni di un plugin).
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). 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 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 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.

description non è sempre quella del manifest. Una description che il manifest prende da un SKILL.md di primo livello viene troncata ai suoi primi 500 caratteri (consulta Requisiti di caricamento). Se la description del manifest corrisponde ai primi 500 caratteri di esattamente una description distinta di una skill in components, l’API restituisce invece quella description della skill. Di conseguenza:

• Una description che leggi potrebbe essere più lunga di 500 caratteri, il limite per un manifest caricato. Un caricamento il cui plugin.json imposta una tale description restituisce 400.
• Nei file che scarichi, .claude-plugin/plugin.json potrebbe avere una description diversa, o nessuna.

L’oggetto content_scan:

Un plugin_id privo del prefisso plugin_ restituisce 400. Un plugin_id che ha il prefisso ma non è nell’inventario della tua organizzazione restituisce 404.

Elencare i plugin

GET /v1/organizations/plugins elenca i plugin della 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 (un ID con prefisso user_, che trova 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. Richiede lo scope read:plugins.

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

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 versione servita. Il corpo è multipart/form-data: files[] è un singolo archivio .zip o .plugin, oppure una parte per ciascun file, dove il nome file di ogni 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, oppure per impostazione predefinita il tuo marketplace della libreria, che viene creato al primo utilizzo) e release_notes (fino a 5.000 caratteri, mostrati nella cronologia delle versioni di claude.ai e restituiti sulla versione). I campi name, display_name, description e manifest_version del plugin provengono dai file caricati, e il caricamento deve soddisfare i requisiti di caricamento. Quando la scansione del contenuto è attiva, il content_scan.status della risposta è processing e il verdetto arriva in modo asincrono. Restituisce il plugin. Richiede lo scope write:plugins.

Carica un archivio:

client = anthropic.Anthropic()

with open("dist/sales-toolkit.zip", "rb") as archive:
    plugin = client.beta.organization.plugins.create(
        files=[archive],
        release_notes="First release",
    )

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

{
  "type": "plugin",
  "id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
  "name": "sales-toolkit",
  "display_name": "Sales Toolkit",
  "description": "Account research and call prep for the sales team.",
  "served_version_id": "pluginver_01Km7tL4pR9xF5sU2zV3jP6q",
  "served_version_pinned": false,
  "latest_version_id": "pluginver_01Km7tL4pR9xF5sU2zV3jP6q",
  "manifest_version": "1.4.0",
  "owner": { "type": "organization" },
  "marketplace_id": "marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r",
  "created_by": { "type": "api_actor", "api_key_id": "apikey_01Nq9vN6rT2zH7uW4bX5mR8s" },
  "organization_installation_preference": "available",
  "organization_installation_preference_inherited": true,
  "content_scan": { "status": "processing", "assessment": null, "reason": null },
  "components": [
    {
      "type": "skill",
      "name": "account-research",
      "description": "Researches a customer account before a call."
    },
    { "type": "mcp_server", "name": "crm", "description": null }
  ],
  "reach": "remote",
  "created_at": "2026-09-01T17:04:11Z",
  "updated_at": "2026-09-01T17:04:11Z"
}

Carica singoli file in un marketplace specifico. Allega ogni file con il suo percorso all’interno del plugin (il suffisso ;filename= nell’esempio cURL, gli argomenti del nome file negli esempi SDK); un file inviato con il solo nome 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 singolo archivio nel marketplace:

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

Oltre a un 400 per un caricamento che viola i requisiti di caricamento (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), una creazione può fallire con:

Ottieni un plugin

GET /v1/organizations/plugins/{plugin_id} restituisce un plugin. Richiede lo scope read:plugins.

client = anthropic.Anthropic()

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

print(f"id: {plugin.id}")
print(f"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 memorizzata senza essere servita. Questo fissa il plugin, e un plugin fissato non può essere sbloccato, né qui né in claude.ai (consulta Versioni e versione distribuita). 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). 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. Fissare pone fine anche a qualsiasi attesa: una versione che era in attesa della scansione dei contenuti rimane memorizzata, e viene servita solo se qualcuno la sceglie. Restituisce il plugin. Richiede lo scope write:plugins.

client = anthropic.Anthropic()

plugin = client.beta.organization.plugins.update(
    "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
    served_version_id="pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p",
)

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

{
  "type": "plugin",
  "id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
  "name": "sales-toolkit",
  "display_name": "Sales Toolkit",
  "description": "Account research and call prep for the sales team.",
  "served_version_id": "pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p",
  "served_version_pinned": true,
  "latest_version_id": "pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p",
  "manifest_version": "1.5.0",
  "owner": { "type": "organization" },
  "marketplace_id": "marketplace_01Lp8uM5qS1yG6tV3aW4kQ7r",
  "created_by": { "type": "api_actor", "api_key_id": "apikey_01Nq9vN6rT2zH7uW4bX5mR8s" },
  "organization_installation_preference": "available",
  "organization_installation_preference_inherited": true,
  "content_scan": { "status": "completed", "assessment": "pass", "reason": null },
  "components": [
    {
      "type": "skill",
      "name": "account-research",
      "description": "Researches a customer account before a call."
    },
    { "type": "mcp_server", "name": "crm", "description": null },
    {
      "type": "command",
      "name": "call-prep",
      "description": "Builds a one-page brief for an upcoming call."
    }
  ],
  "reach": "remote",
  "created_at": "2026-09-01T17:04:11Z",
  "updated_at": "2026-09-16T10:02:45Z"
}

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), la richiesta può non riuscire con:

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 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). Un plugin di proprietà di un membro non può essere nascosto tramite questa API se non eliminandolo, e solo se il suo marketplace è manual.

client = anthropic.Anthropic()

deleted_plugin = client.beta.organization.plugins.delete(
    "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
)

print(f"id: {deleted_plugin.id}")

{ "type": "plugin_deleted", "id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL" }

Versioni dei plugin

Una versione del plugin è uno snapshot immutabile dei file di un plugin derivante da un singolo caricamento (la risposta di Creare una versione 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 e 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.

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

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 e gli stessi errori relativi a file, manifest, archivio e dimensioni di Crea un 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.

client = anthropic.Anthropic()

with open("dist/sales-toolkit.zip", "rb") as archive:
    version = client.beta.organization.plugins.versions.create(
        "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
        files=[archive],
        release_notes="Adds the call-prep command.",
    )

print(f"id: {version.id}")
print(f"manifest_version: {version.manifest_version}")

{
  "type": "plugin_version",
  "id": "pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p",
  "plugin_id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
  "display_name": "Sales Toolkit",
  "description": "Account research and call prep for the sales team.",
  "manifest_version": "1.5.0",
  "release_notes": "Adds the call-prep command.",
  "created_by": { "type": "api_actor", "api_key_id": "apikey_01Nq9vN6rT2zH7uW4bX5mR8s" },
  "content_scan": { "status": "processing", "assessment": null, "reason": null },
  "components": [
    {
      "type": "skill",
      "name": "account-research",
      "description": "Researches a customer account before a call."
    },
    { "type": "mcp_server", "name": "crm", "description": null },
    {
      "type": "command",
      "name": "call-prep",
      "description": "Builds a one-page brief for an upcoming call."
    }
  ],
  "reach": "remote",
  "created_at": "2026-09-15T14:12:30Z"
}

Oltre a un 400 per un caricamento che viola i requisiti di caricamento (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), la richiesta può fallire con:

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.

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

Scarica i file di una versione

GET /v1/organizations/plugins/{plugin_id}/versions/{version}/content scarica i file di una versione come l’archivio .zip memorizzato (Content-Type: application/zip). L’archivio viene restituito qualunque sia il risultato della scansione del contenuto, quindi puoi ispezionare le versioni sospese per i membri. Viene servito esattamente come memorizzato, quindi per un plugin di proprietà dell’organizzazione in un marketplace manual puoi ricaricarlo invariato come nuova versione, a condizione che soddisfi i requisiti di caricamento attuali. {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 sul plugin e sull’ID 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.

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

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 (consulta Condivisioni dei plugin). {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 Gruppi in Gestione utenti). 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.

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

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

client = anthropic.Anthropic()

setting = client.beta.organization.plugins.installation_settings.set(
    "rbac_group_01F3xQqQzXyWvUtSrQpOnMlK",
    plugin_id="plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
    installation_preference="available",
)

print(f"plugin_id: {setting.plugin_id}")
print(f"installation_preference: {setting.installation_preference}")

{
  "type": "plugin_installation_setting",
  "plugin_id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
  "target": { "type": "rbac_group", "rbac_group_id": "rbac_group_01F3xQqQzXyWvUtSrQpOnMlK" },
  "installation_preference": "available",
  "created_at": "2026-09-02T10:00:00Z",
  "updated_at": "2026-09-02T10:00:00Z"
}

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.

client = anthropic.Anthropic()

removed_setting = client.beta.organization.plugins.installation_settings.remove(
    "rbac_group_01F3xQqQzXyWvUtSrQpOnMlK",
    plugin_id="plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
)

print(f"plugin_id: {removed_setting.plugin_id}")

{
  "type": "plugin_installation_setting_deleted",
  "plugin_id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",
  "target": { "type": "rbac_group", "rbac_group_id": "rbac_group_01F3xQqQzXyWvUtSrQpOnMlK" }
}

Condivisioni dei plugin

Le condivisioni esistono solo sui plugin di proprietà dei membri e sono di sola lettura in questa API (consulta Condivisioni).

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

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

{
  "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 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.

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

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.

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

Ottieni un marketplace

GET /v1/organizations/plugin_marketplaces/{marketplace_id} restituisce un marketplace. Richiede lo scope read:plugins.

client = anthropic.Anthropic()

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

print(f"id: {marketplace.id}")
print(f"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.

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

Convalida il contenuto di un marketplace

Due endpoint riportano cosa farebbe una sincronizzazione del contenuto del marketplace indicato, senza connettere 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. 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 gli stessi eseguiti da una sincronizzazione reale. I problemi relativi al contenuto vengono restituiti nel report, non come errori HTTP: la richiesta ha esito positivo 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 ciascuna organizzazione (consulta Limitazione della velocità); non registrano nulla nell’Activity Feed. Una convalida può richiedere fino a 120 secondi prima di restituire un risultato, quindi imposta il timeout del tuo client su un valore superiore. Entrambi gli endpoint richiedono l’ambito read:plugins o write:plugins (read:org_audit e read:compliance_org_data non li concedono).

La convalida legge il repository in modo anonimo. Fa lo stesso per qualsiasi sorgente di plugin che si trova su GitHub ma al di fuori del repository. Di conseguenza, la convalida segnala un repository privato o una sorgente di plugin privata come non trovati o come bisognosi di un accesso a GitHub. Quando la convalida segnala che è necessario un accesso a GitHub, il codice del report è marketplace_repo_sign_in_required.

La convalida non recupera le sorgenti di plugin su host diversi da GitHub. Un plugin con una tale sorgente riceve normalmente un avviso marketplace_validate_source_not_checked e viene controllato quando il marketplace viene effettivamente sincronizzato.

La convalida applica regole più rigide a un marketplace che Anthropic sincronizza in ogni organizzazione. validate_repository le applica quando il repository è un tale marketplace. validate_archive le applica quando l’archivio indica un tale marketplace. Le regole più rigide sono le seguenti:

• Ogni sorgente di plugin esterna al marketplace deve essere fissata a uno SHA di commit completo.
• La convalida segnala le sorgenti non fissate e le sorgenti su host non supportati come errori del plugin.
• Per validate_repository, il branch letto dalla convalida è per impostazione predefinita il branch da cui il 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 ref è omesso o null, per impostazione predefinita corrisponde al branch che una sincronizzazione leggerebbe, 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. Il file è un .zip della directory del marketplace, di al massimo 32 MB, che utilizza solo la compressione DEFLATE o STORE. Il contenuto dell’archivio si trova nella radice o è racchiuso in una cartella (come produce il download da un host Git). Non è accettato nessun altro campo del modulo.

Convalida un repository pubblico su un branch:

client = anthropic.Anthropic()

report = client.beta.organization.plugin_marketplaces.validate_repository(
    repository_url="https://github.com/example-org/claude-plugins",
    ref="release-candidate",
)

print(f"valid: {str(report.valid).lower()}")
print(f"total_plugin_count: {report.total_plugin_count}")

{
  "type": "plugin_marketplace_validation_report",
  "valid": false,
  "ref": "release-candidate",
  "commit_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8",
  "total_plugin_count": 3,
  "manifest_error": null,
  "manifest_error_code": null,
  "plugin_errors": [
    {
      "name": "deploy-helper",
      "error": "The plugin has a top-level bin/ directory.",
      "error_code": "marketplace_sync_bin_directory_not_allowed"
    }
  ],
  "plugin_warnings": [
    {
      "name": "release-notes",
      "warnings": [
        {
          "message": "plugin.json has unrecognized top-level keys: owners",
          "error_code": "marketplace_sync_plugin_unrecognized_keys"
        }
      ]
    }
  ]
}

Convalida invece una copia locale della directory del marketplace, come .zip; la risposta è lo stesso report:

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

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 e Limitazione della velocità), la richiesta stessa può non riuscire con:

Codici del report

Ogni risultato in un report ha un codice stabile: manifest_error_code quando non è stato possibile convalidare nulla, error_code su ciascuna voce di plugin_errors, ed error_code su ciascun avviso. Quando un plugin ha diversi 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 ha potuto essere 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 avere esito positivo 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 limite di 300 richieste al minuto per ciascuna organizzazione. 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 ciascuna organizzazione. Una convalida del marketplace (con uno qualsiasi dei due endpoint) conta come una lettura, e le convalide sono inoltre limitate a 10 al minuto per ciascuna organizzazione su entrambi gli endpoint; entrambi i limiti vengono verificati prima che venga letto il corpo della richiesta. Questi limiti sono conteggiati su tutte le chiavi della tua organizzazione e sono separati dagli altri limiti dell’Admin API della tua organizzazione. Una lettura che passa organization_id viene conteggiata nel limite dell’organizzazione in cui è stata creata la chiave, oppure dell’organizzazione padre se la chiave non ha un’organizzazione propria. Le richieste oltre un limite restituiscono 429 Too Many Requests con un’intestazione retry-after. Le risposte includono le intestazioni anthropic-ratelimit-requests-* per il limite applicabile (sulla convalida del 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).

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 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 forma standard documentata in Errori della Claude API. Indica il request_id presente nel corpo della risposta quando contatti l’assistenza.

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:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "...",
    "details": {
      "error_code": "plugin_name_taken",
      "plugin_id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
    }
  },
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWG"
}

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, invia di nuovo la creazione. Un 409 plugin_name_taken significa che il primo tentativo ha archiviato il plugin oppure che il nome era già in uso. La tua creazione persa ha creato il plugin in details.plugin_id solo se il suo created_by è un api_actor con l’api_key_id della tua chiave. Verificalo prima di caricare su di esso (consulta plugin_name_taken nella tabella precedente). 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 nell’Activity Feed della Compliance API 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.

Gli ID di plugin, versione e marketplace in questi eventi sono gli stessi ID restituiti da questa API. Un evento può anche indicare un marketplace che questa API non elenca, ad esempio un marketplace di plugin pubblicati da Anthropic. plugin_installation_preference_updated identifica il plugin tramite il suo name e marketplace_id anziché il suo id. In claude_plugin_security_scan_completed, plugin_version non è un ID di versione, e nessun campo di una versione del plugin vi corrisponde.

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 è 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” (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