---
title: "Install a plugin"
method: POST
path: "/api/v1beta/plugins"
tags: ["plugins"]
---

# Install a plugin

`POST /api/v1beta/plugins`

Install a plugin from a remote source

## Request body

- union
  - object
  - PkgApiV1InstallPluginRequest — Request to install a plugin
    - `allow_unsigned` boolean — AllowUnsigned permits installing a project-scoped plugin without a verified signature; the exception is recorded in the project's lock file.
    - `clients` string[] — Clients lists target client identifiers (e.g., "claude-code"), or ["all"] to target every plugin-supporting client. Omitting this field installs to all available clients.
    - `force` boolean — Force allows overwriting unmanaged plugin directories
    - `group` string — Group is the group name to add the plugin to after installation
    - `name` string — Name or OCI reference of the plugin to install
    - `project_root` string — ProjectRoot is the project root path for project-scoped installs
    - `scope` 'user' | 'project' — Scope for the installation
    - `version` string — Version to install (empty means latest)

## Response `201`

Created

- PkgApiV1InstallPluginResponse — Response after successfully installing a plugin
  - `plugin` GithubComStacklokToolhivePkgPluginsInstalledPlugin — InstalledPlugin contains the full installation record.
    - `clients` string[] — Clients is the list of client identifiers the plugin is installed for.
    - `components` GithubComStacklokToolhivePkgPluginsComponentInventory — Components is the inventory of component types declared by the plugin (e.g. {"commands": 3, "skills": 2}). Extracted from the OCI artifact.
    - `dependencies` GithubComStacklokToolhivePkgPluginsDependency[] — Dependencies is the list of external plugin dependencies.
      - `digest` string — Digest is the OCI digest for upgrade detection.
      - `name` string — Name is the dependency name.
      - `reference` string — Reference is the OCI reference for the dependency.
    - `digest` string — Digest is the OCI digest (sha256:...) for upgrade detection.
    - `installed_at` string — InstalledAt is the timestamp when the plugin was installed.
    - `managed` boolean — Managed indicates this install is tracked in the project's toolhive.lock.yaml plugins: key. Only ever true for project-scoped installs. No omitempty: false is an observable state (unmanaged), not an absence.
    - `metadata` GithubComStacklokToolhivePkgPluginsPluginMetadata — Metadata contains the plugin's metadata.
      - `author` string — Author is the plugin author or maintainer.
      - `description` string — Description is a human-readable description of the plugin.
      - `keywords` string[] — Keywords is a list of keywords for categorization/search.
      - `license` string — License is the SPDX license identifier for the plugin.
      - `name` string — Name is the unique name of the plugin (kebab-case).
      - `version` string — Version is the semantic version of the plugin.
    - `project_root` string — ProjectRoot is the project root path for project-scoped plugins. Empty for user-scoped.
    - `reference` string — Reference is the full OCI reference (e.g. ghcr.io/org/plugin:v1).
    - `scope` 'user' | 'project' — Scope for the installation
    - `signature` string — Signature is the optional signing signature for the plugin artifact.
    - `status` 'installed' | 'pending' | 'failed' — Status is the current installation status.
    - `tag` string — Tag is the OCI tag (e.g. v1.0.0).

## Other responses

- `400` — Bad Request
- `401` — Unauthorized (registry refused credentials)
- `404` — Not Found (artifact not present in registry)
- `409` — Conflict
- `429` — Too Many Requests (registry rate limit)
- `500` — Internal Server Error
- `502` — Bad Gateway (upstream registry failure)
- `504` — Gateway Timeout (upstream pull timed out)

---

[API](https://skmtc.dev/stacklok/apis/toolhive-api.md) · [All operations](https://skmtc.dev/stacklok/apis/toolhive-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stacklok/toolhive-api/revisions/e9f942effcda/schema)