# Plugins

See the [OpenAPI document](/openapi.json) for schemas and operation IDs.

## Prerequisites

- Protected operations require an API key in `x-api-key` or a browser session cookie; some actions require a verified user session
- Tenant-scoped operations use `X-Organization-Id`; browser sessions can use their active workspace. Discovery and personal-workspace bootstrap do not require an active workspace
- The base URL for your deployment, `https://server.hlix.ai` by default

## Operations

| Method | Path | Operation |
| --- | --- | --- |
| `GET` | `/v1/api/plugins` | [List installed workspace plugins](#list-installed-workspace-plugins) |
| `POST` | `/v1/api/plugins` | [Install a plugin with encrypted inputs](#install-a-plugin-with-encrypted-inputs) |
| `DELETE` | `/v1/api/plugins/{id}` | [Remove a plugin from subsequent runs](#remove-a-plugin-from-subsequent-runs) |
| `GET` | `/v1/api/plugins/{id}` | [Read a plugin installation](#read-a-plugin-installation) |
| `PATCH` | `/v1/api/plugins/{id}` | [Update plugin setup, version or project availability](#update-plugin-setup-version-or-project-availability) |
| `GET` | `/v1/api/plugins/catalog` | [Browse official MCP Registry recipes](#browse-official-mcp-registry-recipes) |
| `GET` | `/v1/api/plugins/catalog/detail` | [Read MCP Registry details and a public repository README](#read-mcp-registry-details-and-a-public-repository-readme) |
| `POST` | `/v1/api/plugins/import-archive` | [Preview a standard plugin or Agent Skills ZIP](#preview-a-standard-plugin-or-agent-skills-zip) |
| `POST` | `/v1/api/plugins/preview` | [Validate a plugin manifest without installing](#validate-a-plugin-manifest-without-installing) |

## List installed workspace plugins

`GET /v1/api/plugins` · operation ID `listPlugins`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `projectId` | query | no | string | Only enabled plugins available to this project. |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | PluginListResponse | Safe installation metadata; secret inputs never read back. |
| `400` | ApiError \| ValidationError | Invalid manifest, setup inputs or project scope. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner or admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Install a plugin with encrypted inputs

`POST /v1/api/plugins` · operation ID `installPlugin`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `CreatePlugin` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `inputs` | object | **yes** |  |
| `manifest` | object | **yes** |  |
| `projectIds` | string (uuid)[] \| null | **yes** |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `201` | PluginResponse | Installation created. |
| `400` | ApiError \| ValidationError | Invalid manifest, setup inputs or project scope. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner or admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Remove a plugin from subsequent runs

`DELETE /v1/api/plugins/{id}` · operation ID `removePlugin`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | PluginRemoveResponse | Removed. Running jobs keep their resolved configuration. |
| `400` | ApiError \| ValidationError | Invalid manifest, setup inputs or project scope. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner or admin. |
| `404` | ApiError | Plugin not found. |

## Read a plugin installation

`GET /v1/api/plugins/{id}` · operation ID `getPlugin`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | PluginResponse | Installation with nonsecret inputs only. |
| `400` | ApiError \| ValidationError | Invalid manifest, setup inputs or project scope. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner or admin. |
| `404` | ApiError | Plugin not found. |

## Update plugin setup, version or project availability

`PATCH /v1/api/plugins/{id}` · operation ID `updatePlugin`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `UpdatePlugin` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `enabled` | boolean | no |  |
| `inputs` | object | no |  |
| `manifest` | object | no |  |
| `projectIds` | string (uuid)[] \| null | no |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | PluginResponse | Updated installation. Omitted inputs are preserved; null explicitly removes an input. |
| `400` | ApiError \| ValidationError | Invalid manifest, setup inputs or project scope. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner or admin. |
| `404` | ApiError | Plugin not found. |

## Browse official MCP Registry recipes

`GET /v1/api/plugins/catalog` · operation ID `listPluginCatalog`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `search` | query | no | string | Registry search text. |
| `cursor` | query | no | string | Opaque next cursor paired with the same search. |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | PluginCatalogResponse | Compatible recipes, with explanations for unsupported alternatives. |
| `400` | ApiError \| ValidationError | Invalid manifest, setup inputs or project scope. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner or admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |
| `503` | ApiError | Registry unavailable. |

## Read MCP Registry details and a public repository README

`GET /v1/api/plugins/catalog/detail` · operation ID `getPluginCatalogDetail`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `name` | query | **yes** | string | Canonical MCP Registry server name. |
| `version` | query | no | string | Exact registry version or latest (default). |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | PluginCatalogDetailResponse | Setup remains available when README content is missing or unavailable. |
| `400` | ApiError \| ValidationError | Invalid manifest, setup inputs or project scope. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner or admin. |
| `404` | ApiError | Server version not found. |
| `503` | ApiError | Registry unavailable. |

## Preview a standard plugin or Agent Skills ZIP

`POST /v1/api/plugins/import-archive` · operation ID `importPluginArchive`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/zip` (required)

The contract does not pin this body's properties.

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | PluginArchivePreviewResponse | Validated manifest; no installation or backend execution. ZIP limit 5 MB, decompressed text 2 MB total/200 KB per file, 500 entries. |
| `400` | ApiError \| ValidationError | Invalid manifest, setup inputs or project scope. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner or admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |
| `413` | ApiError | Archive exceeds the request size limit. |
| `415` | ApiError | Content-Type must be application/zip. |

## Validate a plugin manifest without installing

`POST /v1/api/plugins/preview` · operation ID `previewPlugin`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `PreviewPlugin` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `manifest` | object | **yes** |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | PluginPreviewResponse | Structurally valid manifest; no connectivity claim. |
| `400` | ApiError \| ValidationError | Invalid manifest, setup inputs or project scope. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner or admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## If a request fails

The response table for each operation lists its documented errors. Common status codes include:

- `400` — the body failed schema validation, or the request named no active organization. A `ValidationError` body carries the failing fields; an `ApiError` body carries only `error`.
- `401` — no valid session or API key.
- `403` — authenticated, but not a member of the named organization, or a client collaborator without the required access.
- `404` — check the resource ID and your access to the selected Workspace.
- `409` — the expected revision or state is stale, or another operation currently owns the transition.
- `500` — the operation failed server-side. Retry only where an idempotency key makes that safe.

## Next steps

[API reference](/api/reference/)
  [API & OpenAPI](/api/openapi/)
  [TypeScript SDK](/sdk/typescript/)
  [CLI reference](/reference/cli/)