OpenWebUI Tool Server

Wikantik ships an OpenAPI 3.1 tool server under /tools/ that exposes hybrid search and page retrieval as LLM-callable tools. It is designed for OpenWebUI and any other OpenAPI tool runtime; the OpenAPI document at /tools/openapi.json advertises two operations:

Operation	Method + path	Purpose
`search_wiki`	`POST /tools/search_wiki`	BM25 + hybrid search across the wiki corpus
`get_page`	`GET /tools/page/{name}`	Fetch a single page's Markdown body with truncation

Configuration

Tool-server access has two layers:

DB-backed API keys (recommended) — generated via the admin UI at /admin/apikeys, bound to a Wikantik principal, and stored SHA-256 hashed. The principal is recorded for attribution and the audit trail only: every call reads the wiki as an anonymous visitor would, so page ACLs are evaluated against a signed-out reader and the tools return only pages that reader may view.
Transport-layer guards — CIDR allowlist, rate limits, and the "no config = fail closed" safety net live in wikantik-tools.properties. Defaults ship inside the module JAR; overrides go in tomcat/lib/wikantik-tools.properties.

Property	Purpose	Default
`tools.access.allowedCidrs`	Comma-separated CIDR allowlist (e.g. `10.0.0.0/8`)	(none)
`tools.access.allowUnrestricted`	Explicit opt-in to run with no auth and no CIDR	`false`
`tools.ratelimit.global`	Global requests per second (0 disables)	`100`
`tools.ratelimit.perClient`	Per-client requests per second (0 disables)	`10`
`wikantik.public.baseURL`	Public base URL used for citation links + OpenAPI `servers` entry	(request host)

Generating a key

Navigate to Administration → API Keys and click Generate Key. Pick:

Principal — the login the key is attributed to in the audit trail. It does not change what the key can read: page ACLs are evaluated as for an anonymous visitor.
Label — freeform note (e.g. OpenWebUI production) to identify the key later.
Scope — tools (OpenAPI only), mcp_read or mcp_admin (MCP servers only), or all (both).

The plaintext token (wkk_…) is shown once at creation time and only the SHA-256 hash is persisted. Revoking a key is a single click; any client using the revoked token starts receiving HTTP 403 immediately.

Fail-closed semantics

When neither a DB-backed key, nor tools.access.allowedCidrs, nor tools.access.allowUnrestricted=true is configured, the server refuses every request with 503 Service Unavailable and logs a CRITICAL line at startup. With at least one DB-backed key generated via the admin UI, the server accepts Bearer tokens from that table — no configuration reload required.

Calling the tools

`search_wiki`

curl -X POST http://localhost:8080/tools/search_wiki \
    -H "Authorization: Bearer $TOOLS_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "hybrid retrieval", "maxResults": 5}'

Response:

{
  "query": "hybrid retrieval",
  "results": [
    {
      "name": "HybridRetrieval",
      "url": "https://wiki.example.com/wiki/HybridRetrieval",
      "score": 18,
      "summary": "Fusion of BM25 and dense vector ranking",
      "tags": ["search", "design"],
      "snippet": "…fused ranking …",
      "lastModified": "2026-04-12T18:22:11Z"
    }
  ],
  "total": 1
}

maxResults defaults to 10 when omitted or not positive, and is capped at 25.

`get_page`

curl -H "Authorization: Bearer $TOOLS_KEY" \
    "http://localhost:8080/tools/page/HybridRetrieval?maxChars=4000"

The response strips YAML frontmatter from text, includes summary/tags from frontmatter as top-level fields, and reports truncation via truncated/totalChars/ truncatedAt when the body exceeds the limit (default 6000 chars, hard cap 20000; a missing or non-positive maxChars uses the default). A page that does not exist returns 404, and a page a signed-out reader may not view returns 403 before any body is loaded.

Observability

The tool server publishes to the process-wide Micrometer registry, scraped at /metrics (Prometheus text format; InternalNetworkFilter limits it to loopback and RFC 1918 clients). Prometheus renders the dots as underscores. All meters are prefixed wikantik.tools:

Meter	Type	Notes
`wikantik.tools.requests{endpoint,status}`	counter	endpoint ∈ {search_wiki, get_page, openapi}; status ∈ {success, error, not_found, forbidden} (`not_found` and `forbidden` occur only for get_page)
`wikantik.tools.search.results_returned`	counter	total result rows emitted
`wikantik.tools.get_page.truncated`	counter	get_page responses that hit the truncation cap

OpenWebUI wiring

In OpenWebUI:

Workspace → Tools → Add Tool → OpenAPI URL.
Paste https://wiki.example.com/tools/openapi.json and your Bearer token.
OpenWebUI reads the two operations verbatim; the per-operation description fields double as the LLM's tool prompts, so no extra authoring is required.

Security notes

DB-backed keys are bound to a Wikantik principal for attribution and auditing only; each call reads the wiki as an anonymous visitor, so page ACLs hide every page a signed-out reader cannot view, whichever principal the key is bound to. The principal does not widen or narrow what the tools return.
The legacy tools.access.keys / mcp.access.keys config-file token lists were removed in 2.0.21 (June 2026) and are no longer read by anything. Setting either is a silent no-op; database-backed keys minted at /admin/apikeys are the only token mechanism.
Rate limits are sliding-window, 1-second buckets; the Retry-After: 1 header is returned with every 429.

Cluster Hub: Generative AI Hub: Foundation Models, RAG Architecture, and Agent Workflows (generative-ai)