CLI & HTTP API Reference

The Knowledge Base is exposed through two flat contracts: the rantaiclaw kb CLI (agent-shellable, TOON by default) and the /api/v1/kb/* HTTP API (JSON). Both are backed by the same store and retrieval pipeline; the CLI lives in src/kb/axi/cli.rs and the HTTP surface in src/kb/axi/api.rs.

CLI: rantaiclaw kb

The CLI is an “axi-cli” surface: idempotent, never interactive, TOON output by default, --json toggles JSON. Each subcommand is gated by the kb feature (built into the default binary).

kb delete has no --json flag — it always prints a small TOON result block. kb intelligence, graph, re-embed, and drift cover the Document Intelligence and maintenance surfaces documented in Document Intelligence & GraphRAG and Searching & Retrieval.

Output: TOON by default, --json to switch

TOON (Token-Optimized Object Notation) is a compact tabular form that costs fewer tokens than JSON while staying machine-parsable (src/kb/axi/toon.rs). The header declares the row count and the projected columns; each row is indented two spaces:

chunks[5]{document,section,score,content_preview}:
  Insurance Policy,Coverage,0.91,The maximum coverage limit is…
  Insurance Policy,Coverage,0.84,Deductibles apply per claim…

Everything goes to stdout — operators grep one stream, agents parse one stream. Passing --json emits pretty-printed JSON instead, for scripted callers.

Exit-code contract

Every subcommand returns one of two exit codes (documented in src/kb/axi/cli.rs):

HTTP API: /api/v1/kb/*

When the gateway runs with the kb feature, the following routes are mounted (router() in src/kb/axi/api.rs). Bodies and responses are JSON.

Auth model

Authentication mirrors the rest of /api/v1/*: the pairing/bearer rules from the [gateway] config apply unchanged (check_auth in src/kb/axi/api.rs). When require_pairing = true, every route needs Authorization: Bearer <token> — pair via POST /pair first. When require_pairing = false (the local-dev default), requests pass through.

Upload cap

Ingest uploads are capped at 32 MiB per request (KB_UPLOAD_MAX_BYTES = 32 * 1024 * 1024). A larger upload is rejected by the body-limit layer before any handler runs. The KB subtree also carries a longer per-request timeout (600 s, vs. the gateway-wide 120 s) because ingest embeds every chunk through the possibly-remote embedding provider.

Lazy init & the 503 fail-fast

The heavy KB plumbing — config, sqlite-vec store, embedder, optional reranker — is built once per process and cached (KbContext, guarded by a tokio::sync::Mutex keyed on the resolved DB path). The first request to land triggers initialization; subsequent requests share the same handles.

Init failures cache as Err. A failed build (missing embedding key, unreachable DB) is cached and surfaces as 503 on every subsequent call until the gateway restarts — this is intentional fail-fast behavior, not a per-request retry. A missing key returns 503 kb_not_configured; other build failures return 503 kb_unavailable. Operators fix the env (or PUT /api/v1/config/knowledge, which flushes the cache) and the next request rebuilds. Per-request KB errors map by kind: NotFound → 404, Config / unsupported file type → 400, upstream embedding/chat failures → 502, anything else → 500.

The entire module is #[cfg(feature = "kb")] at the gateway-import level, so a non-KB build never mounts these routes or pays the compile cost.

See also

• Reference → CLI — every top-level rantaiclaw command.
• Knowledge Base — the subsystem overview and the three consumption surfaces.
• Configuration & Keys — the KB_* knobs behind these surfaces.