API Plugins

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.

Endpoint

L'API espone 18 endpoint distribuiti su cinque risorse:

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. 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. Consulta Creare una chiave API Admin.
• 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, e la CLI ant sotto ant beta:organization; inviano gli header anthropic-version e anthropic-beta per te. Gli esempi in questa pagina usano il client predefinito di ciascun SDK, che, come la CLI, legge la chiave API Admin dalla variabile d'ambiente ANTHROPIC_API_KEY; gli esempi curl leggono la chiave dalla stessa variabile e la passano nell'header x-api-key. Negli esempi di elenco Python, TypeScript, C#, Go, Java e Ruby e nella CLI, l'SDK recupera altre pagine man mano che iteri, quindi limit imposta la dimensione della pagina, non il totale; gli esempi PHP e curl restituiscono una sola pagina (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 nel Compliance API Activity Feed, 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 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) 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:

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. Rimangono 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 ha lasciato l'organizzazione. Vengono eliminati quando viene eliminato l'account del membro.

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 segue quella più recente, e ogni nuova versione viene distribuita non appena viene archiviata.

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

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). 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 in modo permanente al plugin di ereditare il valore predefinito del suo marketplace, come spiega Configurare un'impostazione di installazione).

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.

Su un plugin non fissato, ogni caricamento diventa subito la versione distribuita. I membri perdono il plugin finché la scansione della nuova versione 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).

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:

reach conta 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 è stato possibile determinare perché uno dei suoi file di skill o di comando non poteva essere letto; 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 <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 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 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, che richiede una chiave creata per tutte le organizzazioni collegate (consulta 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 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, 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 del pilota, imposta il valore a livello di organizzazione (questo impedisce in modo permanente al plugin di ereditare il valore predefinito del suo marketplace, come spiega Configurare un'impostazione di installazione), poi rimuovi l'impostazione del gruppo in modo che il gruppo segua di nuovo l'organizzazione:

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   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 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 finché next_page non è null, passando tu stesso il next_page di ogni pagina come page anziché usare un iteratore di elenco dell'SDK, che su questo elenco può fermarsi prima del tempo (consulta Paginazione). 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 ti indica quali plugin hanno nuovi contenuti o una nuova versione distribuita dall'ultima esecuzione (per i quali vale la pena scaricare di nuovo l'archivio); 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 generare 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.
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 Scaricare i file di una versione).
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.

L'oggetto content_scan:

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

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

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ò non riuscire 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 la versione di un plugin di proprietà dell'organizzazione che viene servita ai membri. Passa una versione precedente per eseguire un rollback, oppure una più recente per promuovere una build che è stata archiviata senza essere servita. Questa operazione esegue il "pinning" (fissaggio) del plugin, e un plugin fissato attualmente non può essere sbloccato, né qui né in claude.ai (consulta Versioni e versione servita). 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 modifica nulla; passarla su un plugin non fissato lo fissa su quella versione, quindi i caricamenti successivi smettono di essere serviti automaticamente. 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 mantiene da quel momento un'impostazione propria), 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 sostituisce 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 di un plugin è uno "snapshot" (istantanea) immutabile dei file di un plugin provenienti da un singolo caricamento (la risposta di Crea 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; 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 servita non appena viene archiviata; se è fissato, la versione viene archiviata ma non servita finché non imposti la versione servita 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ò non riuscire 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 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.

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. {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). 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 modifica 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; questa operazione non può essere annullata, perché l'impostazione a livello di organizzazione non può essere rimossa, quindi il plugin non segue più le modifiche successive al valore predefinito del marketplace. 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 l'impostazione di installazione di un gruppo

DELETE /v1/organizations/plugins/{plugin_id}/installation_settings/{target} rimuove l'impostazione di un gruppo per un plugin di proprietà dell'organizzazione. I membri di quel gruppo ricadono sul valore a livello di organizzazione, oppure sull'impostazione di un altro dei loro gruppi. L'impostazione a livello di organizzazione non può essere rimossa una volta impostata, esattamente come in claude.ai (un {target} pari a organization restituisce 400); modificane invece il valore. Un gruppo che non ha alcuna impostazione per questo plugin restituisce 404. La risposta contiene la chiave composita al posto di un id. 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 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à); 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:

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

Paginazione

Gli endpoint di elenco usano 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. Elenca 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 recuperano ulteriori pagine durante l'iterazione ma si fermano alla prima pagina vuota, quindi sull'elenco dei plugin possono terminare in anticipo; quando ti servono tutti i plugin, come nel flusso di lavoro dell'inventario di sicurezza, richiedi tu stesso ogni pagina e passa il relativo 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. Quando contatti il supporto, indica il request_id presente nel corpo della risposta.

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 dell'impostazione di installazione di un gruppo, 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 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, 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" (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