API Plugins

L'API Plugins vous permet d'inventorier chaque plugin de votre organisation Claude Enterprise, de publier des plugins et de nouvelles versions depuis vos propres pipelines, de choisir la version servie aux membres, de contrôler qui peut utiliser chaque plugin, de télécharger les fichiers des plugins pour examen et de vérifier une « marketplace » (place de marché) Git avant de la connecter.

Pour les rapports d'utilisation des plugins (quels plugins et quelles skills les membres utilisent, et à quelle fréquence), consultez les API Analytics.

Points de terminaison

L'API expose 18 points de terminaison répartis sur cinq ressources :

Cette version n'inclut pas les skills autonomes (les skills qu'un membre rédige dans l'éditeur de skills ou téléverse en tant que skill unique dans claude.ai). Elles n'apparaissent pas dans l'inventaire et ne peuvent pas être créées ici. Les plugins publiés par Anthropic ne sont pas non plus inventoriés ; leur utilisation est rapportée par les API Analytics. Les marketplaces sont créées, connectées à des dépôts et supprimées dans claude.ai, et non via cette API.

Prérequis

• Votre organisation doit disposer d'un forfait Claude Enterprise.
• Votre propriétaire principal crée une clé API Admin dotée de la portée read:plugins, de la portée write:plugins, ou des deux, dans claude.ai > Organization settings > API. Consultez Créer une clé API Admin.
• Chaque requête comporte trois en-têtes : x-api-key, anthropic-version: 2023-06-01 et anthropic-beta: ce-plugins-2026-09-01.

Les SDK Python, TypeScript, C#, Go, Java, PHP et Ruby exposent ces points de terminaison sous client.beta.organization, et la CLI ant sous ant beta:organization ; ils envoient les en-têtes anthropic-version et anthropic-beta pour vous. Les exemples de cette page utilisent le client par défaut de chaque SDK, qui, comme la CLI, lit la clé API Admin depuis la variable d'environnement ANTHROPIC_API_KEY ; les exemples curl lisent la clé depuis la même variable et la transmettent dans l'en-tête x-api-key. Dans les exemples de liste Python, TypeScript, C#, Go, Java et Ruby ainsi que dans la CLI, le SDK récupère des pages supplémentaires au fil de l'itération, de sorte que limit définit la taille de page, et non le total ; les exemples PHP et curl renvoient une seule page (consultez Pagination).

Les clés API appartiennent à l'organisation et continuent de fonctionner après le départ de la personne qui les a créées. Ne les partagez pas et ne les enregistrez pas dans un système de gestion de versions.

Démarrage rapide

Listez les plugins des marketplaces propres à votre organisation, du plus récent au plus ancien :

client = anthropic.Anthropic()

plugins = client.beta.organization.plugins.list(owner_type="organization", limit=20)

# Récupère automatiquement des pages supplémentaires si nécessaire.
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"
}

Dans cet exemple, le plugin est épinglé à une version antérieure : une version plus récente (latest_version_id) est stockée mais pas encore servie.

Portées

Une clé peut porter plusieurs portées. Une intégration qui téléverse un plugin puis le relit a besoin à la fois de read:plugins et de write:plugins. Partout où cette page indique qu'un point de terminaison nécessite la portée read:plugins, une clé dotée de read:org_audit ou de read:compliance_org_data fonctionne également.

Accès aux fichiers des plugins des membres

Chacune de ces portées de lecture (read:plugins, read:org_audit et read:compliance_org_data) permet de télécharger les fichiers des plugins situés dans les marketplaces personnelles des membres, y compris des fichiers que les paramètres d'administration de claude.ai n'affichent pas, et une clé read:org_audit ou read:compliance_org_data liée à votre organisation parente peut le faire dans toute organisation placée sous celle-ci qui a accès à cette API, en transmettant organization_id (consultez Lire une autre organisation sous le même parent). Chacun de ces téléchargements enregistre un événement claude_plugin_archive_accessed dans le flux d'activité (Activity Feed) de la Compliance API, identifiant la clé, le plugin, la version et le membre (consultez Événements du flux d'activité). Les téléchargements de plugins appartenant à l'organisation ne sont pas enregistrés.

Lire une autre organisation sous le même parent

Les clés read:plugins et write:plugins ne lisent et n'écrivent que dans l'organisation où elles ont été créées. Si votre entreprise possède plusieurs organisations Claude liées sous une même organisation parente, une clé read:org_audit ou read:compliance_org_data que le propriétaire principal du parent a créée pour toutes les organisations liées (consultez Créer une clé API Admin) peut également lire n'importe laquelle d'entre elles ayant accès à cette API : transmettez l'ID de cette organisation dans le paramètre de requête organization_id sur n'importe quel point de terminaison GET de cette page. L'ID est l'UUID de l'organisation affiché dans les paramètres de claude.ai (sa forme préfixée par org_ est également acceptée). Sans ce paramètre, la clé lit l'organisation dans laquelle elle a été créée. Un 404 signifie que l'organisation désignée ne se trouve pas sous le parent de la clé ou que l'API ne lui est pas disponible ; une valeur qui n'est ni un UUID ni un ID org_ renvoie 400. Toute autre clé qui désigne une organisation autre que la sienne obtient 404. Les écritures n'acceptent pas organization_id.

Concepts clés

Plugins et composants

Un plugin est un paquet qui étend Claude pour les membres de votre organisation. Il contient n'importe quelle combinaison des composants suivants :

Chaque plugin possède un manifeste à l'emplacement .claude-plugin/plugin.json. Le name du manifeste devient le name du plugin : un identifiant en minuscules, unique au sein de sa marketplace.

Marketplaces

Une marketplace est un conteneur de plugins. Chaque marketplace a un propriétaire et une source.

• Propriétaire. L'organisation possède ses marketplaces. Chaque membre peut également avoir des marketplaces personnelles.
• Source. manual signifie que les plugins sont téléversés, dans claude.ai ou, pour une marketplace d'organisation, via cette API. github, gitlab et public_git signifient que les plugins sont synchronisés depuis un dépôt Git que le propriétaire a connecté. Rien ne peut être téléversé dans une marketplace synchronisée, et cette API ne peut pas en supprimer les plugins, car la synchronisation suivante annulerait l'une ou l'autre modification. Modifiez plutôt le dépôt.

La marketplace de bibliothèque de votre organisation est la marketplace manual appartenant à l'organisation vers laquelle vont les téléversements lorsque vous ne désignez pas de marketplace. Elle est créée la première fois que quelque chose y est téléversé.

