Skip to main content
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

SyntaxExampleBehavior
Keywordspayment timeoutMatch pages containing both terms
Boolean ANDpayment AND timeoutExplicit AND (same as space-separated)
Boolean ORpayment OR billingMatch pages containing either term
Boolean NOTpayment NOT refundExclude pages containing a term
Phrase"payment timeout"Match the exact phrase
curl 'http://localhost:3333/api/kiwi/search?q=payment+AND+timeout'

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

curl 'http://localhost:3333/api/kiwi/search?q=payment+NOT+refund'
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.
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.
curl -X POST 'http://localhost:3333/api/kiwi/search/semantic' \
  -H "Content-Type: application/json" \
  -d '{"query": "how does auth work?", "limit": 10}'

curl 'http://localhost:3333/api/kiwi/search/semantic?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].

​
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.
Last modified on May 31, 2026