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 per te gli header anthropic-version e anthropic-beta. Gli esempi in questa pagina usano il client predefinito di ciascun SDK che, come la CLI, legge la chiave Admin API dalla variabile d'ambiente ANTHROPIC_API_KEY; gli esempi curl leggono la chiave dalla stessa variabile e la passano nell'header x-api-key. Quando un SDK o la CLI recupera altre pagine per te, limit imposta la dimensione della pagina, non il totale (consulta Paginazione).

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. Restano nell'inventario sotto lo user_id del membro, e il filtro owner_user_id li trova ancora, così puoi esaminare e rimuovere i contenuti di un membro che se n'è andato. Vengono rimossi dall'inventario quando l'account del membro viene eliminato.

Versioni e versione distribuita

Ogni caricamento crea una nuova version (versione) immutabile, che provenga da questa API, da claude.ai o da una sincronizzazione Git. Un plugin ha due puntatori alle sue versioni:

• latest_version_id: la versione più recente.
• served_version_id: la "served version" (versione distribuita), ovvero quella distribuita ai membri.

Per impostazione predefinita served_version_pinned è false: la versione distribuita normalmente segue quella più recente. Quando la scansione dei contenuti è attiva, una versione salvata in claude.ai potrebbe attendere la propria scansione dei contenuti: viene archiviata ma non distribuita subito. Questa pagina usa "attendere" solo per una versione salvata in claude.ai, non per una che un membro o un amministratore pubblica in un plugin. Mentre la scansione è attiva, una versione in attesa viene distribuita solo dopo che la sua scansione si completa con pass o warn. Mentre una versione è in attesa, served_version_id indica una versione precedente a latest_version_id. Non eseguire il polling finché i due ID non coincidono: potrebbero restare diversi, ad esempio quando la scansione fallisce.

La scelta di una versione con POST /v1/organizations/plugins/{plugin_id} esegue il pin (fissaggio) del plugin (served_version_pinned: true). Lo stesso accade quando un amministratore sceglie una versione in claude.ai, o accetta la richiesta di un membro di pubblicare nel plugin. Da quel momento, i nuovi caricamenti vengono archiviati e fanno avanzare latest_version_id, ma i membri mantengono la versione fissata finché non punti served_version_id a un'altra. Un plugin i cui due puntatori differiscono ha una versione archiviata che non viene distribuita.

Questo consente a una pipeline di rilascio di caricare ogni build, testarla e poi promuoverla. Per fare in modo che sia la tua pipeline a decidere quando ogni build viene distribuita, fissa il plugin una volta impostando served_version_id sulla sua versione corrente; da quel momento, promuovi ogni build che vuoi distribuire. Con la scansione dei contenuti attiva, quel primo fissaggio restituisce 409 scan_pending finché la scansione della versione corrente non è completata, e 400 scan_failed se la scansione si è completata con fail o unknown, o è andata in errore (warn è accettato). Un plugin fissato attualmente non può essere sbloccato, né qui né in claude.ai.

Per eseguire il rollback, imposta served_version_id su una versione precedente. Per avanzare, procedi allo stesso modo.

Queste regole descrivono i plugin di proprietà dell'organizzazione. La versione distribuita di un plugin di proprietà di un membro è controllata dal suo proprietario in claude.ai.

Impostazioni di installazione