Search

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.

string

required

Search query. Supports boolean operators and phrase matching.

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

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'

Trust-ranked search

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

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.

string

required

Natural language query.

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.

string

required

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

string

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

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.

REST API

CLI

Full-text search

Query syntax

Trust-ranked search

Semantic search

Metadata query

​Full-text search

​Query syntax

​Trust-ranked search

​Semantic search

​Metadata query

Full-text search

Query syntax

Trust-ranked search

Semantic search

Metadata query