Search

Full-text, trust-ranked, vector, and metadata search endpoints.

KiwiFS provides multiple search strategies. You can use full-text search for keyword matching, vector search for semantic similarity, or metadata queries for structured filtering.

Full-text search

BM25-ranked full-text search powered by SQLite FTS5.

q · string · required

Search query. Supports boolean operators and phrase matching.

suggest_threshold · number

Similarity threshold (0–1) for “did you mean?” suggestions when the query yields few results.

curl 'http://localhost:3333/api/kiwi/search?q=payment+timeout'

[
  {
    "path": "concepts/payments.md",
    "title": "Payments",
    "snippet": "...handles <mark>payment</mark> retries after a <mark>timeout</mark>...",
    "score": 4.82
  }
]

Query syntax

Syntax	Example	Behavior
Keywords	payment timeout	Match pages containing both terms
Boolean AND	payment AND timeout	Explicit AND (same as space-separated)
Boolean OR	payment OR billing	Match pages containing either term
Boolean NOT	payment NOT refund	Exclude pages containing a term
Phrase	"payment timeout"	Match the exact phrase

Boolean search

curl 'http://localhost:3333/api/kiwi/search?q=payment+AND+timeout'

Trust-ranked search

Search results weighted by trust signals in frontmatter. Pages marked as verified or source-of-truth rank higher.

q · string · required

Search query (same syntax as full-text search).

curl 'http://localhost:3333/api/kiwi/search/verified?q=auth'

[
  {
    "path": "concepts/auth.md",
    "title": "Authentication",
    "snippet": "...OAuth2 <mark>auth</mark> flow...",
    "score": 8.91,
    "trust": {"status": "verified", "source-of-truth": true}
  }
]

Add status: verified or source-of-truth: true to your page frontmatter to boost that page in trust-ranked results.

Semantic search

Vector similarity search using embeddings. Requires a vector search provider configured in .kiwi/config.toml.

query · string · required

Natural language query.

limit · integer · default: "10"

Maximum number of results to return.

POST

curl -X POST 'http://localhost:3333/api/kiwi/search/semantic' \
  -H "Content-Type: application/json" \
  -d '{"query": "how does auth work?", "limit": 10}'

[
  {
    "path": "concepts/auth.md",
    "title": "Authentication",
    "snippet": "OAuth2 + JWT based authentication system...",
    "similarity": 0.92
  }
]

Semantic search requires vector embeddings. Configure an embedder provider (OpenAI, Ollama, Cohere, etc.) in your .kiwi/config.toml under [search.vector].

Hybrid search

Fuse FTS and semantic ranks with Reciprocal Rank Fusion. Degrades to lexical-only when no vector index exists.

mode · string

Set to hybrid to enable RRF fusion.

q · string · required

Search query.

limit · integer · default: "10"

Maximum number of results.

rrf_k · integer · default: "60"

RRF constant. Higher values flatten rank differences.

curl 'http://localhost:3333/api/kiwi/search?mode=hybrid&q=payment+timeout&limit=10'

{
  "query": "payment timeout",
  "engines": ["fts", "semantic"],
  "results": [
    {
      "path": "concepts/payments.md",
      "title": "Payments",
      "score": 0.032,
      "fts_rank": 1,
      "semantic_rank": 3
    }
  ]
}

Context pack

Retrieve pages and pack extracted sections into a token budget. The pack never summarizes. Overflow is listed so you can see what was dropped.

curl -X POST 'http://localhost:3333/api/kiwi/brief' \
  -H "Content-Type: application/json" \
  -d '{"query": "how does auth work?", "budget_tokens": 4000, "max_pages": 20}'

query · string · required

Retrieval query.

budget_tokens · integer

Maximum tokens in the packed context.

max_pages · integer

Cap on candidate pages before packing.

path_prefix · string

Restrict retrieval to a directory.

Metadata query

Query pages by their frontmatter fields using JSON path syntax.

where · string · required

JSON path filter expression (e.g. $.status=draft).

sort · string

JSON path to the field to sort by (e.g. $.updated).

order · string · default: "asc"

Sort order: asc or desc.

curl 'http://localhost:3333/api/kiwi/meta?where=$.status=draft&sort=$.updated&order=desc'

[
  {
    "path": "concepts/billing.md",
    "title": "Billing",
    "metadata": {"status": "draft", "updated": "2026-04-20", "author": "agent:writer"}
  }
]

Combine metadata queries with the DQL endpoint for more complex structured queries across your knowledge base.