API Plugin
Inventarisasi dan kelola plugin di organisasi Claude Enterprise Anda: unggah plugin dan versi, pilih versi yang disajikan kepada anggota, kendalikan siapa yang dapat menggunakan setiap plugin, unduh file plugin untuk ditinjau, dan validasi marketplace sebelum Anda menghubungkannya.
Plugins API memungkinkan Anda melakukan hal-hal berikut:
- Menginventarisasi plugin di organisasi Claude Enterprise Anda
- Menerbitkan plugin dan versi baru dari pipeline Anda sendiri
- Memilih versi mana yang disajikan kepada anggota
- Mengendalikan siapa yang dapat menggunakan setiap plugin
- Mengunduh file plugin untuk ditinjau
- Memeriksa marketplace Git sebelum Anda menghubungkannya
Untuk pelaporan penggunaan plugin (plugin dan skill mana yang digunakan anggota, dan seberapa sering), lihat Analytics API.
Endpoint
API ini menyediakan 18 endpoint di lima sumber daya:
| Sumber daya | Endpoint |
|---|---|
| Plugin: mencantumkan plugin di organisasi, mengunggah plugin baru, mencari satu plugin, memilih versi yang disajikan kepada anggota (rollback atau promosi), menghapus satu plugin | GET /v1/organizations/pluginsPOST /v1/organizations/pluginsGET /v1/organizations/plugins/{plugin_id}POST /v1/organizations/plugins/{plugin_id}DELETE /v1/organizations/plugins/{plugin_id} |
| Versi plugin: mencantumkan riwayat versi plugin, mengunggah versi baru, mencari satu versi, mengunduh file suatu versi | GET /v1/organizations/plugins/{plugin_id}/versionsPOST /v1/organizations/plugins/{plugin_id}/versionsGET /v1/organizations/plugins/{plugin_id}/versions/{version}GET /v1/organizations/plugins/{plugin_id}/versions/{version}/content |
| Pengaturan instalasi: membaca siapa yang dapat menggunakan plugin milik organisasi, mengaturnya untuk seluruh organisasi atau untuk satu grup, menghapus salah satu pengaturan tersebut | GET /v1/organizations/plugins/{plugin_id}/installation_settingsPOST /v1/organizations/plugins/{plugin_id}/installation_settings/{target}DELETE /v1/organizations/plugins/{plugin_id}/installation_settings/{target} |
| Berbagi: membaca dengan siapa seorang anggota telah membagikan plugin miliknya sendiri (hanya-baca) | GET /v1/organizations/plugins/{plugin_id}/shares |
| Marketplace plugin: menemukan ID marketplace, mencari satu marketplace, menetapkan pengaturan instalasi default untuk plugin-pluginnya, memeriksa konten marketplace sebelum menghubungkannya | GET /v1/organizations/plugin_marketplacesGET /v1/organizations/plugin_marketplaces/{marketplace_id}POST /v1/organizations/plugin_marketplaces/{marketplace_id}POST /v1/organizations/plugin_marketplaces/validate_repositoryPOST /v1/organizations/plugin_marketplaces/validate_archive |
Plugin yang dipublikasikan Anthropic tidak diinventarisasi; penggunaannya dilaporkan oleh Analytics API. Marketplace dibuat, dihubungkan ke repositori, dan dihapus di claude.ai, bukan melalui API ini.
Prasyarat
- Organisasi Anda harus menggunakan paket Claude Enterprise.
- Pemilik utama Anda membuat kunci Admin API dengan cakupan
read:plugins, cakupanwrite:plugins, atau keduanya di claude.ai > Pengaturan organisasi > API. Lihat Membuat kunci untuk organisasi Claude Enterprise. - Setiap permintaan membawa tiga header:
x-api-key,anthropic-version: 2026-10-21, dananthropic-beta: ce-plugins-2026-09-01.
Di Python, TypeScript, C#, Go, Java, PHP, dan Ruby, SDK menyediakan endpoint ini di bawah client.beta.organization, dan CLI ant di bawah ant beta:organization; keduanya mengirimkan header anthropic-version dan anthropic-beta untuk Anda. Contoh-contoh di halaman ini membaca kunci Admin API dari variabel lingkungan ANTHROPIC_API_KEY. Jika SDK atau CLI mengambil halaman tambahan untuk Anda, limit menentukan ukuran halaman, bukan total (lihat Paginasi).
Kunci API adalah milik organisasi dan tetap berfungsi setelah orang yang membuatnya keluar. Jangan bagikan kunci tersebut atau memasukkannya ke kontrol sumber.
Mulai cepat
Cantumkan plugin di marketplace milik organisasi Anda sendiri, dimulai dari yang terbaru:
client = anthropic.Anthropic()
plugins = client.beta.organization.plugins.list(owner_type="organization", limit=20)
# Secara otomatis mengambil halaman berikutnya sesuai kebutuhan.
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"
}Dalam contoh ini plugin disematkan ke versi sebelumnya: versi yang lebih baru (latest_version_id) sudah disimpan tetapi belum disajikan.
Cakupan
| Cakupan | Memberikan |
|---|---|
read:plugins | Setiap endpoint GET di halaman ini, termasuk unduhan arsip, ditambah validasi marketplace. |
write:plugins | Setiap endpoint POST dan DELETE di halaman ini: membuat plugin, membuat versi, mengubah versi yang disajikan, menghapus plugin, menetapkan dan menghapus pengaturan instalasi, dan menetapkan default marketplace, ditambah validasi marketplace. Cakupan ini tidak memberikan akses baca. |
read:org_audit | Cakupan hanya-baca untuk integrasi audit keamanan: setiap endpoint GET di halaman ini, termasuk unduhan arsip, ditambah endpoint baca manajemen pengguna dan Compliance API. Cakupan ini tidak memberikan validasi marketplace atau operasi tulis apa pun. |
read:compliance_org_data | Cakupan Compliance API untuk metadata organisasi (nama, jenis, peran, dan grup) dan pengaturan efektif. Memberikan setiap endpoint GET di halaman ini, persis seperti read:org_audit, sehingga Compliance Access Key dapat membaca plugin tanpa kunci kedua. Cakupan ini tidak memberikan validasi marketplace atau operasi tulis apa pun. |
Sebuah kunci dapat membawa beberapa cakupan. Integrasi yang mengunggah plugin lalu membacanya kembali memerlukan read:plugins dan write:plugins. Di mana pun halaman ini menyatakan bahwa suatu endpoint memerlukan cakupan read:plugins, kunci dengan read:org_audit atau read:compliance_org_data juga berfungsi.
Akses ke file plugin anggota
Masing-masing cakupan baca ini (read:plugins, read:org_audit, dan read:compliance_org_data) dapat mengunduh file plugin di marketplace pribadi anggota, termasuk file yang tidak ditampilkan oleh pengaturan admin claude.ai, dan kunci read:org_audit atau read:compliance_org_data yang terikat ke organisasi induk Anda dapat melakukan hal ini di organisasi mana pun di bawahnya yang memiliki akses ke API ini, dengan meneruskan organization_id (lihat Membaca organisasi lain di bawah induk yang sama). Setiap unduhan tersebut mencatat peristiwa claude_plugin_archive_accessed di Activity Feed Compliance API, yang mengidentifikasi kunci, plugin, versi, dan anggota (lihat Peristiwa Activity Feed). Unduhan plugin milik organisasi tidak dicatat.
Membaca organisasi lain di bawah induk yang sama
Kunci read:plugins dan write:plugins hanya membaca dan menulis organisasi tempat kunci tersebut dibuat. Sebagian perusahaan memiliki beberapa organisasi Claude yang ditautkan di bawah satu organisasi induk. Kunci read:org_audit atau read:compliance_org_data yang dibuat untuk semua organisasi tertaut juga dapat membaca organisasi tertaut mana pun yang memiliki akses ke API ini. Untuk membacanya, teruskan ID-nya dalam parameter query organization_id pada endpoint GET mana pun di halaman ini. ID tersebut adalah UUID organisasi yang ditampilkan di pengaturan claude.ai (bentuk berawalan org_ juga diterima). Tanpa parameter tersebut, kunci membaca organisasi tempat kunci itu dibuat. Kunci yang tidak memiliki organisasi sendiri harus selalu meneruskan organization_id. 404 berarti organisasi yang disebutkan tidak berada di bawah induk kunci atau API tidak tersedia untuknya; nilai yang bukan UUID atau ID org_ mengembalikan 400. Kunci lain apa pun yang menyebutkan organisasi selain miliknya sendiri mendapatkan 404. Operasi tulis tidak menerima organization_id.
Konsep utama
Plugin dan komponen
Plugin adalah paket yang memperluas Claude untuk anggota organisasi Anda. Plugin berisi kombinasi apa pun dari komponen berikut:
| Komponen | Apa itu |
|---|---|
| Skill | Instruksi dan file yang dimuat Claude ketika suatu tugas memerlukannya. |
| Perintah | Prompt tersimpan yang dijalankan anggota dengan mengetik / diikuti nama command tersebut. |
| Agen | Asisten pembantu dengan instruksinya sendiri, yang dapat menerima sebagian tugas dari Claude. |
| Hook | Perintah yang berjalan secara otomatis ketika suatu event terjadi dalam sesi, seperti sebelum Claude menggunakan alat. |
| Server MCP | Koneksi dari Claude ke alat dan data di sistem lain (Model Context Protocol). |
| CLI | Program baris perintah yang diizinkan plugin untuk dijalankan oleh Claude. |
Setiap plugin memiliki manifest di .claude-plugin/plugin.json. name pada manifest menjadi name plugin: pengenal huruf kecil yang unik di dalam marketplace-nya.
Marketplace
Marketplace adalah wadah plugin. Setiap marketplace memiliki pemilik dan sumber.
- Pemilik. Organisasi memiliki marketplace-nya sendiri. Setiap anggota juga dapat memiliki marketplace pribadi.
- Sumber.
manualberarti plugin diunggah, di claude.ai atau, untuk marketplace organisasi, melalui API ini.github,gitlab, danpublic_gitberarti plugin disinkronkan dari repositori Git yang dihubungkan oleh pemilik. Tidak ada yang dapat diunggah ke marketplace yang disinkronkan, dan API ini tidak dapat menghapus pluginnya, karena sinkronisasi berikutnya akan membatalkan perubahan mana pun. Sebagai gantinya, ubah repositorinya.
Library marketplace (marketplace pustaka) organisasi Anda adalah marketplace manual milik organisasi yang menjadi tujuan unggahan ketika Anda tidak menyebutkan marketplace. Marketplace ini dibuat saat pertama kali sesuatu diunggah ke sana.
Plugin milik organisasi dan milik anggota
owner.type pada plugin menyatakan di marketplace milik siapa plugin tersebut berada:
organization: Anda dapat mengelolanya melalui API ini, kecuali bahwa plugin di marketplace yang disinkronkan dari Git tidak dapat menerima unggahan atau dihapus di sini.user: plugin berada di marketplace pribadi seorang anggota. Anda dapat membaca detailnya dan mengunduh filenya, serta menghapusnya jika marketplace-nyamanual. Mengunggah versi dan memilih versi yang disajikan mengembalikan403. Berbagi hanya dikelola oleh anggota tersebut, di claude.ai.
Menghapus anggota dari organisasi tidak menghapus plugin mereka. Plugin tersebut tetap berada di inventaris di bawah user_id anggota, dan filter owner_user_id masih menemukannya, sehingga Anda dapat meninjau dan menghapus konten anggota yang telah keluar. Plugin tersebut dihapus dari inventaris ketika akun anggota dihapus.
Versi dan versi yang disajikan
Setiap unggahan membuat versi baru yang tidak dapat diubah, baik berasal dari API ini, dari claude.ai, maupun dari sinkronisasi Git. Plugin memiliki dua penunjuk ke versinya:
latest_version_id: versi terbaruserved_version_id: versi yang disajikan kepada anggota
Secara default served_version_pinned bernilai false: versi yang disajikan biasanya mengikuti versi terbaru. Ketika pemindaian konten aktif, versi yang disimpan di claude.ai mungkin menunggu hasil pemindaian kontennya: versi tersebut disimpan tetapi tidak langsung disajikan. Halaman ini menggunakan kata “menunggu” hanya untuk versi yang disimpan di claude.ai, bukan untuk versi yang diterbitkan anggota atau administrator ke dalam plugin. Selama pemindaian aktif, versi yang menunggu hanya disajikan ketika content_scan-nya menunjukkan completed dengan pass atau warn. Selama sebuah versi menunggu, served_version_id menyebutkan versi yang lebih lama daripada latest_version_id. Jangan melakukan polling hingga kedua ID cocok: keduanya mungkin tetap berbeda, misalnya ketika pemindaian gagal.
Memilih versi dengan POST /v1/organizations/plugins/{plugin_id} akan menyematkan (“pin”) plugin (served_version_pinned: true). Begitu pula ketika administrator memilih versi di claude.ai, atau menerima permintaan anggota untuk memublikasikan ke plugin tersebut. Sejak saat itu, unggahan baru disimpan dan memajukan latest_version_id, tetapi anggota tetap mendapatkan versi yang disematkan hingga Anda mengarahkan served_version_id ke versi lain. Plugin yang kedua penunjuknya berbeda memiliki versi tersimpan yang tidak sedang disajikan.
Hal ini memungkinkan pipeline rilis mengunggah setiap build, mengujinya, lalu mempromosikannya. Agar pipeline Anda menentukan kapan setiap build disajikan, sematkan plugin sekali dengan mengatur served_version_id ke versinya saat ini; sejak saat itu, promosikan setiap build yang ingin Anda sajikan. Dengan pemindaian konten aktif, penyematan pertama tersebut mengembalikan 409 scan_pending selama content_scan versi saat ini bernilai processing, dan 400 scan_failed jika pemindaian bernilai fail, unknown, atau errored (warn diterima). Plugin yang telah disematkan tidak dapat dilepas sematannya, baik di sini maupun di claude.ai.
Untuk melakukan rollback, tetapkan served_version_id ke versi sebelumnya. Maju ke versi yang lebih baru dengan cara yang sama.
Aturan ini menjelaskan plugin milik organisasi. Versi yang disajikan dari plugin milik anggota dikendalikan oleh pemiliknya di claude.ai.
Pengaturan instalasi
Pengaturan instalasi menentukan siapa yang dapat menggunakan plugin milik organisasi. Setiap pengaturan memiliki salah satu dari empat nilai, yang dibawa dalam field bernama installation_preference (dan, pada objek plugin dan marketplace, organization_installation_preference dan default_installation_preference):
| Nilai | Yang dilihat anggota |
|---|---|
required | Plugin terinstal dan tidak dapat dihapus. |
auto_install | Plugin terinstal dan dapat dihapus. |
available | Plugin dapat diinstal sesuai permintaan. |
not_available | Plugin disembunyikan. |
Sebuah plugin dapat memiliki pengaturan tingkat organisasi dan satu pengaturan untuk setiap grup (grup yang dikelola di Manajemen pengguna untuk kontrol akses berbasis peran). Seorang anggota mendapatkan nilai berdasarkan aturan berikut:
- Nilai tingkat organisasi adalah pengaturan tingkat organisasi milik plugin itu sendiri jika ada, jika tidak maka default marketplace-nya, jika tidak maka
not_available. Plugin melaporkan nilai ini diorganization_installation_preference, denganorganization_installation_preference_inherited: trueselama nilai tersebut berasal dari default marketplace. - Anggota yang tidak termasuk dalam grup mana pun yang memiliki pengaturan untuk plugin tersebut mendapatkan nilai tingkat organisasi.
- Anggota yang termasuk dalam satu atau lebih grup yang memiliki pengaturan mendapatkan pengaturan paling permisif dari grup-grup tersebut sebagai gantinya, dengan urutan
required,auto_install,available,not_available.
Pengaturan grup menggantikan nilai seluruh organisasi untuk anggotanya; pengaturan tersebut tidak menambahkannya. Misalnya, jika nilai seluruh organisasi adalah required dan grup Pilot memiliki available, anggota Pilot mendapatkan available. Ketika Anda memindahkan plugin dari grup percontohan ke seluruh organisasi, atur nilai seluruh organisasi lalu hapus pengaturan grup tersebut. Mengatur nilai seluruh organisasi menghentikan plugin mewarisi default marketplace-nya; menghapus pengaturan seluruh organisasi mengembalikan plugin ke default tersebut.
Plugin yang dibuat melalui API ini dimulai tanpa pengaturannya sendiri, sehingga mewarisi default marketplace-nya: not_available kecuali seseorang telah menetapkan default. Menghapus grup akan menghapus pengaturannya dari setiap plugin.
Berbagi
Share menentukan siapa yang dapat menggunakan plugin milik anggota. Pemilik membagikannya di claude.ai dengan setiap anggota, dengan suatu grup, atau dengan anggota tertentu. API ini mencantumkan share tetapi tidak dapat mengubahnya.
Jika organisasi Anda telah menonaktifkan suatu jenis berbagi di pengaturan claude.ai-nya, berbagi jenis tersebut tetap muncul dalam daftar tetapi tidak memberikan akses kepada siapa pun selama pengaturan tersebut nonaktif; daftar itu sendiri tidak menunjukkan apakah pengaturan tersebut nonaktif.
Pemindaian konten
“Content scanning” (pemindaian konten) adalah pengaturan organisasi di claude.ai. Saat aktif, versi yang baru disimpan akan dipindai (claude.ai mengecualikan beberapa) dan hasilnya dilaporkan di content_scan; versi yang tidak dipindai, misalnya versi yang disimpan sebelum pemindaian diaktifkan, memiliki content_scan: null. Pemindaian tidak ditawarkan kepada organisasi yang menggunakan kunci enkripsi yang dikelola pelanggan atau retensi data nol.
Selama pemindaian aktif, anggota hanya disajikan plugin ketika pemindaian versi yang disajikan berstatus completed dengan pass atau warn. Selama pemindaian berstatus processing atau errored, atau menunjukkan fail atau unknown, plugin ditahan dari anggota, dan versi sebelumnya tidak disajikan sebagai gantinya. Versi yang tidak pernah dipindai (content_scan: null) disajikan secara normal.
Versi yang Anda unggah melalui API ini tidak pernah menunggu pemindaian kontennya. Ketika versi tersebut menjadi versi yang disajikan, anggota kehilangan plugin hingga content_scan-nya menunjukkan completed dengan pass atau warn. Jika anggota harus tetap menggunakan versi saat ini selama versi baru dipindai, sematkan plugin terlebih dahulu (lihat Versi dan versi yang disajikan).
Selama versi yang disimpan di claude.ai menunggu pemindaiannya, versi yang disajikan tidak berubah. Ketika unggahan API Anda menjadi versi yang disajikan, penantian apa pun berakhir: versi yang menunggu hanya disajikan jika seseorang memilihnya. Untuk melihat pemindaian versi yang menunggu, baca versi tersebut (lihat Mencantumkan versi plugin).
Setelah unggahan, content_scan.status bernilai processing dan hasil pemindaian tiba secara asinkron. Baca versi tersebut untuk melihatnya; objek plugin hanya menampilkan pemindaian versi yang disajikan. Selama pemindaian aktif, mengubah versi yang disajikan ke versi yang content_scan-nya bernilai processing mengembalikan 409 scan_pending, dan mengubahnya ke versi yang pemindaiannya bernilai fail, unknown, atau errored mengembalikan 400 scan_failed.
Pemindaian gagal yang diizinkan di claude.ai
Di claude.ai, pemilik organisasi dapat mengizinkan versi yang pemindaiannya gagal. Demikian pula anggota yang peran kustom-nya dapat mengelola Pustaka. API ini kemudian dapat melaporkan pemindaian tersebut sebagai completed dengan warn dan reason dari pemindaian yang gagal. Selama demikian, aturan untuk warn berlaku: versi tersebut dapat disajikan kepada anggota, dan Anda dapat menjadikannya versi yang disajikan. Tidak ada apa pun dalam respons yang menunjukkan bahwa versi tersebut diizinkan, sehingga warn dapat berupa peringatan atau pemindaian gagal yang diizinkan. Mengizinkan versi yang pemindaiannya bernilai warn tidak mengubah content_scan-nya. Ketika suatu versi tidak lagi diizinkan, API ini melaporkan hasil pemindaian terbaru yang telah selesai. Versi yang disajikan yang pemindaiannya kemudian bernilai fail atau unknown akan ditahan dari anggota.
Jangkauan
reach merangkum, dalam satu nilai, seberapa jauh jangkauan suatu versi di mesin anggota dan di luarnya:
| Nilai | Arti |
|---|---|
remote | Mendeklarasikan server MCP atau CLI, apa pun yang dideklarasikannya selain itu. |
privileged | Tidak mendeklarasikan server MCP atau CLI, tetapi mendeklarasikan hook, monitor (perintah latar belakang yang terus berjalan selama sesi), server LSP (Language Server Protocol), alur kerja (skrip yang dapat dijalankan Claude Code; file apa pun di folder workflows/ pada root plugin dihitung sebagai alur kerja), atau pengaturan yang diterapkan plugin ke aplikasi anggota, atau berisi skill, perintah, atau file Markdown lain yang frontmatter-nya menyetujui alat terlebih dahulu (allowed-tools). Semua ini berjalan, atau berlaku, di komputer anggota sendiri. |
contained | Tidak mendeklarasikan server MCP, CLI, hook, monitor, server LSP, alur kerja, atau pengaturan aplikasi, dan tidak ada file Markdown-nya yang menyetujui alat terlebih dahulu (misalnya, plugin yang hanya berisi skill, command, dan agent, tanpa satu pun yang memiliki allowed-tools). |
reach menghitung semua yang dideklarasikan versi tersebut, termasuk monitor, server LSP, alur kerja, dan pengaturan aplikasi, yang tidak dicantumkan oleh components, sehingga versi dengan daftar components kosong tetap dapat bernilai privileged. Nilainya null untuk versi yang disimpan sebelum komponen dicatat, dan untuk versi yang jangkauannya tidak dapat ditentukan karena SKILL.md dari salah satu skill-nya, atau salah satu file command-nya, tidak dapat dibaca; perlakukan null sebagai tidak terklasifikasi. Nilai ini biasanya ditentukan saat sebuah versi disimpan, berdasarkan aturan yang berlaku pada saat itu. Oleh karena itu, versi yang lebih lama dapat bernilai contained padahal file yang sama jika disimpan hari ini akan bernilai privileged.
Persyaratan unggahan
Unggahan mengikuti aturan yang sama dengan unggahan plugin di claude.ai, sehingga arsip yang sama diterima di kedua tempat.
- Unggahan berupa satu arsip
.zipatau.plugin, atau sekumpulan file individual. Arsip dapat membungkus semuanya dalam satu folder tingkat atas. - Unggahan harus berisi tepat satu manifest, di
.claude-plugin/plugin.json, yang harus mendeklarasikanname.SKILL.mdsaja tanpa manifest akan ditolak. SKILL.mdtingkat atas yang frontmatter-nya mendeklarasikan komponen plugin digabungkan ke dalam manifest;plugin.jsonyang berlaku di mana pun keduanya menetapkan nilai.descriptionyang diambil manifest dariSKILL.mdtersebut dipotong menjadi 500 karakter pertamanya.namedapat berisi huruf kecil (dari alfabet apa pun), angka, dan tanda hubung, hingga 64 karakter. Huruf besar, spasi, garis bawah, dan tanda baca lainnya ditolak.displayNamepaling banyak 64 karakter dandescriptionpaling banyak 500.- Setiap
SKILL.mdmemerlukan frontmatter YAML yang valid dengannamedandescription, yang keduanya tidak boleh berisi tag XML seperti<example>. Dua skill, atau dua command, tidak boleh memiliki nama yang sama. - Tidak boleh ada file di bawah direktori
bin/tingkat atas. - Tidak boleh ada file
.zipbersarang. Server MCP terpaket (.mcpb,.dxt) diizinkan. - Path file harus relatif, tidak berisi
.., dan hanya menggunakan huruf, angka, spasi, dan_ . - / ( ) ,. - Body permintaan dan arsip yang tidak dikompresi masing-masing paling banyak 200 MB; body permintaan yang melebihi batas mengembalikan
413(request_too_large) alih-alih400. Sebuah unggahan memiliki paling banyak 5.000 file, kedalaman path 12, path sepanjang 472 karakter, dan nama file atau folder sepanjang 255 karakter. - Arsip ZIP harus menggunakan kompresi DEFLATE atau STORE, dan tidak boleh dienkripsi atau berisi tautan simbolik.
- Unggahan yang membuat plugin mengembalikan
400jika marketplace sudah berisi 1.000 plugin. Plugin yang tidak dicantumkan oleh API ini juga dihitung, sehingga batas ini dapat tercapai meskipun Daftar plugin menampilkan kurang dari 1.000 plugin di marketplace tersebut. Anthropic dapat menaikkan batas 5.000 file.
Contoh alur kerja
Publikasikan setiap build dari pipeline rilis
Unggah setiap build bertag dari CI, dan biarkan pipeline menentukan kapan sebuah build disajikan.
- Temukan marketplace tujuan unggahan dengan
GET /v1/organizations/plugin_marketplaces?owner_type=organization, atau hilangkanmarketplace_iduntuk menggunakan marketplace pustaka. - Pada rilis pertama, buat plugin dengan
POST /v1/organizations/plugins. Pada setiap rilis berikutnya, catatlatest_version_idplugin, lalu unggah versi denganPOST /v1/organizations/plugins/{plugin_id}/versions. Jika respons unggahan hilang, baca plugin dan coba lagi hanya jikalatest_version_idtidak berubah (lihat Mencoba ulang unggahan). - Agar anggota tetap menggunakan versi saat ini selama setiap build baru diperiksa, sematkan plugin sekali dengan menetapkan
served_version_idke versinya saat ini. Sejak saat itu setiap unggahan disimpan tanpa disajikan, dan sematan tidak dapat dibatalkan: setiap build yang ingin Anda sajikan memerlukan langkah 5. - Saat pemindaian konten aktif, lakukan polling
GET /v1/organizations/plugins/{plugin_id}/versions/{version}hinggacontent_scan.statustidak lagiprocessing, dan promosikan hanya jika nilainyacompleteddenganpassatauwarn. - Promosikan build dengan
POST /v1/organizations/plugins/{plugin_id}dan{"served_version_id": "<the new version's ID>"}. Untuk rollback, kirim ID versi sebelumnya dengan cara yang sama.
Luncurkan plugin ke grup percontohan, lalu ke semua orang
-
Cari ID grup pilot dengan
GET /v1/organizations/rbac_groups. Panggilan tersebut memerlukan scoperead:rbac_groups(lihat Grup dan peran di Manajemen pengguna). Langkah-langkah berikutnya memerlukanwrite:plugins, yang hanya bekerja pada organisasi tempat kuncinya dibuat, jadi di enterprise dengan beberapa organisasi tertaut, buat satu kunci di organisasi yang menyimpan plugin dan berikan kedua scope tersebut, atau gunakan kunci kedua yang dibuat di sana untuk langkah-langkah tersebut. -
Berikan grup pengaturannya sendiri, misalnya
auto_install, denganPOST /v1/organizations/plugins/{plugin_id}/installation_settings/{target}, di mana{target}adalah IDrbac_group_grup tersebut, sementara nilai tingkat organisasi tetapnot_available. Hanya anggota grup yang mendapatkan plugin. -
Ketika masa percontohan berakhir, atur nilai seluruh organisasi dengan panggilan berikut, lalu hapus pengaturan grup agar grup kembali mengikuti organisasi. Mengatur nilai seluruh organisasi menghentikan plugin mewarisi default marketplace-nya; menghapus pengaturan seluruh organisasi nantinya mengembalikan plugin ke default tersebut.
Pythonclient = 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}")Kemudian hapus pengaturan grup dengan
DELETE /v1/organizations/plugins/{plugin_id}/installation_settings/{target}, di mana{target}adalah ID grup. Pengaturan grup menggantikan nilai tingkat organisasi untuk anggotanya alih-alih menambahkannya, sehingga pengaturan grupavailableyang tersisa akan membuat anggota tersebut tetap padaavailable.
Jaga inventaris keamanan tetap sinkron
Jalankan job malam hari yang menandai plugin yang menjangkau di luar sesi anggota atau yang pemindaian kontennya menunjukkan warn, fail, atau unknown.
- Telusuri halaman
GET /v1/organizations/plugins?limit=100hingganext_pagebernilainull(lihat Paginasi). Bacareachdancontent_scansetiap plugin dari daftar tersebut pada setiap eksekusi: perubahan padacontent_scansaja, seperti hasil pemindaian yang tiba belakangan, tidak mengubahupdated_at.updated_atbiasanya memberi tahu Anda plugin mana yang memiliki konten baru atau versi baru yang disajikan sejak eksekusi terakhir (layak untuk mengunduh arsip baru). Versi yang menunggu (lihat Versi dan versi yang disajikan) mengubahupdated_atketika menjadi versi yang disajikan, tidak harus ketika disimpan. Untuk mendeteksinya, bandingkanlatest_version_iddengan nilai dari eksekusi terakhir Anda. Pencantuman ulang secara penuh juga yang mendeteksi penghapusan, karena plugin yang dihapus oleh sinkronisasi Git atau penghapusan akun menghilang tanpa event. - Tandai setiap plugin yang
reach-nya bernilairemote(mendeklarasikan server MCP atau CLI), atau yangcontent_scan.assessment-nya bernilaiwarn,fail, atauunknown.warnjuga dapat berupa pemindaian gagal yang diizinkan di claude.ai. Abaikanwarnhanya jika Anda menerima setiap pemindaian gagal yang diizinkan di sana. Field-field ini menjelaskan versi yang disajikan. Untuk juga memeriksa versi lebih baru yang tidak disajikan, cantumkan versi plugin ketikalatest_version_idberbeda dariserved_version_id(lihat Mencantumkan versi plugin). - Untuk setiap plugin yang ditandai, unduh arsip versi yang disajikan untuk ditinjau dengan
GET /v1/organizations/plugins/{plugin_id}/versions/{served_version_id}/content(lihat Mengunduh file suatu versi). Unduh juga versi tidak disajikan mana pun yang memenuhi uji langkah 2, berdasarkan ID-nya. - Untuk menarik plugin dari anggota selama Anda meninjaunya, lihat Menghapus plugin untuk opsi yang dapat dibatalkan (milik organisasi) dan yang permanen.
Plugin
Objek plugin menjelaskan plugin di salah satu marketplace organisasi Anda atau di marketplace pribadi anggota (respons Mulai cepat menunjukkan contoh lengkapnya). display_name, description, manifest_version, content_scan, components, dan reach-nya menjelaskan versi yang disajikan, sehingga satu panggilan daftar menunjukkan apa yang sedang disajikan kepada anggota.
| Field | Deskripsi |
|---|---|
id | Berawalan plugin_. |
name | Dari manifest. Unik di dalam marketplace-nya, bukan di seluruh organisasi. Tetap untuk plugin milik organisasi; berubah jika anggota mengganti nama plugin miliknya sendiri di claude.ai. |
display_name, description, manifest_version | displayName, description, dan version dari manifest versi yang disajikan; masing-masing bernilai null jika manifest tidak mendeklarasikannya. description mungkin berupa description dari sebuah skill, bukan dari manifest (dijelaskan setelah tabel ini). manifest_version dinormalisasi untuk tampilan: satu v atau V di awal dihapus, sehingga version manifest "v1.4.0" dikembalikan sebagai "1.4.0". Nilainya juga null untuk nilai yang tidak tampak seperti nomor versi, seperti "latest", dan untuk versi plugin yang dibuat sebelum claude.ai mulai mencatat field ini pada Agustus 2026. Unggahan tidak pernah ditolak karena version-nya, dan manifest_version tidak unik. |
served_version_id, latest_version_id | Berawalan pluginver_: versi yang disajikan kepada anggota, dan versi terbaru. Lihat Versi dan versi yang disajikan. |
served_version_pinned | false sampai plugin disematkan (lihat Versi dan versi yang disajikan); true sejak saat itu. |
owner | {"type": "organization"}, atau {"type": "user", "user_id": "user_..."} untuk marketplace pribadi anggota. |
marketplace_id | Berawalan marketplace_. |
created_by | Siapa yang membuat plugin: {"type": "user_actor", "user_id": "user_...", "email_address": "..."} untuk seseorang di claude.ai (email_address mungkin null), atau {"type": "api_actor", "api_key_id": "apikey_..."} untuk kunci API. Jenis aktor lain mungkin muncul. null jika tidak ada pembuat yang tercatat, seperti untuk plugin yang disinkronkan dari Git. |
organization_installation_preference, organization_installation_preference_inherited | Milik organisasi: nilai tingkat organisasi, dan apakah nilai tersebut berasal dari default marketplace (lihat Pengaturan instalasi). Milik anggota: keduanya null. |
content_scan | Hasil pemindaian versi yang disajikan, berupa objek dengan status, assessment, dan reason (dijelaskan setelah tabel ini). null jika tidak pernah dipindai. |
components | Komponen versi yang disajikan, masing-masing {"type", "name", "description"} dengan type salah satu dari skill, mcp_server, command, agent, hook, atau cli, dicantumkan dalam urutan jenis tersebut lalu berdasarkan nama. Untuk server MCP, name adalah kuncinya di manifest; untuk hook, peristiwa tempat hook tersebut berjalan; untuk CLI, nama executable-nya. description selalu null untuk server MCP, hook, dan CLI. null jika tidak tercatat. |
reach | contained, privileged, atau remote. Lihat Jangkauan. |
updated_at | Berubah ketika versi yang disajikan berubah, ketika plugin menjadi disematkan, dan biasanya ketika versi baru disimpan. Versi yang menunggu (lihat Versi dan versi yang disajikan) mengubahnya ketika versi tersebut menjadi versi yang disajikan, tidak selalu ketika disimpan. Nilainya tidak berubah untuk pengaturan instalasi, share, atau perubahan pada content_scan saja. |
description tidak selalu berasal dari manifest. description yang diambil manifest dari SKILL.md tingkat atas dipotong menjadi 500 karakter pertamanya (lihat Persyaratan unggahan). Jika description manifest adalah 500 karakter pertama dari tepat satu nilai unik description skill di components, API mengembalikan description skill tersebut sebagai gantinya. Akibatnya:
descriptionyang Anda baca mungkin lebih panjang dari 500 karakter, batas untuk manifest yang diunggah. Unggahan yangplugin.json-nya menetapkandescriptionseperti itu mengembalikan400.- Di file yang Anda unduh,
.claude-plugin/plugin.jsonmungkin memilikidescriptionyang berbeda, atau tidak memilikinya sama sekali.
Objek content_scan:
| Field | Deskripsi |
|---|---|
status | processing selama pemindaian berjalan, completed ketika selesai, atau errored ketika tidak dapat diselesaikan (atau, sesekali, ketika hasilnya tidak dapat dibaca untuk respons ini, dalam hal ini pembacaan berikutnya mungkin melaporkannya). Pemindaian selesai yang terbaru, jika ada, yang dilaporkan. Anggota tidak disajikan versi yang status-nya processing atau errored; mengunggah ulang konten sebagai versi baru akan mendapatkan pemindaian baru. |
assessment | Diatur ketika status adalah completed: pass (tidak ada yang ditemukan), warn (ditemukan sesuatu yang tidak memblokir penggunaan, atau pemindaian gagal yang diizinkan di claude.ai), fail (ditemukan sesuatu yang memblokir penggunaan), atau unknown (tidak ada putusan). Selain itu null. |
reason | Untuk warn dan fail, kekhawatiran utama, dari daftar berikut. Selain itu null, dan juga null pada pemindaian lama yang dibuat sebelum alasan mulai dicatat. |
reason | Arti |
|---|---|
covert-usage-telemetry | Memerintahkan Claude untuk mengirim informasi tentang anggota atau penggunaannya ke alamat luar tanpa memberi tahu mereka. |
undisclosed-data-destination | Mengirim file, email, dokumen, atau konten lain ke tujuan luar yang tetap, yang tidak ditampilkan kepada anggota dan tidak dikendalikan olehnya. |
remote-code-instruction-loader | Memerintahkan Claude untuk mengunduh dan menjalankan, atau mengikuti instruksi dari, konten luar yang dapat berubah setelah plugin diinstal. |
credential-exposure | Berisi kredensial aktif, atau mengumpulkan kredensial atau token dari lingkungan anggota. |
guardrail-tampering | Melemahkan pengaman anggota, misalnya dengan menyetujui sebelumnya setiap prompt izin. |
system-prompt-spoofing | Meniru atau mencoba menggantikan instruksi sistem Claude. |
covert-record-tampering | Diam-diam mengubah, menyembunyikan, atau menghapus informasi yang seharusnya dilihat anggota. |
covert-behavior-override | Mengubah perilaku Claude melampaui tujuan plugin dan menyembunyikan perubahan tersebut dari anggota. |
hidden-code-execution | Menjalankan kode yang dibundel sambil memerintahkan Claude untuk tidak mengungkapkan apa yang dilakukannya. |
undisclosed-promotion-injection | Menyisipkan konten promosi yang tidak diungkapkan ke dalam output Claude. |
hidden-identity-gate | Mengubah atau menghentikan perilakunya tergantung pada akun mana yang menjalankannya, tanpa menjelaskan alasannya. |
destructive-persistence | Dapat menghapus atau merusak file anggota, atau menginstal program yang tetap ada setelah plugin tidak ada lagi. |
unanalyzable-binary | Menyertakan program yang dikompilasi atau tidak dapat dibaca, sehingga pemindaian tidak dapat memverifikasi apa yang dilakukannya. |
other | Kekhawatiran lain apa pun, termasuk yang lebih baru dari daftar ini. |
plugin_id yang tidak memiliki awalan plugin_ mengembalikan 400. plugin_id yang memiliki awalan tersebut tetapi tidak ada dalam inventaris organisasi Anda mengembalikan 404.
Daftar plugin
GET /v1/organizations/plugins menampilkan plugin di organisasi Anda, di marketplace organisasi dan di marketplace pribadi anggota, diurutkan berdasarkan created_at secara menurun. Filter berdasarkan owner_type (organization atau user), owner_user_id (ID berawalan user_, yang menemukan plugin milik seorang anggota, termasuk setelah anggota tersebut meninggalkan organisasi), marketplace_id, dan created_at[gte], created_at[gt], created_at[lte], created_at[lt] (timestamp RFC 3339). Filter digabungkan dengan AND. marketplace_id atau owner_user_id yang tidak cocok dengan apa pun di organisasi Anda mengembalikan halaman kosong, bukan error. Respons memiliki bentuk yang ditampilkan di Mulai cepat. Memerlukan scope read:plugins.
client = anthropic.Anthropic()
plugins = client.beta.organization.plugins.list(owner_type="organization", limit=20)
# Secara otomatis mengambil halaman berikutnya sesuai kebutuhan.
for plugin in plugins:
print(f"{plugin.id}: {plugin.name}")Membuat plugin
POST /v1/organizations/plugins membuat plugin milik organisasi beserta versi pertamanya dalam satu panggilan; versi tersebut menjadi versi yang disajikan. Body-nya adalah multipart/form-data: files[] adalah satu arsip .zip atau .plugin, atau satu bagian untuk setiap file, di mana nama file setiap bagian adalah path file di dalam plugin (misalnya .claude-plugin/plugin.json). Field opsional adalah marketplace_id (marketplace manual milik organisasi, atau secara default marketplace library Anda, yang dibuat saat pertama kali digunakan) dan release_notes (hingga 5.000 karakter, ditampilkan di riwayat versi claude.ai dan dikembalikan pada versi). name, display_name, description, dan manifest_version plugin berasal dari file yang diunggah, dan unggahan harus memenuhi persyaratan unggahan. Ketika pemindaian konten aktif, content_scan.status pada respons adalah processing dan putusannya tiba secara asinkron. Mengembalikan plugin. Memerlukan scope write:plugins.
Mengunggah arsip:
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"
}Unggah file satu per satu ke marketplace tertentu. Lampirkan setiap file dengan path-nya di dalam plugin (akhiran ;filename= pada contoh cURL, argumen nama file pada contoh SDK); file yang dikirim hanya dengan nama dasarnya berarti manifest tidak ditemukan. SDK TypeScript dan Java serta CLI ant belum dapat melampirkan file dengan path, sehingga contoh-contoh tersebut mengunggah plugin sebagai satu arsip ke marketplace sebagai gantinya:
client = anthropic.Anthropic()
# Tuple (filename, file) mempertahankan path setiap file di dalam plugin;
# objek file biasa hanya akan dikirim dengan nama dasarnya saja.
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}")Selain 400 untuk unggahan yang melanggar persyaratan unggahan (413 untuk body permintaan lebih dari 200 MB) dan respons bersama (403 ketika marketplace_id adalah marketplace pribadi milik anggota; lihat Respons error), pembuatan dapat gagal dengan:
| Status | Penyebab | Yang harus dilakukan |
|---|---|---|
| 404 | marketplace_id bukan marketplace milik organisasi Anda. | Ambil ID dari Mencantumkan marketplace. |
| 400 | Marketplace disinkronkan dari Git, atau sudah berisi 1.000 plugin (lihat Persyaratan unggahan). | Unggah ke marketplace manual lain, atau ubah repositorinya. |
409 plugin_name_taken | Nama tersebut sudah dipakai di marketplace itu. | Unggah versi ke details.plugin_id hanya jika itu memang plugin yang ingin Anda perbarui, karena mungkin orang lain yang membuatnya. Jika tidak, atau jika details.plugin_id tidak ada, unggah dengan nama lain (ubah name pada manifest). |
409 skill_name_taken | Plugin akan masuk ke marketplace library dan salah satu skill-nya memiliki nama yang sama dengan skill organisasi. | Ganti nama skill tersebut, atau hapus skill organisasi di claude.ai. |
409 (tanpa error_code) | Unggahan lain dengan nama yang sama ke marketplace yang sama sedang berlangsung, atau nama tersebut dipegang oleh plugin yang tidak dicantumkan oleh API ini. | Coba lagi dengan backoff. Jika 409 tetap muncul selama lebih dari beberapa menit, unggah dengan nama lain (ubah name pada manifest). |
503 registration_pending | Plugin telah dibuat tetapi pendaftarannya belum selesai. | Jangan kirim ulang; unggah file yang sama sebagai versi dari details.plugin_id (lihat Mencoba ulang unggahan). |
Mendapatkan plugin
GET /v1/organizations/plugins/{plugin_id} mengembalikan satu plugin. Memerlukan scope read:plugins.
client = anthropic.Anthropic()
plugin = client.beta.organization.plugins.retrieve("plugin_01Hq3vX8kZcN2mB7pR4tY9wL")
print(f"id: {plugin.id}")
print(f"name: {plugin.name}")Mengubah versi yang disajikan
POST /v1/organizations/plugins/{plugin_id} mengubah versi plugin milik organisasi mana yang disajikan kepada anggota. Berikan versi sebelumnya untuk rollback, atau versi yang lebih baru untuk mempromosikan build yang disimpan tanpa disajikan. Ini menyematkan plugin, dan plugin yang tersemat tidak dapat dilepas sematannya, baik di sini maupun di claude.ai (lihat Versi dan versi yang disajikan). Satu-satunya field yang dapat diperbarui adalah served_version_id, dan field ini wajib. Perubahan sampai ke anggota sebelum respons dikembalikan dan tidak membuat versi. Ketika pemindaian konten aktif, versi tersebut harus versi yang dapat disajikan kepada anggota (lihat Pemindaian konten). Memberikan versi yang sudah disajikan pada plugin yang tersemat tidak mengubah apa pun; memberikannya pada plugin yang tidak tersemat akan menyematkannya di sana, sehingga unggahan berikutnya tidak lagi disajikan secara otomatis. Penyematan juga mengakhiri penantian apa pun: versi yang sedang menunggu pemindaian kontennya tetap tersimpan, dan hanya disajikan jika seseorang memilihnya. Mengembalikan plugin. Memerlukan 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"
}Selain respons bersama (403 untuk plugin milik anggota, serta 409 scan_pending atau 400 scan_failed untuk versi yang tidak boleh disajikan kepada anggota; lihat Respons error), permintaan dapat gagal dengan:
| Status | Penyebab | Yang harus dilakukan |
|---|---|---|
| 400 | Body tidak menyertakan served_version_id, mengaturnya ke null, atau berisi field lain; atau nilainya tidak memiliki prefiks pluginver_ atau bernilai latest. | Kirim tepat {"served_version_id": "pluginver_..."}. |
| 404 | served_version_id bukan versi dari plugin ini. | Ambil ID dari Mencantumkan versi plugin. |
409 (tanpa error_code) | Unggahan ke plugin ini atau perubahan versi yang disajikan lainnya masih berlangsung. | Coba lagi sebentar lagi. |
409 skill_name_taken | Plugin berada di marketplace library dan versi tersebut memiliki skill yang namanya kini dipakai oleh skill organisasi. | Pilih versi lain, atau ganti nama salah satu skill. |
Menghapus plugin
DELETE /v1/organizations/plugins/{plugin_id} menghapus plugin secara permanen beserta setiap versi yang dimilikinya, sama seperti penghapusan oleh administrator di claude.ai. Endpoint ini berfungsi untuk plugin apa pun di marketplace manual, termasuk plugin milik anggota, bahkan jika anggota tersebut telah keluar dari organisasi. Saat penghapusan selesai, plugin, versinya, dan file-filenya hilang dari setiap pembacaan, dan plugin tersebut tidak lagi disajikan kepada anggota. Pengaturan instalasi plugin milik organisasi ikut dihapus; pembagian plugin milik anggota ditarik, dan plugin tersebut juga hilang bagi pemiliknya. Plugin di marketplace yang disinkronkan dari Git mengembalikan 400: hapus plugin tersebut dari repositori, atau hapus marketplace di claude.ai. Memerlukan scope write:plugins.
Penghapusan tidak dapat dibatalkan, dan tidak ada penghapusan per versi. Untuk menahan plugin milik organisasi secara reversibel, atur pengaturan instalasi tingkat organisasinya ke not_available (plugin yang mewarisi default marketplace-nya akan mendapatkan pengaturannya sendiri, dan menghapus pengaturan tingkat organisasi tersebut nantinya akan mengembalikan plugin ke default), dan hapus (atau atur ke not_available) setiap pengaturan grup yang dicantumkan oleh GET /v1/organizations/plugins/{plugin_id}/installation_settings, karena pengaturan grup menimpa nilai tingkat organisasi bagi anggotanya. Kirim penulisan ini satu per satu, bukan secara paralel (lihat Menetapkan pengaturan instalasi). Plugin milik anggota tidak dapat ditahan melalui API ini kecuali dengan menghapusnya, dan hanya jika marketplace-nya adalah 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" }Versi plugin
Versi plugin adalah snapshot yang tidak dapat diubah dari file-file plugin dari satu unggahan (respons Membuat versi menampilkan objek lengkapnya). Field-fieldnya mencerminkan field versi yang disajikan milik plugin (display_name, description, manifest_version, content_scan, components, reach) untuk versi ini, ditambah release_notes (sebagaimana diberikan bersama unggahan dan ditampilkan di riwayat versi claude.ai) dan created_by (siapa yang mengunggahnya).
{version} yang tidak memiliki prefiks pluginver_ mengembalikan 400 (kecuali literal latest jika disebutkan). Nilai yang memiliki prefiks tersebut tetapi tidak mengidentifikasi versi dari plugin itu mengembalikan 404.
Mencantumkan versi plugin
GET /v1/organizations/plugins/{plugin_id}/versions mencantumkan versi-versi plugin, diurutkan berdasarkan created_at secara menurun; item pertama adalah versi yang diidentifikasi oleh latest_version_id. limit bernilai 1 hingga 1.000. Memerlukan scope read:plugins.
client = anthropic.Anthropic()
versions = client.beta.organization.plugins.versions.list(
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL", limit=50
)
# Secara otomatis mengambil halaman berikutnya sesuai kebutuhan.
for version in versions:
print(f"{version.id}: {version.manifest_version}")Membuat versi
POST /v1/organizations/plugins/{plugin_id}/versions menambahkan versi ke plugin milik organisasi di marketplace manual. Body berupa multipart/form-data, dengan field files[] dan release_notes yang sama, persyaratan unggahan, serta error file, manifest, arsip, dan ukuran yang sama seperti Membuat plugin. Nama yang diunggah (name pada manifest) harus sama dengan name plugin. Jika plugin tidak disematkan, versi baru biasanya disajikan segera setelah disimpan; jika disematkan, versi tersebut disimpan tetapi tidak disajikan sampai Anda mengubah versi yang disajikan ke versi tersebut. Untuk memeriksanya, bandingkan id pada respons dengan served_version_id plugin. Mengembalikan versi. Memerlukan 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"
}Selain 400 untuk unggahan yang melanggar persyaratan unggahan (413 untuk body permintaan lebih dari 200 MB) dan respons bersama (403 untuk plugin milik anggota; lihat Respons error), permintaan dapat gagal dengan:
| Status | Penyebab | Yang harus dilakukan |
|---|---|---|
| 400 | Plugin berada di marketplace yang disinkronkan dari Git, atau nama yang diunggah berbeda dari nama plugin. | Ubah repositorinya, atau perbaiki name pada manifest. |
409 (tanpa error_code) | Unggahan lain ke plugin ini, atau perubahan versi yang disajikan, masih berlangsung. | Coba lagi sebentar lagi. |
409 skill_name_taken | Plugin berada di marketplace library dan versi tersebut menambahkan skill dengan nama yang sama dengan skill organisasi. | Ganti nama skill tersebut, atau hapus skill organisasi di claude.ai. |
503 registration_pending | Versi telah disimpan tetapi pendaftarannya belum selesai. | Kirim ulang permintaan yang sama jika respons menyertakan x-should-retry: true (lihat Mencoba ulang unggahan). |
Mendapatkan versi
GET /v1/organizations/plugins/{plugin_id}/versions/{version} mengembalikan satu versi. {version} adalah ID versi, atau latest untuk versi yang diidentifikasi oleh latest_version_id pada saat permintaan. Memerlukan 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}")Mengunduh file versi
GET /v1/organizations/plugins/{plugin_id}/versions/{version}/content mengunduh file-file sebuah versi sebagai arsip .zip yang tersimpan (Content-Type: application/zip). Arsip dikembalikan apa pun hasil pemindaian kontennya, sehingga Anda dapat memeriksa versi yang ditahan dari anggota. Arsip disajikan persis seperti yang tersimpan, sehingga untuk plugin milik organisasi di marketplace manual Anda dapat mengunggahnya ulang tanpa perubahan sebagai versi baru, asalkan memenuhi persyaratan unggahan saat ini. {version} harus berupa ID versi, bukan latest: baca served_version_id atau latest_version_id plugin terlebih dahulu, atau resolve latest dengan GET /v1/organizations/plugins/{plugin_id}/versions/latest. Nama file Content-Disposition diturunkan dari nama plugin dan tidak unik; beri nama file yang disimpan berdasarkan plugin dan ID versi. Memerlukan scope read:plugins.
Mengunduh arsip plugin milik anggota mencatat event claude_plugin_archive_accessed pada Activity Feed Compliance API, yang mengidentifikasi kunci (sebagai api_actor), plugin dan marketplace-nya, versi, serta anggota pemilik berdasarkan ID; event ini tidak memuat nama. Mengunduh arsip plugin milik organisasi tidak mencatat apa pun.
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")Pengaturan instalasi plugin
Endpoint ini berlaku untuk plugin milik organisasi. Endpoint ini mengembalikan 404 untuk plugin milik anggota, yang memiliki share sebagai gantinya (lihat Share plugin). {target} adalah literal organization untuk pengaturan seluruh organisasi plugin, atau ID rbac_group_ sebuah grup untuk pengaturan grup tersebut; nilai lain apa pun mengembalikan 400. ID grup berasal dari GET /v1/organizations/rbac_groups (scope read:rbac_groups; lihat Grup di Manajemen pengguna). Sebuah pengaturan tidak memiliki id sendiri: pengaturan dialamatkan melalui (plugin_id, target), dan tidak ada aktor yang tercatat padanya (aktor tercatat pada event aktivitas plugin_installation_preference_updated-nya).
Mencantumkan pengaturan instalasi plugin
GET /v1/organizations/plugins/{plugin_id}/installation_settings mencantumkan pengaturan yang dimiliki plugin milik organisasi, diurutkan berdasarkan created_at secara menurun: pengaturan tingkat organisasinya sendiri (tidak ada selama plugin mewarisi default marketplace-nya) dan pengaturan setiap grup. Filter berdasarkan target_type (organization atau rbac_group). Memerlukan scope read:plugins.
client = anthropic.Anthropic()
settings = client.beta.organization.plugins.installation_settings.list(
"plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
)
# Secara otomatis mengambil halaman berikutnya sesuai kebutuhan.
for setting in settings:
print(f"{setting.plugin_id}: {setting.installation_preference}")Menetapkan pengaturan instalasi
POST /v1/organizations/plugins/{plugin_id}/installation_settings/{target} mengatur pengaturan instalasi satu target untuk plugin milik organisasi, dengan membuatnya atau mengubah nilai yang sudah dimilikinya. Satu-satunya field body adalah installation_preference (required, auto_install, available, atau not_available), dan field ini wajib. Mengatur nilai yang sudah dimiliki target tidak mengubah apa pun. Mengatur target organization menghentikan plugin mewarisi default marketplace-nya (organization_installation_preference_inherited menjadi false), bahkan ketika nilainya sama dengan default, sehingga plugin tidak lagi mengikuti perubahan default marketplace berikutnya. Untuk mengembalikan plugin ke default marketplace-nya, hapus pengaturan tingkat organisasi; pengaturan grup tidak terpengaruh. Target grup harus berupa grup yang dapat dilihat organisasi Anda di GET /v1/organizations/rbac_groups, atau permintaan mengembalikan 404. Perubahan tidak mengubah updated_at plugin; perubahan dicatat di Activity Feed. Mengembalikan pengaturan. Memerlukan scope write:plugins.
Kirim penulisan pengaturan instalasi untuk suatu plugin satu per satu. Jika beberapa penulisan untuk plugin yang sama tiba bersamaan, server menanganinya satu per satu dan dapat menjawab sebagian di antaranya dengan 503 alih-alih menerapkannya. 503 tersebut menyertakan x-should-retry: true, dan penulisan tersebut aman untuk diulang: tunggu satu atau dua detik, lalu kirim lagi.
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"
}Menghapus pengaturan instalasi
DELETE /v1/organizations/plugins/{plugin_id}/installation_settings/{target} menghapus pengaturan instalasi satu target untuk plugin milik organisasi. Dengan {target} berupa organization, endpoint ini menghapus pengaturan tingkat organisasi milik plugin itu sendiri. Plugin kemudian kembali mewarisi default marketplace-nya (organization_installation_preference_inherited menjadi true) dan mengikuti perubahan default tersebut berikutnya; pengaturan grup tidak terpengaruh. Dengan ID rbac_group_ sebuah grup, endpoint ini menghapus pengaturan grup tersebut: anggota grup kembali ke nilai tingkat organisasi, atau ke pengaturan grup lain yang mereka ikuti. Target yang tidak memiliki pengaturan sendiri mengembalikan 404; ini termasuk target organization dari plugin yang sudah mewarisi default marketplace-nya. Perubahan tidak mengubah updated_at plugin; perubahan dicatat di Activity Feed. Respons membawa kunci komposit sebagai pengganti id; untuk target organization, target-nya adalah {"type": "organization"}. Memerlukan 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" }
}Pembagian plugin
Pembagian (“share”) hanya ada pada plugin milik anggota dan bersifat hanya-baca di API ini (lihat Pembagian).
Mencantumkan pembagian plugin
GET /v1/organizations/plugins/{plugin_id}/shares mencantumkan pihak-pihak yang telah diberi akses oleh pemilik plugin milik anggota, diurutkan berdasarkan granted_at secara menurun: setiap anggota (organization), sebuah grup (rbac_group), atau anggota tertentu (organization_member). Filter berdasarkan target_type. Plugin yang belum dibagikan oleh pemiliknya mengembalikan daftar kosong; plugin milik organisasi mengembalikan 404. Pembagian bersifat hanya-baca di API ini, dan pembagian yang tercantum hanya memberikan akses selama jenis pembagian tersebut diaktifkan untuk organisasi Anda di claude.ai (lihat Pembagian). granted_at adalah waktu pembagian diberikan; jika pemilik kemudian mengubah pembagian tersebut di claude.ai, nilainya adalah waktu perubahan itu. Memerlukan scope read:plugins.
client = anthropic.Anthropic()
shares = client.beta.organization.plugins.shares.list("plugin_01Mr2wP7sU3aJ8vX5cY6nS9t")
# Secara otomatis mengambil halaman berikutnya sesuai kebutuhan.
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 plugin
API ini membaca marketplace dan menetapkan pengaturan instalasi default marketplace organisasi; marketplace itu sendiri dibuat, dihubungkan ke repositori, dan dihapus di 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"
}| Field | Deskripsi |
|---|---|
name | Nama marketplace. Tetap sepanjang masa hidupnya. |
owner | Bentuknya sama seperti pada plugin. |
source | manual, github, gitlab, atau public_git. Lihat Marketplace. |
sync_status | Hasil sinkronisasi terbaru: success, in_progress, failed_content, failed_transient, failed_auth, atau failed_limits. null sampai sinkronisasi pertama kali dicoba, yang tidak pernah terjadi untuk marketplace dengan source manual. |
last_sync_ended_at | Waktu selesainya upaya sinkronisasi terbaru, apa pun hasilnya; untuk repositori terhubung yang belum pernah disinkronkan, waktu marketplace dibuat. null untuk marketplace yang tidak disinkronkan. |
last_sync_read_sha | Commit yang dibaca dari repositori pada sinkronisasi terakhir. Belum tentu commit asal versi-versi yang disajikan. null untuk marketplace yang tidak disinkronkan. |
default_installation_preference | Marketplace organisasi: nilai tingkat organisasi untuk setiap plugin di dalamnya yang tidak memiliki pengaturan sendiri (not_available jika belum pernah ditetapkan). Marketplace pribadi: null. |
marketplace_id yang tidak memiliki prefiks marketplace_ mengembalikan 400. Nilai yang memiliki prefiks tersebut tetapi tidak dapat diresolusikan, atau milik organisasi lain, mengembalikan 404.
Mencantumkan marketplace
GET /v1/organizations/plugin_marketplaces mencantumkan marketplace organisasi Anda dan marketplace pribadi anggota, diurutkan berdasarkan created_at secara menurun. Gunakan endpoint ini untuk menemukan ID marketplace, untuk memfilter daftar plugin berdasarkan marketplace tersebut atau untuk mengunggah ke dalamnya, sebelum marketplace itu berisi plugin apa pun. Marketplace library muncul setelah sesuatu pertama kali dibuat di dalamnya, di claude.ai atau melalui API ini. Filter berdasarkan owner_type (organization atau user) dan source. limit bernilai 1 hingga 1.000. Memerlukan scope read:plugins.
client = anthropic.Anthropic()
marketplaces = client.beta.organization.plugin_marketplaces.list(
owner_type="organization"
)
# Secara otomatis mengambil halaman berikutnya sesuai kebutuhan.
for marketplace in marketplaces:
print(f"{marketplace.id}: {marketplace.name}")Mendapatkan marketplace
GET /v1/organizations/plugin_marketplaces/{marketplace_id} mengembalikan satu marketplace. Memerlukan 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}")Menetapkan pengaturan instalasi default marketplace
POST /v1/organizations/plugin_marketplaces/{marketplace_id} menetapkan pengaturan instalasi default dari marketplace milik organisasi. Setiap plugin di marketplace yang tidak memiliki pengaturan tingkat organisasinya sendiri melaporkan default ini sebagai organization_installation_preference-nya, termasuk plugin yang ditambahkan kemudian. Endpoint ini berfungsi untuk marketplace manual maupun yang disinkronkan; marketplace pribadi milik anggota mengembalikan 403. Satu-satunya field yang dapat diperbarui adalah default_installation_preference, dan field ini wajib. Nilainya tidak dapat dikembalikan ke null: setelah marketplace memiliki default, marketplace tersebut akan tetap memilikinya, seperti di claude.ai. Perubahan dicatat sebagai satu event marketplace_updated tanpa event per plugin, dan tidak mengubah updated_at plugin mana pun. Menetapkan nilai yang sudah ditetapkan tidak mengubah apa pun, dengan satu pengecualian: marketplace yang default-nya belum pernah ditetapkan melaporkan not_available tetapi tidak memiliki pengaturan, sehingga penulisan pertamanya (bahkan not_available) dihitung sebagai perubahan. Mengembalikan marketplace. Memerlukan 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}")Memvalidasi konten marketplace
Dua endpoint melaporkan apa yang akan dilakukan oleh sinkronisasi konten marketplace yang diberikan, tanpa menghubungkan atau menyimpan apa pun: POST /v1/organizations/plugin_marketplaces/validate_repository membaca repositori GitHub publik, dan POST /v1/organizations/plugin_marketplaces/validate_archive membaca .zip dari direktori marketplace yang Anda unggah. Keduanya mengembalikan laporan yang sama: apakah marketplace.json terbentuk dengan benar, plugin mana yang akan dilewati dan alasannya, serta plugin mana yang akan tersinkronisasi dengan sebagian isinya tidak disertakan. Pemeriksaannya sama dengan yang dijalankan oleh sinkronisasi sungguhan. Masalah pada konten dikembalikan dalam laporan, bukan sebagai error HTTP: permintaan berhasil dengan valid: false, bahkan ketika repositori atau arsip sama sekali tidak dapat dibaca. Sebuah validasi dihitung sebagai operasi baca, dan kedua endpoint tersebut secara bersama-sama juga dibatasi hingga 10 validasi per menit untuk setiap organisasi (lihat Pembatasan laju); keduanya tidak mencatat apa pun di Activity Feed. Sebuah validasi dapat memakan waktu hingga 120 detik sebelum mengembalikan hasil, jadi atur timeout klien Anda di atas angka tersebut. Kedua endpoint memerlukan scope read:plugins atau write:plugins (read:org_audit dan read:compliance_org_data tidak memberikannya).
Validasi membaca repositori secara anonim. Hal yang sama berlaku untuk sumber plugin apa pun yang berada di GitHub tetapi di luar repositori. Akibatnya, validasi melaporkan repositori privat atau sumber plugin privat sebagai tidak ditemukan atau memerlukan login GitHub. Ketika validasi melaporkan bahwa login GitHub diperlukan, kode laporannya adalah marketplace_repo_sign_in_required.
Validasi tidak mengambil sumber plugin di host selain GitHub. Plugin dengan sumber seperti itu biasanya mendapatkan peringatan marketplace_validate_source_not_checked dan diperiksa ketika marketplace benar-benar tersinkronisasi.
Validasi menerapkan aturan yang lebih ketat pada marketplace yang disinkronkan oleh Anthropic ke setiap organisasi. validate_repository menerapkannya ketika repositori tersebut merupakan marketplace seperti itu. validate_archive menerapkannya ketika arsip menyebutkan marketplace seperti itu. Aturan yang lebih ketat tersebut adalah sebagai berikut:
- Setiap sumber plugin di luar marketplace harus dipin ke SHA commit lengkap.
- Validasi melaporkan sumber yang tidak dipin dan sumber pada host yang tidak didukung sebagai error plugin.
- Untuk
validate_repository, branch yang dibaca validasi secara default adalah branch tempat marketplace disinkronkan.
validate_repository menerima body JSON dengan dua field: repository_url, URL https:// dari repositori publik di github.com (wajib), dan ref, nama branch atau SHA commit lengkap 40 karakter (opsional). Ketika ref dihilangkan atau null, nilainya default ke branch yang akan dibaca oleh sinkronisasi, biasanya branch default repositori. validate_archive menerima multipart/form-data dengan tepat satu bagian, archive, yang dikirim sebagai bagian file dengan nama file. File tersebut adalah .zip dari direktori marketplace, berukuran paling besar 32 MB, yang hanya menggunakan kompresi DEFLATE atau STORE. Isi arsip berada di root atau dibungkus dalam satu folder (seperti yang dihasilkan oleh unduhan dari host Git). Tidak ada field formulir lain yang diterima.
Memvalidasi repositori publik pada suatu 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"
}
]
}
]
}| Field | Deskripsi |
|---|---|
valid | true ketika marketplace.json terbentuk dengan benar dan tidak ada plugin yang akan dilewati. Peringatan tidak membuatnya bernilai false. |
ref | Branch yang dibaca, berdasarkan nama; null ketika tidak ada branch yang disebutkan dan branch default yang dibaca, untuk SHA commit, atau untuk arsip. |
commit_sha | Commit yang divalidasi. Untuk arsip yang diunduh dari host Git, commit yang dicatat host di field komentar file ZIP, jika ada (tidak diverifikasi). |
total_plugin_count | Jumlah plugin yang dideklarasikan marketplace.json; 0 jika file tersebut tidak dapat dibaca. |
manifest_error, manifest_error_code | Diisi ketika tidak ada yang dapat divalidasi: sumber tidak dapat dibaca, atau marketplace.json tidak ada, rusak, atau melebihi batas. Validasi yang tidak selesai dalam 120 detik melaporkan manifest_error_code: "marketplace_validate_deadline_exceeded". |
plugin_errors | Satu {name, error, error_code} per plugin yang akan dilewati oleh sinkronisasi. |
plugin_warnings | Satu {name, warnings: [{message, error_code}]} per plugin yang akan disinkronkan dengan sebagian kontennya tidak disertakan. |
Sebagai alternatif, validasi salinan lokal direktori marketplace sebagai .zip; responsnya berupa laporan yang sama:
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}")Masalah pada konten tidak pernah membuat permintaan gagal. Selain respons yang dimiliki bersama oleh setiap endpoint (403 untuk kunci yang hanya memiliki read:org_audit atau read:compliance_org_data; lihat Respons error dan Pembatasan laju), permintaan itu sendiri dapat gagal dengan:
| Status | Penyebab | Yang harus dilakukan |
|---|---|---|
| 400 | Pada validate_repository: body bukan objek JSON; repository_url tidak ada, lebih panjang dari 2.048 karakter, membawa kredensial, atau tidak berbentuk https://github.com/{owner}/{repo} (sufiks .git diterima; host lain, path yang lebih panjang seperti /tree/main dari halaman branch, atau port selain 443 atau 80 tidak diterima); ref kosong, lebih panjang dari 255 karakter, mengandung .., atau mengandung karakter selain huruf ASCII, digit, ., _, -, +, dan /; atau ada field lain. ref yang lolos pemeriksaan ini tetapi menyebutkan branch yang tidak dimiliki repositori tidak ditolak: permintaan berhasil dengan valid: false dan manifest_error menyatakan bahwa branch tidak ditemukan. Pada validate_archive: body bukan multipart/form-data, bagian archive tidak ada, berulang, atau tidak dikirim sebagai bagian file dengan nama file, atau ada field formulir lain. | Perbaiki permintaan dan kirim ulang. |
| 413 | Pada validate_archive: bagian archive, atau panjang body yang dideklarasikan pada permintaan, melebihi 32 MB. | Validasi repositori melalui URL sebagai gantinya, atau perkecil arsip. |
Kode laporan
Setiap temuan dalam laporan memiliki kode yang stabil: manifest_error_code ketika tidak ada yang dapat divalidasi, error_code pada setiap entri plugin_errors, dan error_code pada setiap peringatan. Ketika sebuah plugin memiliki beberapa masalah, error_code adalah kode masalah pertama dan error menggabungkan pesan-pesannya. Kode baru dapat ditambahkan; manifest_error_code yang tidak dikenali tetap berarti konten tidak dapat divalidasi, kode yang tidak dikenali pada entri plugin_errors tetap berarti plugin akan dilewati, dan kode yang tidak dikenali pada peringatan tetap berarti plugin akan tersinkronisasi. Kode-kode berikut menunjukkan kondisi sementara, sehingga permintaan yang sama mungkin berhasil nanti: 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, dan biasanya marketplace_validate_deadline_exceeded.
Nilai yang tidak dikenali
Setiap nilai string di halaman ini (tipe komponen, reach, field pemindaian, source marketplace, kode error) dapat memperoleh nilai baru kapan saja. Perlakukan nilai yang tidak Anda kenali seperti string tak dikenal lainnya, alih-alih membuat proses gagal.
Pembatasan laju
Permintaan baca (setiap endpoint GET di halaman ini) berbagi batas 300 permintaan per menit untuk setiap organisasi. Permintaan tulis (membuat plugin atau versi, mengubah versi yang disajikan, menghapus, mengatur atau menghapus pengaturan instalasi, dan memperbarui marketplace) berbagi batas 60 permintaan per menit untuk setiap organisasi. Validasi marketplace (endpoint mana pun) dihitung sebagai operasi baca, dan validasi juga dibatasi hingga 10 per menit untuk setiap organisasi di kedua endpoint; kedua batas diperiksa sebelum body permintaan dibaca. Batas-batas ini dihitung di seluruh kunci organisasi Anda dan terpisah dari batas Admin API lainnya milik organisasi Anda. Operasi baca yang meneruskan organization_id dihitung terhadap batas organisasi tempat kunci tersebut dibuat, atau terhadap batas organisasi induk jika kunci tidak memiliki organisasi sendiri. Permintaan yang melebihi batas mengembalikan 429 Too Many Requests dengan header retry-after. Respons menyertakan header anthropic-ratelimit-requests-* untuk batas yang berlaku (pada validasi marketplace, batas 10 per menitnya; pada 429, batas mana pun yang menolak permintaan tersebut).
Unggahan, perubahan versi yang disajikan, atau validasi juga dapat mengembalikan 429 dengan retry-after ketika layanan untuk sementara tidak memiliki kapasitas untuk permintaan lain, dan unggahan mengembalikan 429 ketika organisasi Anda telah melampaui laju pemindaian kontennya. Tangani semua kasus ini dengan cara yang sama: tunggu sesuai retry-after, lalu coba lagi. Terpisah dari batas-batas ini, kirim penulisan pengaturan instalasi untuk plugin yang sama satu per satu: ketika beberapa tiba bersamaan, sebagian dapat dijawab dengan 503 dan x-should-retry: true, dan permintaan tersebut aman untuk dikirim lagi setelah satu atau dua detik (lihat Menetapkan pengaturan instalasi).
Paginasi
Endpoint daftar menggunakan kursor opak. Permintaan pertama mengembalikan hingga limit baris ditambah kursor next_page; teruskan kursor tersebut tanpa diubah sebagai parameter page pada permintaan berikutnya, dan ulangi hingga next_page bernilai null. Perlakukan string kursor sebagai opak: jangan mengurai, memodifikasi, atau membuatnya sendiri. Daftar plugin dapat mengembalikan halaman dengan plugin yang lebih sedikit dari limit, atau tanpa plugin sama sekali, sementara next_page masih terisi, jadi teruslah meminta halaman hingga next_page bernilai null. Iterator daftar pada SDK Python, TypeScript, C#, Go, Java, dan Ruby serta CLI (kecuali dengan --format raw) melakukannya untuk Anda. Mereka meminta halaman berikutnya selama next_page terisi, sehingga halaman yang pendek atau kosong tidak menghentikannya. Di PHP dan curl, minta setiap halaman sendiri dan teruskan next_page-nya sebagai page.
limit memiliki default 20 dan minimum 1. Maksimumnya adalah 100 untuk plugin, pengaturan instalasi, dan pembagian, serta 1.000 untuk versi dan marketplace. Setiap daftar diurutkan dari yang terbaru.
Respons error
Respons error mengikuti bentuk standar yang didokumentasikan dalam Error Claude API. Sertakan request_id dari body respons saat menghubungi dukungan.
| Status | Arti |
|---|---|
| 400 | Input tidak valid, atau operasi tidak berlaku untuk plugin atau marketplace ini (lihat bagian masing-masing endpoint). Juga dikembalikan untuk parameter kueri yang tidak dikenali oleh endpoint, dan untuk organisasi yang bukan organisasi Claude Enterprise (this endpoint is not supported for this organization type). |
| 401 | Header x-api-key tidak ada, atau kunci tidak dikenali. |
| 403 | Kunci tidak memiliki scope yang diperlukan, atau permintaan mengunggah ke plugin atau marketplace pribadi milik anggota, mengubah versi yang disajikannya, atau menetapkan default-nya. (Menghapus plugin milik anggota diizinkan.) |
| 404 | Sumber daya tidak ditemukan. Juga dikembalikan ketika permintaan tidak menyertakan nilai anthropic-beta, atau API tidak diaktifkan untuk organisasi Anda, sehingga endpoint tampak seolah-olah tidak ada. |
| 409 | Sebuah nama sudah digunakan, content_scan suatu versi bernilai processing, atau ada unggahan yang bertentangan sedang berlangsung. |
| 413 | Body permintaan melebihi batas ukuran: 200 MB untuk unggahan, 32 MB untuk validasi marketplace. |
| 429 | “Rate limit” (batas laju) terlampaui. Lihat Pembatasan laju. |
| 500 | Error internal. |
| 503 | Sementara. Juga dikembalikan ketika beberapa penulisan pengaturan instalasi untuk satu plugin tiba pada saat yang sama; kirimkan penulisan tersebut satu per satu. Coba lagi dengan backoff, kecuali registration_pending (lihat tabel berikut). |
Ketika satu status memiliki beberapa penyebab yang perlu Anda tangani secara berbeda, error juga menyertakan error.details.error_code, serta error.details.plugin_id atau error.details.plugin_version_id ketika penyebabnya melibatkan salah satunya:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "...",
"details": {
"error_code": "plugin_name_taken",
"plugin_id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL"
}
},
"request_id": "req_018EeWyXxfu5pfWkrYcMdjWG"
}error_code | Status | Arti dan apa yang harus dilakukan |
|---|---|---|
plugin_name_taken | 409 | Marketplace sudah memegang nama ini. details.plugin_id adalah plugin yang memegang nama tersebut, dan mungkin orang lain yang membuatnya. Untuk mengetahui siapa, dapatkan plugin tersebut dan baca created_by-nya, yang bernilai null ketika tidak ada pembuat yang tercatat. Unggah versi ke plugin tersebut hanya jika itu adalah plugin yang ingin Anda perbarui. Jika tidak, atau ketika plugin_id tidak ada, unggah dengan nama lain. |
skill_name_taken | 409 | Plugin berada di marketplace pustaka dan salah satu skill-nya memiliki nama yang sama dengan skill organisasi (skill yang diunggah administrator untuk seluruh organisasi di claude.ai). details.skill_name menyebutkan namanya. Ganti nama atau hapus salah satunya. |
registration_pending | 503 | File telah disimpan, tetapi skill plugin belum dapat disediakan untuk anggota. Lihat Mencoba ulang unggahan. |
scan_pending | 409 | content_scan versi tersebut bernilai processing. Coba lagi setelah pemindaian selesai. |
scan_failed | 400 | content_scan versi tersebut bernilai fail, unknown, atau errored, sehingga tidak dapat disajikan. Pilih versi lain. |
cmek_key_disabled, cmek_key_network_blocked | 400 | Kunci enkripsi yang dikelola pelanggan milik organisasi Anda tidak tersedia. Lihat Kunci enkripsi yang dikelola pelanggan. |
unsupported_charset | 400 | Pada unggahan atau validate_archive, header Content-Type permintaan menyebutkan charset selain UTF-8, ISO-8859-1, atau US-ASCII. Kirim permintaan tanpa charset, atau dengan salah satu dari charset tersebut. |
Kode baru dapat ditambahkan. Perlakukan kode yang tidak Anda kenali sebagaimana Anda memperlakukan statusnya.
Mencoba ulang unggahan
Tidak ada endpoint yang menerima Idempotency-Key. Mengubah versi yang disajikan, menetapkan pengaturan instalasi, dan menetapkan default marketplace aman untuk diulang. Penghapusan yang diulang, atau penghapusan pengaturan instalasi yang diulang, mengembalikan 404.
Unggahan yang mengembalikan error tidak menyimpan apa pun, dengan satu pengecualian: 503 dengan error_code: "registration_pending". Setelah menyimpan file unggahan, server mendaftarkan skill versi baru ke claude.ai, yang membuat skill tersebut dapat digunakan oleh anggota; registration_pending berarti file telah disimpan tetapi langkah terakhir tersebut tidak selesai. Mengunggah file yang sama sekali lagi akan menyelesaikannya (dan menyimpan satu versi lagi yang identik):
- Pada
POST /v1/organizations/plugins, plugin telah dibuat, dan respons menyertakanx-should-retry: false: jangan kirim ulang permintaan pembuatan (pengiriman ulang mengembalikan409 plugin_name_taken); sebagai gantinya, unggah file yang sama sebagai versi daridetails.plugin_id. - Pada
POST /v1/organizations/plugins/{plugin_id}/versions, versi telah disimpan (details.plugin_version_id); kirim ulang permintaan yang sama ketika respons menyertakanx-should-retry: true, dan jangan lakukan ketika respons menyertakanfalse.
Jika respons pembuatan hilang, kirim permintaan pembuatan lagi. 409 plugin_name_taken berarti percobaan pertama telah menyimpan plugin atau nama tersebut memang sudah dipakai. Plugin di details.plugin_id dibuat oleh permintaan pembuatan Anda yang hilang hanya jika created_by-nya adalah api_actor dengan api_key_id milik kunci Anda. Periksa hal itu sebelum Anda mengunggah ke plugin tersebut (lihat plugin_name_taken di tabel sebelumnya). Mencoba ulang pembuatan versi yang responsnya hilang akan menyimpan versi kedua yang identik. Untuk menghindarinya, catat latest_version_id plugin sebelum setiap unggahan; jika respons hilang, baca plugin tersebut dan coba lagi hanya jika latest_version_id tidak berubah.
Event Activity Feed
Setiap penulisan melalui API ini dicatat di Activity Feed Compliance API organisasi Anda, diatribusikan ke kunci API sebagai api_actor yang membawa ID apikey_-nya. Aktor yang sama muncul di created_by pada plugin dan versi yang dibuat oleh kunci tersebut.
| Event | Dipancarkan ketika |
|---|---|
claude_plugin_created | Plugin dibuat melalui unggahan (di sini atau di claude.ai) atau melalui permintaan publikasi yang diterima. Plugin yang dibuat melalui sinkronisasi Git hanya memancarkan claude_plugin_version_created. |
claude_plugin_version_created | Sebuah versi disimpan. Versi yang disimpan melalui sinkronisasi Git diatribusikan ke system_actor. |
claude_plugin_updated | Versi baru diunggah ke plugin yang sudah ada. |
claude_plugin_served_version_updated | Versi yang disajikan berubah. |
claude_plugin_deleted | Plugin dihapus secara tersendiri, di sini atau di claude.ai. |
plugin_installation_preference_updated | Pengaturan instalasi ditetapkan atau dihapus. |
marketplace_created | Unggahan pertama membuat marketplace pustaka. |
marketplace_updated | Pengaturan instalasi default marketplace berubah, atau administrator atau pemilik memulai sinkronisasi di claude.ai. |
marketplace_deleted | Marketplace dihapus di claude.ai bersama dengan plugin-pluginnya (tanpa event per plugin). |
claude_plugin_archive_accessed | Arsip plugin milik anggota diunduh. |
claude_plugin_security_scan_completed | Pemindaian konten selesai. |
ID plugin, versi, dan marketplace dalam event ini adalah ID yang sama dengan yang dikembalikan oleh API ini. Event juga dapat menyebutkan marketplace yang tidak dicantumkan oleh API ini, seperti marketplace berisi plugin yang dipublikasikan Anthropic. plugin_installation_preference_updated mengidentifikasi plugin berdasarkan name dan marketplace_id-nya, bukan id-nya. Dalam claude_plugin_security_scan_completed, plugin_version bukan ID versi, dan tidak ada field dari versi plugin yang sesuai dengannya.
Mengubah default marketplace mencatat satu event marketplace_updated dan tidak ada event per plugin, meskipun perubahan tersebut mengubah nilai setiap plugin yang mewarisi default tersebut. Pembacaan tidak dicatat, kecuali unduhan arsip plugin milik anggota. Penulisan yang tidak mengubah apa pun tidak mencatat apa pun.
Pembagian yang diberikan atau ditarik di claude.ai muncul di feed sebagai event role_assignment_granted dan role_assignment_revoked. API ini tidak melaporkan penghapusan: plugin yang dihapus tidak muncul di daftar berikutnya. Plugin yang dihapus melalui sinkronisasi Git, melalui penghapusan marketplace-nya (satu event marketplace_deleted), atau melalui penghapusan akun anggota atau organisasi tidak memancarkan event per plugin, jadi tampilkan ulang daftar inventaris lengkap secara berkala untuk mendeteksi penghapusan.
Kunci enkripsi yang dikelola pelanggan
Jika organisasi Anda menggunakan kunci enkripsi yang dikelola pelanggan, description, release_notes, components, dan file suatu versi dienkripsi dengan kunci tersebut. Selama kunci tidak tersedia:
- Pembacaan dan daftar tetap berhasil, dengan
description,release_notes, dancomponentsdikembalikan sebagainull. - Unduhan arsip, pembuatan, pembuatan versi, dan perubahan versi yang disajikan mengembalikan
400dengancmek_key_disabledataucmek_key_network_blocked. - Menghapus plugin di marketplace pustaka mengembalikan
400 cmek_key_disableddan tidak menghapus apa pun, karena skill-nya harus terlebih dahulu ditarik dari claude.ai dan hal itu memerlukan kunci tersebut. Penghapusan lainnya, pengaturan instalasi, dan default marketplace berfungsi seperti biasa.
Memulihkan kunci akan menghilangkan semua kondisi ini.
Lihat juga
Tempat pemilik utama Anda membuat kunci dengan scope tertentu.
Endpoint grup yang menyediakan ID rbac_group_ yang digunakan dalam pengaturan instalasi.
Tempat penulisan plugin dan unduhan arsip anggota dicatat.
Pelaporan penggunaan plugin dan skill untuk Claude Enterprise.
Apakah halaman ini membantu?