Plugins

See the OpenAPI document 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
POST	/v1/api/plugins	Install a plugin with encrypted inputs
DELETE	/v1/api/plugins/{id}	Remove a plugin from subsequent runs
GET	/v1/api/plugins/{id}	Read a plugin installation
PATCH	/v1/api/plugins/{id}	Update plugin setup, version or project availability
GET	/v1/api/plugins/catalog	Browse official MCP Registry recipes
GET	/v1/api/plugins/catalog/detail	Read MCP Registry details and a public repository README
POST	/v1/api/plugins/import-archive	Preview a standard plugin or Agent Skills ZIP
POST	/v1/api/plugins/preview	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

Browse endpoints, request fields and responses.

API & OpenAPI

Download the contract, generate a client, and read the compatibility policy.

TypeScript SDK

Auth, retries, typed errors, uploads and streaming, already built.

CLI reference

The same operations from a terminal, with a stable JSON envelope.