Skip to main content
These two routes serve the capability inventory: one merged list of every skill, tool and connector across the five runtimes and Clawboo’s own connectors. GET /api/capabilities is the read behind the Org chart and the Capabilities panel. POST /api/capabilities/:action installs a curated skill or connector, turns a manageable capability on or off, or answers a pending tool-call approval. The read asks six sources (native, hermes, claude-code, codex, openclaw, and connector for the MCP connectors Clawboo runs itself) and merges their answers. A source that answers has its rows saved; a source that fails is served from its last saved rows, so a dropped Gateway connection never empties the inventory. The response also says how each source read went.
What you can do to a capability depends only on its manageability tier. managed and external-write rows are writable; observe-only rows (runtime built-ins, outside command-line tools) are read-only and refuse enable and disable with 422. A runtime-of-record row can also be read-only when its source marks it writable: false. See Capabilities for the tiers.
Both routes are on the general rate tier (see rate limits).

Routes


GET /api/capabilities

Returns the merged records and a read status for every source. When two records share an id, a fresh one wins over a saved one. Filters apply after the merge, so an unknown filter value returns an empty records list, not an error. This read also writes. It saves every source that answered, and it stamps grant details onto connector records: it creates the owner grant for a connector an agent’s own runtime already attaches (create-only, so a grant you revoked stays revoked), and it adds a read-only copy of a connector record for each other agent that holds a grant on it (synthetic: true).
  • Path params: none.
  • Query params:
Each param is applied only when present and non-empty; omit all four for the full inventory.
  • Request body: none.

Responses

200 OK: the merged view:
sources reports how each source read went. A source with ok: false, degraded: true did not answer; its records are the last saved rows, served unchanged so the inventory stays filled through a disconnect. health: 'drift' means the connector’s tool list no longer matches the one that was approved: re-check what changed before trusting it again. trifecta marks which of three risks a connector brings: reading private data, taking in untrusted content, and sending data out. All three together is the combination to watch. 500 Internal Server Error: any failure loading the inventory (the message is redacted):

Example


POST /api/capabilities/:action

enable, disable and approve take the person check: anything else gets 403 { "ok": false, "error": "person_only" }. install is open. Enabling and disabling decides what a runtime may use at all, such as OpenClaw’s tools.allow and tools.deny. One route for four actions, chosen by the :action segment. install adds a curated skill or connector to an agent; enable and disable turn an existing manageable capability on or off by its id; approve answers a pending tool-call approval. install, enable and disable go to the source that owns the capability, which also writes the audit record. approve answers exactly as POST /api/tools/approvals/:id/resolve does.
  • Path params: action (one of install | enable | disable | approve; any other value returns 400).
  • Request body: shape depends on :action (below).

Action: install

Installs a skill or connector on an agent. Send the install spec as the body, or nested under spec. The agent must exist (an unknown agentId is a 404). The server takes the agent’s runtime from its own record, so the runtime you send is replaced before the write. Request body:
With via: 'native', name and skillContent are scanned for prompt injection, and any mcpServer command, arguments and environment are scanned more strictly. A blocked install writes an install audit row and answers 422:
400 Bad Request: the body is not a valid install spec (via, agentId, runtime, kind or name missing or not a string):
404 Not Found: no agent with that agentId:
200 OK: the capability was installed; the fresh record is returned (or null for an acknowledgement that yields no new row):
422 Unprocessable Entity: the owning source does not take this write for its tier (for example via: 'connector', or an observe-only source):
503 Service Unavailable: an install through OpenClaw while the Gateway connection is down:

Action: enable / disable

Turns an existing capability on or off by its id. The route looks the row up first and applies the same tier the panel shows: an observe-only capability, or one its source marked writable: false, is refused with 422 before anything is written. Request body:
400 Bad Request: missing id:
(For disable, the message reads disable requires { id }.) 404 Not Found: no capability row with that id:
422 Unprocessable Entity: the capability cannot be modified (observe-only, or writable === false):
503 Service Unavailable: the tier allowed the write, but the owning source is OpenClaw and the Gateway connection is down:
200 OK: the toggle was applied; the updated record is returned (or null):

Action: approve

Answers a pending tool-call approval: the same tool_call_approvals rows the approval cards on the board and in chat answer. Answering a row someone already answered changes nothing and returns the row as it is. A tool row whose expiresAt has passed takes no answer: the response is 409 { "error": "approval expired", "approval": { ... } }, and a row still pending is marked expired. An allow_always on an approval tied to a connector grant also saves a standing rule that allows that tool, with any arguments, for 30 days, unless the prompt marked the call as one that cannot be remembered (neverRemember). A call to a destructive tool is always marked that way. An approval of kind: 'exec' (an OpenClaw shell command the Gateway is holding) is answered through the Gateway, exactly as POST /api/tools/approvals/:id/resolve does (see Tools and MCP): it answers 200 { ok: true, kind: 'exec', alreadyResolved }, or 502 { "error": "the Gateway did not accept that decision" } when the Gateway does not take the answer, and the command then stays held. Request body:
403 Forbidden: { "ok": false, "error": "person_only" }: the request did not pass the person check, as on POST /api/tools/approvals/:id/resolve. The approval is left as it was. An allow_always from one of the people an app that started Clawboo names gets 403 { "error": "allow_always_from_app" } here too. 400 Bad Request: missing id or a decision outside the allowed set:
404 Not Found: no approval row with that id:
200 OK (kind: 'tool'): the approval was resolved; the row is returned:

Catch-all

400 Bad Request: :action is not one of the four known actions:
404 Not Found: the write named an unknown source or a capability id that cannot be parsed:
422 Unprocessable Entity: the owning source does not take this write for its tier:
A blocked install is also a 422, with findings (see Action: install). 503 Service Unavailable: the write needed the OpenClaw Gateway and its connection is down:
500 Internal Server Error: any other failure (the message is redacted):

Examples


Error envelope

Most error bodies are { "error": "<message>" }. The two tier 422s add manageability, and the enable and disable check also adds writable, so a client can show the read-only state without a second lookup. A blocked install’s 422 carries ok: false and findings instead. A 503 means the tier allowed the write but the owning source could not reach its runtime: retry after the Gateway reconnects. A 500 message is redacted before it is sent.
Last modified on November 8, 2026