Plugins appartenant à l'organisation et plugins appartenant aux membres

Le champ owner.type d'un plugin indique dans quelle marketplace il se trouve :

• organization : vous pouvez le gérer via cette API, sauf qu'un plugin situé dans une marketplace synchronisée depuis Git ne peut pas recevoir de téléversements ni être supprimé ici.
• user : il se trouve dans la marketplace personnelle d'un membre. Vous pouvez lire ses détails et télécharger ses fichiers, et le supprimer si sa marketplace est manual. Le téléversement de versions et le choix de la version servie renvoient 403. Le partage est géré uniquement par le membre, dans claude.ai.

Retirer un membre de l'organisation ne supprime pas ses plugins. Ils restent dans l'inventaire sous le user_id du membre, et le filtre owner_user_id les trouve toujours, ce qui vous permet d'examiner et de supprimer le contenu d'un membre parti. Ils sont supprimés lorsque le compte du membre est supprimé.

Versions et version servie

Chaque téléversement crée une nouvelle version immuable, qu'il provienne de cette API, de claude.ai ou d'une synchronisation Git. Un plugin possède deux pointeurs vers ses versions :

• latest_version_id : la version la plus récente.
• served_version_id : la version servie aux membres.

Par défaut, served_version_pinned vaut false : la version servie suit la plus récente, et chaque nouvelle version est servie dès qu'elle est stockée.

Choisir une version avec POST /v1/organizations/plugins/{plugin_id} épingle le plugin (served_version_pinned: true). Il en va de même lorsqu'un administrateur choisit une version dans claude.ai, ou accepte la demande d'un membre de publier dans le plugin. À partir de ce moment, les nouveaux téléversements sont stockés et font avancer latest_version_id, mais les membres conservent la version épinglée jusqu'à ce que vous fassiez pointer served_version_id vers une autre version. Un plugin dont les deux pointeurs diffèrent possède une version stockée qui n'est pas servie.

Cela permet à un pipeline de publication de téléverser chaque build, de le tester, puis de le promouvoir. Pour que votre pipeline décide du moment où chaque build est servi, épinglez le plugin une fois en définissant served_version_id sur sa version actuelle ; à partir de là, promouvez chaque build que vous souhaitez servir. Lorsque l'analyse de contenu est activée, ce premier épinglage renvoie 409 scan_pending jusqu'à ce que l'analyse de la version actuelle soit terminée, et 400 scan_failed si l'analyse s'est terminée avec fail ou unknown, ou a échoué avec une erreur (warn est accepté). Un plugin épinglé ne peut actuellement pas être désépinglé, ni ici ni dans claude.ai.

Pour revenir en arrière, définissez served_version_id sur une version antérieure. Procédez de la même manière pour avancer.

Ces règles décrivent les plugins appartenant à l'organisation. La version servie d'un plugin appartenant à un membre est contrôlée par son propriétaire dans claude.ai.

Paramètres d'installation

Les paramètres d'installation déterminent qui peut utiliser un plugin appartenant à l'organisation. Chaque paramètre a l'une des quatre valeurs suivantes, portées par les champs nommés installation_preference (et, sur les objets plugin et marketplace, organization_installation_preference et default_installation_preference) :

