Find widget — Docsbook

GET/api/v1/find_widget

Features

Search the Docsbook widget catalog for an interactive UI widget matching the user's request. Returns matching widget ids and summaries. 'dark mode toggle', 'analytics chart', 'search bar'). After finding a widget, use the returned resourceUri to read its HTML bundle via the ui:// resource.

Price — free, never metered.

Also reachable without a token on this workspace's public MCP endpoint.

Also reachable by name at POST /api/v1/tools/find_widget.

Input2

Authorizationheaderrequired

Your API key, sent as Authorization: Bearer dbk_YOUR_API_KEY.Sent from your browser straight to the API — never to Docsbook, never stored.

querystring · queryrequired

Free-text description of what the user wants, e.g. 'dark mode toggle' or 'analytics dashboard'.

modestring · query

Restrict matches to widgets available in this mode (admin or user).

Output3

okboolean

Whether the tool itself succeeded. A tool that ran and refused — an exhausted balance, a plan restriction, a bad argument — answers 200 with ok: false: the call was made and billed, and that refusal is its answer.

resultobject

The tool's own JSON answer, already parsed — not a string to parse a second time.

Show child attributes3

matchesobject[]

{ id, name, summary, resourceUri, requiresPlan, modes }.

index_versionstring

index_fetched_atstring

duration_msinteger

Server-side wall time for the call.

Use cases

Use this to discover available widgets (e.g.

Responses

200The tool ran. Read ok to see whether it succeeded.

401Missing or invalid API key.

Example input

curl 'https://docsbook.io/api/v1/find_widget?query=<query>' \
  -H 'Authorization: Bearer dbk_YOUR_API_KEY'

Example output

{
  "ok": true,
  "result": {
    "matches": [],
    "index_version": "<index_version>",
    "index_fetched_at": "<index_fetched_at>"
  },
  "duration_ms": 0
}

Updated Sep 24, 2026