plugins

GET /plugin-broker/v1/bindings

List broker grant bindings

Loopback-listener only; returns the non-secret grant projection for a plugin.

Query Parameters:
  • plugin (string) – Plugin ID

Status Codes:
GET /plugin-broker/v1/features/{key}

Get a feature flag

Loopback-listener only; reports whether a feature key is enabled (unset keys are disabled).

Parameters:
  • key (string) – Feature key

Status Codes:
GET /plugin-broker/v1/serial

Get broker bundle serial

Loopback-listener only; returns the current bundle serial for a plugin, or the max grant generation when no file reader is wired.

Query Parameters:
  • plugin (string) – Plugin ID

Status Codes:
POST /plugin-broker/v1/serial-ack

Acknowledge a broker serial

Loopback-listener only; upserts the serial a node reports having adopted for a plugin.

Status Codes:
Response JSON Object:
  • acked_at (string)

  • node_id (string)

  • plugin_id (string)

  • serial (integer)

GET /plugins

List plugins

Returns every catalog entry with its desired state and a has_icon flag; the icon itself is omitted.

Status Codes:
GET /plugins/activity

List plugin activity

Returns the plugin lifecycle log newest first, optionally filtered by plugin and paged by before_id.

Query Parameters:
  • plugin_id (string) – Filter by plugin ID

  • limit (integer) – Page size (default 50, max 500)

  • before_id (integer) – Return rows with id lower than this

Status Codes:
GET /plugins/capabilities

List capability bindings

Returns all capability bindings.

Status Codes:
POST /plugins/catalog

Seed a plugin catalog entry

Parses a plugin manifest and writes a catalog row; re-seeding the same manifest returns the existing row.

Status Codes:
Response JSON Object:
  • created_at (string)

  • data_epoch (integer)

  • description (string)

  • display_name (string)

  • icon (string)

  • plugin_id (string)

  • spec_hash (string) – sha256 of the manifest bytes

  • vendor (string)

  • version (string)

  • version_digest (string) – bundle content address

  • created_at

  • data_epoch

  • description

  • display_name

  • icon

  • plugin_id

  • spec_hash – sha256 of the manifest bytes

  • vendor

  • version

  • version_digest – bundle content address

GET /plugins/icons

List plugin icons

Returns a map of plugin ID to stored icon data URI for plugins that have an icon.

Status Codes:
POST /plugins/import

Import a plugin bundle

Streams an uploaded .kbundle (multipart field bundle or raw octet-stream body) to a spool file and imports it through the helper subprocess.

Status Codes:
GET /plugins/status

Get status of all plugins

Returns the folded status of every plugin that has a desired-state row, in the same shape as the per-plugin status route.

Status Codes:
GET /plugins/store/agent-desired

Get agent desired plugin state

Returns the desired-state projection for the calling agent with bundle index digests for enabled entries, plus mesh peers and denylist when available.

Query Parameters:
  • label (string) – Agent selector label

Status Codes:
Request Headers:
  • X-Karios-Attested-Node-Ip – edge-attested node IP; set by the edge from the validated node cert

GET /plugins/store/blobs/{digest}

Get a plugin store blob

Streams an individual OCI blob by digest, with Range support; excess concurrent requests are shed with 429.

Parameters:
  • digest (string) – Blob digest (sha256:<64-hex>)

Status Codes:
GET /plugins/store/bundle/{digest}

Get a plugin store bundle

Streams the retained signed .kbundle for an index digest, with Range support; excess concurrent requests are shed with 429.

Parameters:
  • digest (string) – Bundle index digest (sha256:<64-hex>)

Status Codes:
POST /plugins/store/cert/sign

Sign an agent plugin CSR

Signs an agent CSR for a plugin with the CN from its stored manifest and the IP-SAN from the edge-attested node IP.

Request JSON Object:
  • csr (string) – PEM CERTIFICATE REQUEST; the agent’s public key only

  • plugin_id (string)

Status Codes:
Request Headers:
  • X-Karios-Attested-Node-Ip – edge-attested node IP; set by the edge from the validated node cert

GET /plugins/store/downloads

List plugin downloads

Returns the progress of online plugin downloads.

Status Codes:
GET /plugins/store/entitlement

Get cluster plugin entitlement

Returns this cluster’s commercial entitlement status and whether licensed plugins are installable.

Status Codes:
POST /plugins/store/node-status

Report agent plugin status

Upserts the plugin node status row for the edge-attested node from the agent’s reported observation.

Request JSON Object:
  • applied_spec_hash (string)

  • observed_state (string)

  • observed_version (string)

  • plugin_id (string)

  • typed_error (string)

