--- title: Create Plugin Version url: https://platform.claude.com/docs/en/api/python/beta/organization/plugins/versions/create --- # Create Plugin Version `beta.organization.plugins.versions.create(plugin_id, **kwargs) -> BetaPluginVersion` **POST** `/v1/organizations/plugins/{plugin_id}/versions` Add a version to an organization-owned Plugin by uploading the new version's files; it becomes the version served to members unless the Plugin's served version has been pinned. The upload is the same `multipart/form-data` as creating a Plugin: the version's files (`files`, each part sent as `files[]`) and optional `release_notes`. The uploaded manifest's `name` must equal the Plugin's `name`. Returns the stored version; read the Plugin back to see which version it serves. Only a Plugin in a `manual` marketplace takes uploads; a Plugin synchronized from a repository gets its versions from the repository. When the Plugin is in the organization's library marketplace, a version that adds a skill with the name of an organization skill (a skill an administrator uploaded for the whole organization in claude.ai) is refused with a 409: `error_code` `skill_name_taken`, with that name in `details.skill_name`. A 503 with `error_code` `registration_pending` means the version was stored but is not yet usable; a later version create on the Plugin completes it. For a worked example, see [Create a version](https://platform.claude.com/docs/en/manage-claude/plugins-api?sdk_languages=python#create-a-version) in the Plugins API guide. **Accepted credentials:** an Admin API key with the `write:plugins` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. ## Parameters - `plugin_id: str` (path parameter) ID of the Plugin (prefixed `plugin_`). - `files: Sequence[FileTypes]` The version's files: one part per file, the part's filename being the file's path within the Plugin (for example `skills/review-pr/SKILL.md`), or a single `.zip` or `.plugin` archive holding them all. On the wire each part is named `files[]`, and a part named plain `files` is not read; with cURL, `-F 'files[]=@SKILL.md;filename=skills/review-pr/SKILL.md'`. The files must include the manifest, `.claude-plugin/plugin.json`. - `release_notes: Optional[str]` Release notes stored with the version and shown in its version history in claude.ai; up to 5,000 characters. maxLength: 5000 - `betas: Optional[List[AnthropicBetaParam]]` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. - `str` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` ## Returns - `class BetaPluginVersion` - `type: Literal["plugin_version"]` Always `plugin_version`. default: plugin_version - `id: str` The version's ID. - `components: Optional[List[BetaPluginComponent]]` What the version contains; null when not enumerated. - `type: Literal["agent", "cli", "command", 3 more]` The kind of component. - `"agent"` - `"cli"` - `"command"` - `"hook"` - `"mcp_server"` - `"skill"` - `description: Optional[str]` What the component declares about itself; always null for MCP servers, hooks, and CLIs. - `name: str` The component's name: a skill's, command's or agent's name, an MCP server's key in the manifest, the event a hook runs on, or a CLI's executable. - `content_scan: Optional[BetaPluginContentScan]` This version's content scan; null when it has not been scanned. - `assessment: Optional[Literal["fail", "pass", "unknown", "warn"]]` The scan's verdict; set only when `status` is `completed`. - `"fail"` - `"pass"` - `"unknown"` - `"warn"` - `reason: Optional[str]` The primary mechanism behind a `warn` or `fail`, such as `credential-exposure` or `guardrail-tampering`; a mechanism this API does not yet name reads as `other`. Null on a `pass`, whenever `assessment` is null, and when no mechanism is reported for the verdict. - `status: Literal["completed", "errored", "processing"]` `processing` while a scan runs, `completed` when it ran to completion, `errored` when it could not run or its outcome cannot be read. - `"completed"` - `"errored"` - `"processing"` - `created_at: datetime` RFC 3339. format: date-time - `created_by: Optional[CreatedBy]` Who uploaded this version; null when not recorded. - `class BetaPluginUserActor` - `type: Literal["user_actor"]` A member of the organization. default: user_actor - `email_address: Optional[str]` The member's email address; may be null, for example when they are no longer a member of the organization. - `user_id: str` The member's User ID. - `class BetaPluginAPIActor` - `type: Literal["api_actor"]` An Admin API key, in the same form the Compliance API activity feed uses for it. default: api_actor - `api_key_id: str` The key's ID. - `description: Optional[str]` The manifest's description; null when it declares none. - `display_name: Optional[str]` The manifest's display name; null when it declares none. - `manifest_version: Optional[str]` The version string the manifest declares; null when it declares none. - `plugin_id: str` The Plugin's ID. - `reach: Optional[Literal["contained", "privileged", "remote"]]` How far the version reaches: `remote`, `privileged` or `contained`, as on the Plugin; null when not classifiable. - `"contained"` - `"privileged"` - `"remote"` - `release_notes: Optional[str]` As supplied with the upload; null when none were supplied. ## Example ```python import os from anthropic import Anthropic client = Anthropic( api_key=os.environ.get( "ANTHROPIC_API_KEY" ), # This is the default and can be omitted ) beta_plugin_version = client.beta.organization.plugins.versions.create( plugin_id="plugin_id", files=[b"Example data"], ) print(beta_plugin_version.id) ``` ### Response (200) ```json { "id": "pluginver_01KaZmQpRsTuVwXyZ2b4c6d8", "components": [ { "description": "description", "name": "review-pr", "type": "skill" } ], "content_scan": { "assessment": "warn", "reason": "credential-exposure", "status": "completed" }, "created_at": "2026-03-14T09:26:53.589793Z", "created_by": { "email_address": "user@example.com", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "description": "Reviews pull requests against your team's conventions.", "display_name": "Code Review Helper", "manifest_version": "1.2.0", "plugin_id": "plugin_01JyHfbRkZvD1gW7oTqXc3Ne", "reach": "contained", "release_notes": "Adds a review checklist for database migrations.", "type": "plugin_version" } ```