Un plugin peut avoir un paramètre à l'échelle de l'organisation et un paramètre par groupe (les groupes de contrôle d'accès basé sur les rôles gérés dans la gestion des utilisateurs). Un membre obtient une valeur selon les règles suivantes :

1. La valeur à l'échelle de l'organisation est le paramètre propre du plugin à l'échelle de l'organisation s'il en a un, sinon la valeur par défaut de sa marketplace, sinon not_available. Le plugin indique cette valeur dans organization_installation_preference, avec organization_installation_preference_inherited: true tant qu'elle provient de la valeur par défaut de la marketplace.
2. Un membre qui n'appartient à aucun groupe ayant un paramètre pour le plugin obtient la valeur à l'échelle de l'organisation.
3. Un membre qui appartient à un ou plusieurs groupes ayant un paramètre obtient à la place le plus permissif des paramètres de ces groupes, selon l'ordre required, auto_install, available, not_available.

Le paramètre d'un groupe remplace la valeur à l'échelle de l'organisation pour ses membres ; il ne s'y ajoute pas. Par exemple, si la valeur à l'échelle de l'organisation est required et que le groupe Pilot a available, les membres de Pilot obtiennent available. Lorsque vous étendez un plugin d'un groupe pilote à toute l'organisation, définissez la valeur à l'échelle de l'organisation, puis supprimez le paramètre du groupe (définir la valeur à l'échelle de l'organisation empêche définitivement le plugin d'hériter de la valeur par défaut de sa marketplace, comme l'explique Définir un paramètre d'installation).

Un plugin créé via cette API démarre sans paramètre propre ; il hérite donc de la valeur par défaut de sa marketplace : not_available, sauf si quelqu'un a défini une valeur par défaut. La suppression d'un groupe supprime ses paramètres de tous les plugins.

Partages

Les partages déterminent qui peut utiliser un plugin appartenant à un membre. Le propriétaire le partage dans claude.ai avec tous les membres, avec un groupe ou avec des membres nommés. Cette API liste les partages mais ne peut pas les modifier.

Si votre organisation a désactivé un type de partage dans ses paramètres claude.ai, les partages de ce type apparaissent toujours dans la liste mais ne donnent accès à personne tant que ce paramètre est désactivé ; la liste elle-même n'indique pas s'il l'est.

Analyse de contenu

L'« content scanning » (analyse de contenu) est un paramètre d'organisation dans claude.ai. Lorsqu'elle est activée, les versions nouvellement stockées sont analysées (claude.ai en exempte quelques-unes) et le résultat est indiqué dans content_scan ; une version qui n'a pas été analysée, par exemple une version stockée avant l'activation de l'analyse, a content_scan: null. L'analyse n'est pas proposée aux organisations qui utilisent des clés de chiffrement gérées par le client ou la conservation zéro des données.

Tant que l'analyse est activée, un plugin n'est servi aux membres que lorsque l'analyse de sa version servie est completed avec pass ou warn. Pendant l'analyse, ou après qu'elle a échoué, rencontré une erreur ou n'a abouti à aucun verdict, le plugin est retenu et n'est pas servi aux membres, et aucune version antérieure n'est servie à sa place. Une version qui n'a jamais été analysée (content_scan: null) est servie normalement.

Sur un plugin non épinglé, chaque téléversement devient immédiatement la version servie. Les membres perdent le plugin jusqu'à ce que l'analyse de la nouvelle version réussisse, et en restent privés si l'analyse échoue. Si les membres doivent conserver la version actuelle pendant l'analyse d'une nouvelle version, épinglez d'abord le plugin (consultez Versions et version servie).

Après un téléversement, content_scan.status vaut processing et le verdict arrive de manière asynchrone. Lisez la version pour le consulter ; l'objet plugin n'affiche que l'analyse de sa version servie. Changer la version servie pour une version dont l'analyse est encore en cours renvoie 409 scan_pending ; pour une version dont l'analyse a échoué, 400 scan_failed.

Reach (rayon d'action)

reach résume, en une seule valeur, jusqu'où une version s'étend sur les machines des membres et au-delà :

reach prend en compte tout ce que la version déclare, y compris les moniteurs, les serveurs LSP et les paramètres d'application, que components ne liste pas ; une version dont la liste components est vide peut donc tout de même être privileged. Il vaut null pour une version stockée avant l'enregistrement des composants, et pour une version dont le rayon d'action n'a pas pu être déterminé parce que l'un de ses fichiers de skill ou de commande n'a pas pu être lu ; traitez null comme non classé.

Exigences de téléversement

Les téléversements suivent les mêmes règles que les téléversements de plugins dans claude.ai, de sorte que les mêmes archives sont acceptées aux deux endroits.

• Le téléversement est soit une archive .zip ou .plugin unique, soit un ensemble de fichiers individuels. Une archive peut tout envelopper dans un seul dossier de premier niveau.
• Il doit contenir exactement un manifeste, à l'emplacement .claude-plugin/plugin.json, qui doit déclarer un name. Un SKILL.md seul sans manifeste est rejeté.
• Un SKILL.md de premier niveau dont le frontmatter déclare des composants de plugin est fusionné dans le manifeste ; plugin.json l'emporte partout où les deux définissent une valeur.
• name peut contenir des lettres minuscules (de n'importe quel alphabet), des chiffres et des traits d'union, jusqu'à 64 caractères. Les lettres majuscules, les espaces, les traits de soulignement et les autres signes de ponctuation sont rejetés.
• displayName comporte au plus 64 caractères et description au plus 500.
• Chaque SKILL.md nécessite un frontmatter YAML valide avec un name et une description, aucun des deux ne contenant de balises XML telles que <example>. Deux skills, ou deux commandes, ne peuvent pas partager le même nom.
• Aucun fichier ne peut se trouver sous un répertoire bin/ de premier niveau.
• Aucun fichier .zip imbriqué. Les serveurs MCP empaquetés (.mcpb, .dxt) sont autorisés.
• Les chemins de fichiers doivent être relatifs, ne contenir aucun .. et n'utiliser que des lettres, des chiffres, des espaces et _ . - / ( ) ,.
• Le corps de la requête et l'archive décompressée font chacun au plus 200 Mo ; un corps de requête dépassant la limite renvoie 413 (request_too_large) plutôt que 400. Un téléversement comporte au plus 5 000 fichiers, une profondeur de chemin de 12, des chemins de 472 caractères et des noms de fichiers ou de dossiers de 255 caractères.
• Les archives ZIP doivent utiliser la compression DEFLATE ou STORE, et ne peuvent pas être chiffrées ni contenir de liens symboliques.
• Une marketplace contient au plus 500 éléments, en comptant ses plugins et toutes les skills autonomes que les membres y conservent. Cette limite et la limite de 5 000 fichiers sont des valeurs actuelles susceptibles d'être relevées.

Exemples de flux de travail

Publier chaque build depuis un pipeline de publication

Téléversez chaque build étiqueté depuis la CI, et laissez le pipeline décider du moment où un build est servi.

1. Trouvez la marketplace dans laquelle téléverser avec GET /v1/organizations/plugin_marketplaces?owner_type=organization, ou omettez marketplace_id pour utiliser la marketplace de bibliothèque.
2. Lors de la première publication, créez le plugin avec POST /v1/organizations/plugins. À chaque publication ultérieure, notez le latest_version_id du plugin, puis téléversez une version avec POST /v1/organizations/plugins/{plugin_id}/versions. Si la réponse du téléversement est perdue, lisez le plugin et ne réessayez que si latest_version_id n'a pas changé (consultez Réessayer les téléversements).
3. Pour que les membres conservent la version actuelle pendant la vérification de chaque nouveau build, épinglez le plugin une fois en définissant served_version_id sur sa version actuelle. À partir de là, chaque téléversement est stocké sans être servi, et l'épinglage ne peut pas être annulé : chaque build que vous souhaitez servir nécessite l'étape 5.
4. Lorsque l'analyse de contenu est activée, interrogez GET /v1/organizations/plugins/{plugin_id}/versions/{version} jusqu'à ce que content_scan.status ne soit plus processing, et ne promouvez que lorsqu'il vaut completed avec pass ou warn.
5. Promouvez le build avec POST /v1/organizations/plugins/{plugin_id} et {"served_version_id": "<the new version's ID>"}. Pour revenir en arrière, envoyez l'ID de la version précédente de la même manière.

Déployer un plugin auprès d'un groupe pilote, puis de tout le monde

1. Recherchez l'ID du groupe pilote avec GET /v1/organizations/rbac_groups. Cet appel nécessite la portée read:rbac_groups, qui requiert une clé créée pour toutes les organisations liées (consultez la gestion des utilisateurs). Les étapes suivantes nécessitent write:plugins, qui n'agit que sur l'organisation dans laquelle sa clé a été créée ; dans une entreprise comportant plusieurs organisations liées, créez donc cette clé dans l'organisation qui détient le plugin et attribuez-lui les deux portées, ou utilisez une seconde clé créée dans cette organisation pour ces étapes.

2. Attribuez au groupe son propre paramètre, par exemple auto_install, avec POST /v1/organizations/plugins/{plugin_id}/installation_settings/{target}, où {target} est l'ID rbac_group_ du groupe, tandis que la valeur à l'échelle de l'organisation reste not_available. Seuls les membres du groupe obtiennent le plugin.

3. À la fin du pilote, définissez la valeur à l'échelle de l'organisation (cela empêche définitivement le plugin d'hériter de la valeur par défaut de sa marketplace, comme l'explique Définir un paramètre d'installation), puis supprimez le paramètre du groupe afin que le groupe suive à nouveau l'organisation :

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

   Supprimez ensuite le paramètre du groupe avec DELETE /v1/organizations/plugins/{plugin_id}/installation_settings/{target}, où {target} est l'ID du groupe. Le paramètre d'un groupe remplace la valeur à l'échelle de l'organisation pour ses membres au lieu de s'y ajouter ; un paramètre de groupe résiduel à available maintiendrait donc ces membres sur available.

Maintenir un inventaire de sécurité à jour

Exécutez une tâche nocturne qui signale les plugins qui s'étendent au-delà de la session du membre ou qui échouent à leur analyse de contenu.

1. Parcourez les pages de GET /v1/organizations/plugins?limit=100 jusqu'à ce que next_page soit null, en transmettant vous-même le next_page de chaque page comme page plutôt qu'en utilisant un itérateur de liste du SDK, qui peut s'arrêter prématurément sur cette liste (consultez Pagination). Lisez le reach et le content_scan de chaque plugin depuis cette liste à chaque exécution : un verdict d'analyse qui arrive plus tard ne modifie pas updated_at. updated_at vous indique quels plugins ont un nouveau contenu ou une nouvelle version servie depuis la dernière exécution (ce qui justifie un nouveau téléchargement d'archive) ; la nouvelle liste complète est également ce qui permet de détecter les suppressions, car un plugin supprimé par une synchronisation Git ou une suppression de compte disparaît sans événement.
2. Signalez chaque plugin dont le reach vaut remote (il déclare un serveur MCP ou une CLI), ou dont le content_scan.assessment vaut fail ou unknown.
3. Pour chaque plugin signalé, téléchargez l'archive de la version servie pour examen avec GET /v1/organizations/plugins/{plugin_id}/versions/{served_version_id}/content (consultez Télécharger les fichiers d'une version).
4. Pour retirer un plugin aux membres pendant que vous l'examinez, consultez Supprimer un plugin pour les options réversible (appartenant à l'organisation) et définitive.

Plugins

L'objet plugin décrit un plugin situé dans l'une des marketplaces de votre organisation ou dans la marketplace personnelle d'un membre (la réponse du Démarrage rapide en montre un exemple complet). Ses champs display_name, description, manifest_version, content_scan, components et reach décrivent sa version servie, de sorte qu'un seul appel de liste montre ce qui est servi aux membres.

L'objet content_scan :

Un plugin_id dépourvu du préfixe plugin_ renvoie 400. Un plugin_id qui porte le préfixe mais ne correspond à rien, appartient à une autre organisation ou fait référence à une skill autonome renvoie 404.

Lister les plugins

GET /v1/organizations/plugins liste tous les plugins de votre organisation, dans les marketplaces de l'organisation et dans les marketplaces personnelles des membres, triés par created_at décroissant. Filtrez par owner_type (organization ou user), owner_user_id (préfixé par user_ ; les plugins d'un membre, y compris après son départ de l'organisation), marketplace_id, et created_at[gte], created_at[gt], created_at[lte], created_at[lt] (horodatages RFC 3339). Les filtres se combinent avec AND. Un marketplace_id ou un owner_user_id qui ne correspond à rien dans votre organisation renvoie une page vide, et non une erreur. La réponse a la forme présentée dans le Démarrage rapide. Nécessite la portée read:plugins.

client = anthropic.Anthropic()

plugins = client.beta.organization.plugins.list(owner_type="organization", limit=20)

# Récupère automatiquement des pages supplémentaires si nécessaire.
for plugin in plugins:
    print(f"{plugin.id}: {plugin.name}")

Créer un plugin

POST /v1/organizations/plugins crée un plugin appartenant à l'organisation et sa première version en un seul appel ; cette version devient la version servie. Le corps est au format multipart/form-data : files[] est soit une archive .zip ou .plugin unique, soit une partie par fichier, où le nom de fichier de chaque partie est le chemin du fichier au sein du plugin (par exemple .claude-plugin/plugin.json). Les champs facultatifs sont marketplace_id (une marketplace manual appartenant à l'organisation ; par défaut, votre marketplace de bibliothèque, qui est créée lors de la première utilisation) et release_notes (jusqu'à 5 000 caractères, affichées dans l'historique des versions de claude.ai et renvoyées sur la version). Les champs name, display_name, description et manifest_version du plugin proviennent du manifeste téléversé, et le téléversement doit respecter les exigences de téléversement. Lorsque l'analyse de contenu est activée, le content_scan.status de la réponse vaut processing et le verdict arrive de manière asynchrone. Renvoie le plugin. Nécessite la portée write:plugins.

Téléverser une archive :

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

Téléversez des fichiers individuels dans une marketplace nommée. Joignez chaque fichier sous son chemin au sein du plugin (le suffixe ;filename= dans l'exemple cURL, les arguments de nom de fichier dans les exemples de SDK) ; un fichier envoyé sous son seul nom de base entraîne l'impossibilité de trouver le manifeste. Les SDK TypeScript et Java ainsi que la CLI ant ne peuvent pas encore joindre de fichiers sous un chemin ; ces exemples téléversent donc plutôt le plugin sous forme d'une archive unique dans la marketplace :

client = anthropic.Anthropic()

# Un tuple (filename, file) conserve le chemin de chaque fichier dans le plugin ;
# un objet fichier seul serait envoyé sous son seul nom de 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}")

Outre une erreur 400 pour un téléversement qui enfreint les exigences de téléversement (413 pour un corps de requête de plus de 200 Mo) et les réponses communes (une erreur 403 lorsque marketplace_id est la marketplace personnelle d'un membre ; consultez Réponses d'erreur), une création peut échouer avec :

Obtenir un plugin

GET /v1/organizations/plugins/{plugin_id} renvoie un plugin. Nécessite la portée read:plugins.

client = anthropic.Anthropic()

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

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

Modifier la version servie

POST /v1/organizations/plugins/{plugin_id} modifie la version d'un plugin appartenant à l'organisation qui est servie aux membres. Passez une version antérieure pour revenir en arrière, ou une version plus récente pour promouvoir un build qui a été stocké sans être servi. Cela épingle le plugin, et un plugin épinglé ne peut actuellement pas être désépinglé, ni ici ni dans claude.ai (consultez Versions et version servie). Le seul champ modifiable est served_version_id, et il est obligatoire. La modification atteint les membres avant que la réponse ne soit renvoyée et ne crée pas de version. Lorsque l'analyse de contenu est activée, la version doit être une version pouvant être servie aux membres (consultez Analyse de contenu). Passer la version déjà servie sur un plugin épinglé ne change rien ; la passer sur un plugin non épinglé l'épingle sur cette version, de sorte que les téléversements ultérieurs cessent d'être servis automatiquement. Renvoie le plugin. Nécessite la portée 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"
}

Outre les réponses communes (une erreur 403 pour un plugin appartenant à un membre, et 409 scan_pending ou 400 scan_failed pour une version qui ne peut pas être servie aux membres ; consultez Réponses d'erreur), la requête peut échouer avec :

Supprimer un plugin

DELETE /v1/organizations/plugins/{plugin_id} supprime définitivement un plugin et toutes les versions qu'il contient, exactement comme le fait une suppression effectuée par un administrateur dans claude.ai. Cela fonctionne sur n'importe quel plugin d'une marketplace manual, y compris le plugin d'un membre, même si ce membre a depuis quitté l'organisation. Lorsque la suppression renvoie sa réponse, le plugin, ses versions et leurs fichiers ont disparu de toutes les lectures, et le plugin n'est plus servi aux membres. Les paramètres d'installation d'un plugin appartenant à l'organisation sont supprimés avec lui ; les partages d'un plugin appartenant à un membre sont retirés, et le plugin disparaît également pour son propriétaire. Un plugin d'une marketplace synchronisée depuis Git renvoie 400 : supprimez-le du dépôt, ou supprimez la marketplace dans claude.ai. Nécessite la portée write:plugins.

La suppression est irréversible, et il n'existe pas de suppression par version. Pour retirer plutôt un plugin appartenant à l'organisation de manière réversible, définissez son paramètre d'installation à l'échelle de l'organisation sur not_available (un plugin qui héritait de la valeur par défaut de sa marketplace conserve dès lors son propre paramètre), et supprimez (ou définissez sur not_available) chaque paramètre de groupe que liste GET /v1/organizations/plugins/{plugin_id}/installation_settings, car le paramètre d'un groupe remplace la valeur à l'échelle de l'organisation pour ses membres. Envoyez ces écritures l'une après l'autre, et non en parallèle (consultez Définir un paramètre d'installation). Un plugin appartenant à un membre ne peut pas être retiré via cette API autrement qu'en le supprimant, et uniquement si sa marketplace est 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" }

Versions de plugin

Une version de plugin est un instantané immuable des fichiers d'un plugin issu d'un téléversement (la réponse de Créer une version montre un objet complet). Ses champs reflètent, pour cette version, les champs de version servie du plugin (display_name, description, manifest_version, content_scan, components, reach), auxquels s'ajoutent release_notes (tel que fourni avec le téléversement ; affiché dans l'historique des versions de claude.ai) et created_by (la personne qui l'a téléversée).

Un {version} dépourvu du préfixe pluginver_ renvoie 400 (sauf la valeur littérale latest lorsque cela est indiqué). Un identifiant qui porte le préfixe mais n'identifie pas une version de ce plugin renvoie 404.

Lister les versions d'un plugin

GET /v1/organizations/plugins/{plugin_id}/versions liste les versions d'un plugin, triées par created_at décroissant ; le premier élément est la version qu'identifie latest_version_id. limit est compris entre 1 et 1 000. Nécessite la portée read:plugins.

client = anthropic.Anthropic()

versions = client.beta.organization.plugins.versions.list(
    "plugin_01Hq3vX8kZcN2mB7pR4tY9wL", limit=50
)

# Récupère automatiquement les pages suivantes selon les besoins.
for version in versions:
    print(f"{version.id}: {version.manifest_version}")

Créer une version

POST /v1/organizations/plugins/{plugin_id}/versions ajoute une version à un plugin appartenant à l'organisation dans une marketplace manual. Le corps est au format multipart/form-data, avec les mêmes champs files[] et release_notes, les mêmes exigences de téléversement et les mêmes erreurs de fichier, de manifeste, d'archive et de taille que Créer un plugin. Le nom téléversé (le name du manifeste) doit être égal au name du plugin. Si le plugin n'est pas épinglé, la nouvelle version est servie dès qu'elle est stockée ; s'il est épinglé, la version est stockée mais n'est pas servie tant que vous ne la définissez pas comme version servie. Pour le vérifier, comparez l'id de la réponse avec le served_version_id du plugin. Renvoie la version. Nécessite la portée 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"
}

Outre une erreur 400 pour un téléversement qui enfreint les exigences de téléversement (413 pour un corps de requête de plus de 200 Mo) et les réponses communes (une erreur 403 pour un plugin appartenant à un membre ; consultez Réponses d'erreur), la requête peut échouer avec :

Obtenir une version

GET /v1/organizations/plugins/{plugin_id}/versions/{version} renvoie une version. {version} est un ID de version, ou latest pour la version qu'identifie latest_version_id au moment de la requête. Nécessite la portée 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}")

Télécharger les fichiers d'une version

GET /v1/organizations/plugins/{plugin_id}/versions/{version}/content télécharge les fichiers d'une version sous la forme de l'archive .zip stockée (Content-Type: application/zip). L'archive est renvoyée quel que soit le résultat de son analyse de contenu, ce qui vous permet d'inspecter les versions qui ne sont pas servies aux membres. Elle est servie exactement telle qu'elle a été stockée ; ainsi, pour un plugin appartenant à l'organisation dans une marketplace manual, vous pouvez la téléverser à nouveau sans modification en tant que nouvelle version, à condition qu'elle respecte les exigences de téléversement actuelles. {version} doit être un ID de version, et non latest : lisez d'abord le served_version_id ou le latest_version_id du plugin, ou résolvez latest avec GET /v1/organizations/plugins/{plugin_id}/versions/latest. Le nom de fichier Content-Disposition est dérivé du nom du plugin et n'est pas unique ; nommez les fichiers enregistrés d'après le plugin et l'ID de version. Nécessite la portée read:plugins.

Le téléchargement de l'archive d'un plugin appartenant à un membre enregistre un événement claude_plugin_archive_accessed dans l'Activity Feed de la Compliance API, qui identifie par ID la clé (en tant que api_actor), le plugin et sa marketplace, la version et le membre propriétaire ; il ne contient aucun nom. Le téléchargement de l'archive d'un plugin appartenant à l'organisation n'enregistre rien.

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

Paramètres d'installation de plugin

Ces points de terminaison s'appliquent aux plugins appartenant à l'organisation. Ils renvoient 404 pour un plugin appartenant à un membre, qui dispose à la place de partages. {target} est la valeur littérale organization pour le paramètre à l'échelle de l'organisation du plugin, ou l'ID rbac_group_ d'un groupe pour le paramètre de ce groupe ; toute autre valeur renvoie 400. Les ID de groupe proviennent de GET /v1/organizations/rbac_groups (portée read:rbac_groups ; consultez Gestion des utilisateurs). Un paramètre n'a pas d'id propre : il est adressé par (plugin_id, target), et aucun acteur n'y est enregistré (l'acteur figure sur son événement d'activité plugin_installation_preference_updated).

Lister les paramètres d'installation d'un plugin

GET /v1/organizations/plugins/{plugin_id}/installation_settings liste les paramètres que détient un plugin appartenant à l'organisation, triés par created_at décroissant : son propre paramètre à l'échelle de l'organisation (absent tant qu'il hérite de la valeur par défaut de sa marketplace) et le paramètre de chaque groupe. Filtrez par target_type (organization ou rbac_group). Nécessite la portée read:plugins.

client = anthropic.Anthropic()

settings = client.beta.organization.plugins.installation_settings.list(
    "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
)

# Récupère automatiquement des pages supplémentaires si nécessaire.
for setting in settings:
    print(f"{setting.plugin_id}: {setting.installation_preference}")

Définir un paramètre d'installation

POST /v1/organizations/plugins/{plugin_id}/installation_settings/{target} définit le paramètre d'installation d'une cible pour un plugin appartenant à l'organisation, en le créant ou en modifiant la valeur qu'il contient déjà. Le seul champ du corps est installation_preference (required, auto_install, available ou not_available), et il est obligatoire. Définir la valeur que la cible contient déjà ne change rien. Définir la cible organization met fin à l'héritage, par le plugin, de la valeur par défaut de sa marketplace (organization_installation_preference_inherited devient false), même lorsque la valeur est identique à la valeur par défaut ; cette opération est irréversible, car le paramètre à l'échelle de l'organisation ne peut pas être supprimé, de sorte que le plugin ne suit plus les modifications ultérieures de la valeur par défaut de la marketplace. Une cible de groupe doit être un groupe que votre organisation peut voir dans GET /v1/organizations/rbac_groups, sinon la requête renvoie 404. La modification n'altère pas le updated_at du plugin ; elle est enregistrée dans l'Activity Feed. Renvoie le paramètre. Nécessite la portée write:plugins.

Envoyez les écritures de paramètres d'installation d'un plugin une à la fois. Si plusieurs écritures pour le même plugin arrivent en même temps, le serveur les traite l'une après l'autre et peut répondre à certaines d'entre elles par 503 au lieu de les appliquer. Cette réponse 503 contient x-should-retry: true, et l'écriture peut être répétée sans risque : attendez une seconde ou deux, puis renvoyez-la.

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

Supprimer le paramètre d'installation d'un groupe

DELETE /v1/organizations/plugins/{plugin_id}/installation_settings/{target} supprime le paramètre d'un groupe pour un plugin appartenant à l'organisation. Les membres de ce groupe se rabattent sur la valeur à l'échelle de l'organisation, ou sur le paramètre d'un autre de leurs groupes. Le paramètre à l'échelle de l'organisation ne peut pas être supprimé une fois défini, exactement comme dans claude.ai (un {target} valant organization renvoie 400) ; modifiez plutôt sa valeur. Un groupe qui ne détient aucun paramètre pour ce plugin renvoie 404. La réponse contient la clé composite à la place d'un id. Nécessite la portée 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" }
}

Partages de plugin

Les partages n'existent que sur les plugins appartenant à des membres et sont en lecture seule dans cette API (consultez Partages).

Lister les partages d'un plugin

GET /v1/organizations/plugins/{plugin_id}/shares liste les destinataires avec lesquels le propriétaire d'un plugin appartenant à un membre l'a partagé, triés par granted_at décroissant : tous les membres (organization), un groupe (rbac_group) ou un membre nommé (organization_member). Filtrez par target_type. Un plugin que son propriétaire n'a pas partagé renvoie une liste vide ; un plugin appartenant à l'organisation renvoie 404. Les partages sont en lecture seule dans cette API, et un partage listé ne donne accès que tant que ce type de partage est activé pour votre organisation dans claude.ai (consultez Partages). granted_at correspond au moment où le partage a été accordé ; si le propriétaire modifie ultérieurement le partage dans claude.ai, il s'agit du moment de cette modification. Nécessite la portée read:plugins.

client = anthropic.Anthropic()

shares = client.beta.organization.plugins.shares.list("plugin_01Mr2wP7sU3aJ8vX5cY6nS9t")

# Récupère automatiquement les pages suivantes selon les besoins.
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
}

Marketplaces de plugins

Cette API lit les marketplaces et définit le paramètre d'installation par défaut d'une marketplace de l'organisation ; les marketplaces elles-mêmes sont créées, connectées à un dépôt et supprimées dans 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 dépourvu du préfixe marketplace_ renvoie 400. Un identifiant qui porte le préfixe mais ne se résout pas, ou qui appartient à une autre organisation, renvoie 404.

Lister les marketplaces

GET /v1/organizations/plugin_marketplaces liste les marketplaces de votre organisation et les marketplaces personnelles des membres, triées par created_at décroissant. Utilisez-le pour trouver l'ID d'une marketplace, afin de filtrer la liste des plugins par celle-ci ou d'y téléverser, avant même qu'elle ne contienne un plugin. La marketplace de bibliothèque apparaît dès que quelque chose y a été créé pour la première fois, dans claude.ai ou via cette API. Filtrez par owner_type (organization ou user) et par source. limit est compris entre 1 et 1 000. Nécessite la portée read:plugins.

client = anthropic.Anthropic()

marketplaces = client.beta.organization.plugin_marketplaces.list(
    owner_type="organization"
)

# Récupère automatiquement les pages suivantes selon les besoins.
for marketplace in marketplaces:
    print(f"{marketplace.id}: {marketplace.name}")

Obtenir une marketplace

GET /v1/organizations/plugin_marketplaces/{marketplace_id} renvoie une marketplace. Nécessite la portée read:plugins.

client = anthropic.Anthropic()

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

print(f"id: {marketplace.id}")
print(f"name: {marketplace.name}")

Définir le paramètre d'installation par défaut d'une marketplace

POST /v1/organizations/plugin_marketplaces/{marketplace_id} définit le paramètre d'installation par défaut d'une marketplace appartenant à l'organisation. Chaque plugin de la marketplace sans paramètre propre à l'échelle de l'organisation indique cette valeur par défaut comme son organization_installation_preference, y compris les plugins ajoutés ultérieurement. Cela fonctionne pour les marketplaces manual et synchronisées ; la marketplace personnelle d'un membre renvoie 403. Le seul champ modifiable est default_installation_preference, et il est obligatoire. Il ne peut pas être redéfini sur null : une fois qu'une marketplace a une valeur par défaut, elle en conserve une, comme dans claude.ai. Une modification est enregistrée sous la forme d'un seul événement marketplace_updated, sans événement par plugin, et n'altère le updated_at d'aucun plugin. Définir la valeur déjà définie ne change rien, à une exception près : une marketplace dont la valeur par défaut n'a jamais été définie indique not_available mais ne détient aucun paramètre, de sorte que sa première écriture (même not_available) compte comme une modification. Renvoie la marketplace. Nécessite la portée 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}")

Valider le contenu d'une marketplace

Deux points de terminaison indiquent ce que ferait une synchronisation du contenu de marketplace fourni, sans rien connecter ni stocker : POST /v1/organizations/plugin_marketplaces/validate_repository lit un dépôt GitHub public, et POST /v1/organizations/plugin_marketplaces/validate_archive lit un .zip du répertoire de la marketplace que vous téléversez. Les deux renvoient le même rapport : si marketplace.json est bien formé, quels plugins seraient ignorés et pourquoi, et quels plugins seraient synchronisés avec une partie de leur contenu omise. Les vérifications sont celles qu'exécute une véritable synchronisation. Les problèmes liés au contenu sont signalés dans le rapport, et non sous forme d'erreurs HTTP : la requête réussit avec valid: false, même lorsque le dépôt ou l'archive ne peut pas du tout être lu. Une validation compte comme une lecture, et les deux points de terminaison sont en outre limités ensemble à 10 validations par minute par organisation (consultez Limitation de débit) ; ils n'enregistrent rien dans l'Activity Feed. Une validation peut prendre jusqu'à 120 secondes avant de renvoyer une réponse ; définissez donc le délai d'expiration de votre client au-delà de cette valeur. Les deux points de terminaison nécessitent la portée read:plugins ou write:plugins (read:org_audit et read:compliance_org_data ne les accordent pas).

Le dépôt, ainsi que toute source de plugin située en dehors de celui-ci sur GitHub, sont lus de manière anonyme ; un dépôt privé ou une source de plugin privée est donc signalé comme introuvable. Les sources de plugin hébergées ailleurs que sur GitHub ne sont pas récupérées ; un tel plugin reçoit normalement un avertissement marketplace_validate_source_not_checked et est vérifié lorsque la marketplace est effectivement synchronisée. Si le dépôt est, ou si l'archive désigne, une marketplace qu'Anthropic synchronise dans chaque organisation, des règles plus strictes s'appliquent : chaque source de plugin située en dehors de la marketplace doit être épinglée à un SHA de commit complet, les sources non épinglées ou hébergées sur un hôte non pris en charge sont signalées comme des erreurs de plugin, et la branche lue est par défaut celle depuis laquelle cette marketplace est synchronisée.

validate_repository accepte un corps JSON avec deux champs : repository_url, l'URL https:// d'un dépôt public sur github.com (obligatoire), et ref, un nom de branche ou un SHA de commit complet de 40 caractères (facultatif ; lorsqu'il est omis ou null, la branche qu'une synchronisation lirait, généralement la branche par défaut du dépôt). validate_archive accepte un corps multipart/form-data avec exactement une partie, archive, envoyée en tant que partie fichier avec un nom de fichier : un .zip du répertoire de la marketplace, de 32 Mo au maximum, dont le contenu se trouve à la racine ou est enveloppé dans un seul dossier (comme le produit un téléchargement depuis un hôte Git), avec une compression DEFLATE ou STORE uniquement. Aucun autre champ de formulaire n'est accepté.

Valider un dépôt public sur une branche :

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

Validez plutôt une copie locale du répertoire de la marketplace, sous forme de .zip ; la réponse est le même rapport :

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

Les problèmes liés au contenu ne font jamais échouer la requête. Outre les réponses communes à tous les points de terminaison (une erreur 403 pour une clé qui ne dispose que de read:org_audit ou read:compliance_org_data ; consultez Réponses d'erreur et Limitation de débit), la requête elle-même peut échouer avec :

Codes de rapport

Chaque constat d'un rapport possède un code stable : manifest_error_code lorsque rien n'a pu être validé, error_code sur chaque entrée plugin_errors, et error_code sur chaque avertissement. Lorsqu'un plugin présente plusieurs problèmes, error_code est celui du premier et error regroupe leurs messages. De nouveaux codes peuvent être ajoutés ; un manifest_error_code non reconnu signifie toujours que le contenu n'a pas pu être validé, un code non reconnu sur une entrée plugin_errors signifie toujours que le plugin serait ignoré, et un code non reconnu sur un avertissement signifie toujours que le plugin serait synchronisé. Ces codes indiquent des conditions transitoires, de sorte que la même requête peut réussir plus tard : 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 et, généralement, marketplace_validate_deadline_exceeded.

Valeurs non reconnues

Chaque valeur de chaîne de cette page (types de composants, reach, champs d'analyse, source de marketplace, codes d'erreur) peut recevoir de nouvelles valeurs à tout moment. Traitez une valeur que vous ne reconnaissez pas comme vous le feriez pour toute chaîne inconnue, plutôt que de provoquer un échec.

Limitation de débit

Les requêtes de lecture (chaque point de terminaison GET de cette page) partagent une « rate limit » (limite de débit) de 300 requêtes par minute par organisation, et les requêtes d'écriture (création d'un plugin ou d'une version, modification de la version servie, suppression, définition ou suppression d'un paramètre d'installation, et mise à jour d'une marketplace) partagent une limite de 60 requêtes par minute par organisation. Une validation de marketplace (via l'un ou l'autre point de terminaison) compte comme une lecture, et les validations sont en outre limitées à 10 par minute par organisation sur l'ensemble des deux points de terminaison ; les deux limites sont vérifiées avant la lecture du corps de la requête. Ces limites sont comptabilisées sur l'ensemble des clés de votre organisation et sont distinctes des autres limites de l'Admin API de votre organisation. Les requêtes dépassant une limite renvoient 429 Too Many Requests avec un en-tête retry-after. Les réponses incluent des en-têtes anthropic-ratelimit-requests-* pour la limite applicable (pour la validation de marketplace, sa limite de 10 par minute ; pour une réponse 429, la limite qui a refusé la requête).

Un téléversement, une modification de la version servie ou une validation peut également renvoyer 429 avec retry-after lorsque le service n'a brièvement pas la capacité d'en traiter un autre, et un téléversement renvoie 429 lorsque votre organisation a dépassé son débit d'analyse de contenu. Gérez tous ces cas de la même manière : attendez la durée indiquée par retry-after, puis réessayez. Indépendamment de ces limites, envoyez les écritures de paramètres d'installation pour un même plugin une à la fois : lorsque plusieurs arrivent en même temps, certaines peuvent recevoir une réponse 503 avec x-should-retry: true, et celles-ci peuvent être renvoyées sans risque après une seconde ou deux (consultez Définir un paramètre d'installation).

Pagination

Les points de terminaison de liste utilisent un « opaque cursor » (curseur opaque). La première requête renvoie jusqu'à limit lignes ainsi qu'un curseur next_page ; transmettez le curseur sans modification comme paramètre page de la requête suivante, et répétez jusqu'à ce que next_page soit null. Traitez la chaîne du curseur comme opaque : ne l'analysez pas, ne la modifiez pas et ne la construisez pas vous-même. Lister les plugins peut renvoyer une page contenant moins de limit plugins, voire aucun, alors que next_page est toujours défini ; continuez donc à demander des pages jusqu'à ce que next_page soit null. Les itérateurs de liste des SDK récupèrent les pages suivantes au fil de l'itération mais s'arrêtent à la première page vide ; sur la liste des plugins, ils peuvent donc se terminer prématurément. Lorsque vous avez besoin de tous les plugins, comme dans le workflow d'inventaire de sécurité, demandez chaque page vous-même et transmettez son next_page comme page.

limit vaut 20 par défaut et a un minimum de 1. Le maximum est de 100 pour les plugins, les paramètres d'installation et les partages, et de 1 000 pour les versions et les marketplaces. Chaque liste est triée de la plus récente à la plus ancienne.

Réponses d'erreur

Les réponses d'erreur suivent la structure standard documentée dans Erreurs. Indiquez le request_id figurant dans le corps de la réponse lorsque vous contactez le support.

Lorsqu'un même statut a plusieurs causes que vous traiteriez différemment, l'erreur contient également error.details.error_code, ainsi que error.details.plugin_id ou error.details.plugin_version_id lorsque la cause en implique un :

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

De nouveaux codes peuvent être ajoutés. Traitez un code que vous ne reconnaissez pas de la même manière que son statut.

Nouvelles tentatives de téléversement

Aucun endpoint n'accepte d'Idempotency-Key. La modification de la version servie, la définition d'un paramètre d'installation et la définition d'une valeur par défaut de marketplace peuvent être répétées sans risque. Une suppression répétée, ou un retrait répété du paramètre d'installation d'un groupe, renvoie 404.

Un téléversement qui renvoie une erreur n'a rien stocké, à une exception près : 503 avec error_code: "registration_pending". Après avoir stocké les fichiers d'un téléversement, le serveur enregistre les skills de la nouvelle version auprès de claude.ai, ce qui les rend utilisables par les membres ; registration_pending signifie que les fichiers ont été stockés mais que cette dernière étape n'a pas abouti. Téléverser à nouveau les mêmes fichiers la termine (et stocke une version supplémentaire, identique) :

• Sur POST /v1/organizations/plugins, le plugin a bien été créé, et la réponse contient x-should-retry: false : ne renvoyez pas la création (un renvoi retourne 409 plugin_name_taken) ; téléversez plutôt les mêmes fichiers en tant que version de details.plugin_id.
• Sur POST /v1/organizations/plugins/{plugin_id}/versions, la version a bien été stockée (details.plugin_version_id) ; renvoyez la même requête lorsque la réponse contient x-should-retry: true, et ne le faites pas lorsqu'elle contient false.

Si la réponse d'une création est perdue, relancez-la : la nouvelle tentative renvoie 409 plugin_name_taken avec l'ID du plugin dans details.plugin_id, et vous poursuivez avec ce plugin. Relancer une création de version dont la réponse a été perdue stocke une seconde version identique. Pour éviter cela, enregistrez le latest_version_id du plugin avant chaque téléversement ; si une réponse est perdue, lisez le plugin et ne relancez que si latest_version_id n'a pas changé.

Événements du flux d'activité

Chaque écriture effectuée via cette API est enregistrée dans le flux d'activité de l'API Compliance de votre organisation, attribuée à la clé API en tant qu'api_actor portant son ID apikey_. Le même acteur apparaît dans created_by sur les plugins et les versions que la clé crée.

Les ID de plugin, de version et de marketplace figurant dans ces événements sont les mêmes ID que ceux renvoyés par cette API. plugin_installation_preference_updated identifie le plugin par son name et son marketplace_id plutôt que par son id.

La modification de la valeur par défaut d'une marketplace enregistre un seul événement marketplace_updated et aucun événement par plugin, même si elle modifie la valeur de chaque plugin qui hérite de cette valeur par défaut. Les lectures ne sont pas enregistrées, à l'exception des téléchargements de l'archive d'un plugin appartenant à un membre. Une écriture qui ne modifie rien n'enregistre rien.

Les partages accordés ou retirés dans claude.ai apparaissent dans le flux sous forme d'événements role_assignment_granted et role_assignment_revoked. Cette API ne signale pas les suppressions : un plugin supprimé est simplement absent de la liste suivante. Un plugin retiré par une synchronisation Git, par la suppression de sa marketplace (un seul événement marketplace_deleted), ou par la suppression du compte d'un membre ou de l'organisation n'émet aucun événement par plugin ; listez donc à nouveau l'inventaire complet périodiquement pour détecter les retraits.

Clés de chiffrement gérées par le client

Si votre organisation utilise une « customer-managed encryption key » (clé de chiffrement gérée par le client), les champs description, release_notes et components ainsi que les fichiers d'une version sont chiffrés avec celle-ci. Tant que la clé n'est pas disponible :

• Les lectures et les listes réussissent toujours, avec description, release_notes et components renvoyés à null.
• Les téléchargements d'archives, les créations, les créations de versions et les modifications de la version servie renvoient 400 avec cmek_key_disabled ou cmek_key_network_blocked.
• La suppression d'un plugin dans la marketplace de la bibliothèque renvoie 400 cmek_key_disabled et ne supprime rien, car ses skills doivent d'abord être retirées de claude.ai, ce qui nécessite la clé. Les autres suppressions, les paramètres d'installation et les valeurs par défaut des marketplaces fonctionnent normalement.

Le rétablissement de la clé lève toutes ces restrictions.

Voir aussi