Status Codes:
Request Headers:
  • X-Karios-Attested-Node-Ip – edge-attested node IP; set by the edge from the validated node cert

GET /plugins/store/source

List plugins in the source index

Returns the entries of the configured source index; fetch errors are reported in the body with status 200.

Status Codes:
  • 200 OK – configured flag, plugins and optional error

  • 403 Forbidden – missing required permission

GET /plugins/store/source-config

Get plugin source config

Returns the current plugin source base URL, where it came from, the built-in default and the config file path.

Status Codes:
PUT /plugins/store/source-config

Set plugin source config

Persists the plugin source base URL to the config file; it applies to the next request without restart.

Status Codes:
POST /plugins/store/source-config/test

Test plugin source config

Probes the plugin index at the given or configured base URL and reports reachability, status, plugin count and latency.

Status Codes:
GET /plugins/store/state

Get plugin store state

Returns the plugin store state view.

Status Codes:
Response JSON Object:
  • catalog_epoch (integer)

  • channel (string)

  • file_epoch (integer)

  • file_index_digest (string)

  • imported_at (string)

  • imported_by (string)

  • index_digest (string)

GET /plugins/{id}

Get a plugin

Returns the catalog versions, desired state and per-node status rows of one plugin.

Parameters:
  • id (string) – Plugin ID

Status Codes:
POST /plugins/{id}/bind

Bind or unbind a plugin capability

Binds (bind route) or releases (unbind route) the capability interface the installed plugin version provides.

Parameters:
  • id (string) – Plugin ID

Status Codes:
POST /plugins/{id}/disable

Set plugin desired state

Writes the target desired state (enabled, disabled, archived or absent per route) for an installed plugin and nudges the reconciler. Uninstall and purge refuse the IPAM and inventory authority unless an administrator forces it with a reason.

Parameters:
  • id (string) – Plugin ID

Request JSON Object:
  • force (boolean)

  • reason (string)

Status Codes:
POST /plugins/{id}/download

Download and import a plugin

Starts a detached download of the plugin bundle from the configured source index and returns the current download status.

Parameters:
  • id (string) – Plugin ID

Status Codes:
Response JSON Object:
  • done (integer)

  • error (string)

  • percent (integer)

  • plugin_id (string)

  • state (string) – downloading | importing | ready | error

  • total (integer)

  • updated_unix (integer)

  • version (string)

POST /plugins/{id}/enable

Set plugin desired state

Writes the target desired state (enabled, disabled, archived or absent per route) for an installed plugin and nudges the reconciler. Uninstall and purge refuse the IPAM and inventory authority unless an administrator forces it with a reason.

Parameters:
  • id (string) – Plugin ID

Request JSON Object:
  • force (boolean)

  • reason (string)

Status Codes:
POST /plugins/{id}/install

Install a plugin

Upserts the desired-state row for a catalog version and nudges the reconciler; returns the op for the resulting desired state.

Parameters:
  • id (string) – Plugin ID

Status Codes:
POST /plugins/{id}/purge

Set plugin desired state

Writes the target desired state (enabled, disabled, archived or absent per route) for an installed plugin and nudges the reconciler. Uninstall and purge refuse the IPAM and inventory authority unless an administrator forces it with a reason.

Parameters:
  • id (string) – Plugin ID

Request JSON Object:
  • force (boolean)

  • reason (string)

Status Codes:
POST /plugins/{id}/resume

Resume a paused plugin

Re-drives a paused-by-system plugin after checking the permission required by its parked desired state.

Parameters:
  • id (string) – Plugin ID

Status Codes:
POST /plugins/{id}/retention

Set plugin archive retention

Upserts the operator archive-retention override for a plugin; retention_days must be greater than 0.

Parameters:
  • id (string) – Plugin ID

Status Codes:
Response JSON Object:
  • plugin_id (string)

  • retention_days (integer)

  • updated_at (string)

  • updated_by (string)

GET /plugins/{id}/status

Get plugin status

Returns the folded state and converged flag of one plugin, derived from its desired state and node rows.

Parameters:
  • id (string) – Plugin ID

Status Codes:
POST /plugins/{id}/unbind

Bind or unbind a plugin capability

Binds (bind route) or releases (unbind route) the capability interface the installed plugin version provides.

Parameters:
  • id (string) – Plugin ID

Status Codes:
POST /plugins/{id}/uninstall

Set plugin desired state

Writes the target desired state (enabled, disabled, archived or absent per route) for an installed plugin and nudges the reconciler. Uninstall and purge refuse the IPAM and inventory authority unless an administrator forces it with a reason.

Parameters:
  • id (string) – Plugin ID

Request JSON Object:
  • force (boolean)

  • reason (string)

Status Codes: