Plugins

Package plugin is what each host is running, and how to change it: enable, disable, reload, or pin a service to a version.

plugins

DELETE /v1/plugins/authored/{id}

Removes one of the caller org's built plugins, so the runtime can no longer load it. Scoped to the caller's org, so an id belonging to another tenant answers 404 and is not deleted.

GET /v1/plugins/authored

Lists the plugins the caller's org BUILT, newest first, each with the TypeScript as authored. That is a different set with a different lifecycle from GET /v1/plugins, which reports the subsystems this deployment mounted. The bundled CommonJS the runtime executes is never included, and neither is any credential — a plugin names the connectors provider it needs and reads the credential from ctx.auth at run time.

POST /v1/plugins/build

Build a plugin for your org from TypeScript, or from an API spec a model writes it from

Builds one plugin for the caller's org and answers 201 with the bundle's size, whether a model wrote the source, and the plugin as stored. Post source to build TypeScript as-is, or spec — an OpenAPI document or plain prose describing the endpoints — to have one generated; the generated source comes back in the answer, so a caller reads what will run before it runs. Exactly one of the two, and name must be one lowercase path segment; both or neither is 400.

COMPILING IS THE GATE. The source goes through the same pipeline the committed connectors do — esbuild to one CommonJS program, then compiled in the goja runtime that will actually execute it — and anything that fails is rejected and NEVER stored. So a plugin in the store is one this deployment has already loaded once, not one a model claimed was fine. A failed build answers 422 carrying the diagnostics a caller needs to fix it: the bundler's error, the source that failed, and whether the model wrote it — a body outside the declared success shape.

CREDENTIALS ARE NOT PART OF A PLUGIN. A plugin names the connectors provider it needs and reads that credential from ctx.auth at run time, under KMS custody. Source that contains something shaped like a key is REFUSED rather than silently scrubbed, so a caller who pasted one finds out instead of shipping it — register it as a connector instead.

Requires a validated principal; 403 without one. The plugin is stored under that principal's org and is what /v1/plugins/authored lists — never /v1/plugins, which is this deployment's mounted-subsystem inventory. Source over 512 KiB or a spec over 256 KiB is refused. Posting a spec to a deployment with no AI client configured is 503, and a generation that fails upstream is 502.

Request body — application/json

GET /v1/plugins

Reports what this deployment actually mounted: every subsystem the composition root declared and whether it is switched on. A plugin here is MOUNTED CODE that extends the deployment's own surface — not a tool an agent calls — so this is an inventory and not a tool source. It is read off the same boot snapshot every traced request resolves its subsystem label against, so it cannot drift from what is serving. Enabled-only by default, because a caller asking what this deployment can do wants what is running; ?all=true adds the configured-but-off ones.

---

All Hanzo APIs · Interactive reference