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:
200 OK – plugin_id and bindings
400 Bad Request – plugin query param missing or invalid
403 Forbidden – caller is not loopback
500 Internal Server Error – grant read failed
- 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:
200 OK – key and enabled flag
403 Forbidden – caller is not loopback
- 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:
200 OK – plugin_id and serial
400 Bad Request – plugin query param missing or invalid
403 Forbidden – caller is not loopback
500 Internal Server Error – serial read failed
- 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:
200 OK – recorded ack
400 Bad Request – invalid body or plugin ID
403 Forbidden – caller is not loopback
500 Internal Server Error – ack write failed
- 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:
200 OK – plugins list
403 Forbidden – missing required permission
500 Internal Server Error – catalog or desired state read failed
- 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:
200 OK – activity rows and count
403 Forbidden – missing required permission
500 Internal Server Error – activity read failed
- GET /plugins/capabilities
List capability bindings
Returns all capability bindings.
- Status Codes:
200 OK – bindings list
403 Forbidden – missing required permission
500 Internal Server Error – bindings read failed
- 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:
200 OK – existing entry, idempotent re-seed
201 Created – created entry
400 Bad Request – invalid body or manifest refused
403 Forbidden – missing required permission
409 Conflict – catalog entry exists with a different manifest, or bundle not compatible with this core (PLUGIN_BUNDLE_INCOMPATIBLE)
500 Internal Server Error – catalog read or write failed
- 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:
200 OK – icons keyed by plugin ID
403 Forbidden – missing required permission
500 Internal Server Error – icon read failed
- 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:
200 OK – import result from the helper
400 Bad Request – unreadable request body
403 Forbidden – missing required permission
413 Request Entity Too Large – bundle exceeds the import size limit
422 Unprocessable Entity – bundle refused by the import helper
500 Internal Server Error – spool write failed
- 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:
200 OK – per-plugin status list
403 Forbidden – missing required permission
500 Internal Server Error – desired state or node status read failed
- 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:
200 OK – label, plugins projection, optional mesh_peers and denylist
500 Internal Server Error – desired state read failed
- 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:
200 OK – blob content
206 Partial Content – partial blob content
400 Bad Request – bad digest
404 Not Found – no such artifact
429 Too Many Requests – serve saturated; retry after backoff
- 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:
200 OK – bundle content
206 Partial Content – partial bundle content
400 Bad Request – bad digest
404 Not Found – no such artifact
429 Too Many Requests – serve saturated; retry after backoff
- 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:
200 OK – plugin_id, cn, san_ip and leaf_chain_pem
400 Bad Request – plugin_id and csr are required
401 Unauthorized – no attested node identity
403 Forbidden – plugin not enabled for agent delivery
409 Conflict – plugin declares no tls-cert dependency
502 Bad Gateway – certificate signing failed
- 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:
200 OK – downloads list
403 Forbidden – missing required permission
- GET /plugins/store/entitlement
Get cluster plugin entitlement
Returns this cluster’s commercial entitlement status and whether licensed plugins are installable.
- Status Codes:
200 OK – entitlement status
403 Forbidden – missing required permission
- 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:
200 OK – plugin_id, node_id and observed_state
400 Bad Request – missing or invalid plugin_id or observed_state
401 Unauthorized – no attested node identity
403 Forbidden – plugin does not target agents
500 Internal Server Error – status write failed
- 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:
200 OK – source config
403 Forbidden – missing required permission
- 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:
200 OK – ok, url and config file path
400 Bad Request – invalid body, missing url or url not http(s)
403 Forbidden – missing required permission
500 Internal Server Error – config write failed
- 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:
200 OK – probe result
403 Forbidden – missing required permission
- GET /plugins/store/state
Get plugin store state
Returns the plugin store state view.
- Status Codes:
200 OK – store state
403 Forbidden – missing required permission
500 Internal Server Error – store state read failed
- 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:
200 OK – plugin catalog, desired state and nodes
400 Bad Request – invalid plugin ID
403 Forbidden – missing required permission
404 Not Found – plugin not in catalog
500 Internal Server Error – catalog read failed
- 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:
200 OK – binding on bind; interface, version_major and released on unbind
400 Bad Request – invalid plugin ID, invalid body or interface not provided by the plugin
403 Forbidden – missing required permission
404 Not Found – plugin not installed
409 Conflict – capability held by another plugin
500 Internal Server Error – catalog, manifest or binding write failed
- 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:
202 Accepted – op_id, plugin_id, spec_hash and desired
400 Bad Request – invalid plugin ID, or force without a reason
403 Forbidden – missing required permission, or force by a non-administrator
404 Not Found – plugin not installed
409 Conflict – removal of the IPAM and inventory authority without force (PLUGIN_SOLE_AUTHORITY)
500 Internal Server Error – desired state write failed
- 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:
202 Accepted – download status
400 Bad Request – plugin id required
403 Forbidden – missing required permission or cluster not entitled to this licensed plugin
503 Service Unavailable – download source could not be resolved
- 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:
202 Accepted – op_id, plugin_id, spec_hash and desired
400 Bad Request – invalid plugin ID, or force without a reason
403 Forbidden – missing required permission, or force by a non-administrator
404 Not Found – plugin not installed
409 Conflict – removal of the IPAM and inventory authority without force (PLUGIN_SOLE_AUTHORITY)
500 Internal Server Error – desired state write failed
- 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:
202 Accepted – op_id, plugin_id, spec_hash and desired
400 Bad Request – invalid plugin ID or body
403 Forbidden – missing required permission
404 Not Found – plugin version not in catalog
409 Conflict – bundle version not compatible with this core (PLUGIN_BUNDLE_INCOMPATIBLE)
500 Internal Server Error – manifest no longer validates or desired state write failed
- 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:
202 Accepted – op_id, plugin_id, spec_hash and desired
400 Bad Request – invalid plugin ID, or force without a reason
403 Forbidden – missing required permission, or force by a non-administrator
404 Not Found – plugin not installed
409 Conflict – removal of the IPAM and inventory authority without force (PLUGIN_SOLE_AUTHORITY)
500 Internal Server Error – desired state write failed
- 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:
202 Accepted – plugin_id and resumed flag
400 Bad Request – invalid plugin ID
403 Forbidden – missing permission required by the parked desired state
404 Not Found – plugin not installed
- 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:
200 OK – retention override
400 Bad Request – invalid plugin ID, invalid body or retention_days not greater than 0
403 Forbidden – missing required permission
500 Internal Server Error – retention override write failed
- 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:
200 OK – plugin state, converged flag, desired state and nodes
400 Bad Request – invalid plugin ID
403 Forbidden – missing required permission
- 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:
200 OK – binding on bind; interface, version_major and released on unbind
400 Bad Request – invalid plugin ID, invalid body or interface not provided by the plugin
403 Forbidden – missing required permission
404 Not Found – plugin not installed
409 Conflict – capability held by another plugin
500 Internal Server Error – catalog, manifest or binding write failed
- 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:
202 Accepted – op_id, plugin_id, spec_hash and desired
400 Bad Request – invalid plugin ID, or force without a reason
403 Forbidden – missing required permission, or force by a non-administrator
404 Not Found – plugin not installed
409 Conflict – removal of the IPAM and inventory authority without force (PLUGIN_SOLE_AUTHORITY)
500 Internal Server Error – desired state write failed