Search

Use these endpoints to find pages by keyword, meaning, frontmatter, or shape. Pick the one that fits the question:

Endpoint	Use it when
`GET /search`	You have keywords. BM25 over SQLite FTS5, with a soft trust boost. Add `mode=hybrid` to fuse in vector results.
`GET /search/verified`	You want verified and source-of-truth pages strongly preferred.
`GET /search/semantic`	You have a natural-language question and a vector index is configured.
`POST /brief`	You want a token-budgeted pack of the most relevant sections in one call.
`GET /meta`	You want to filter pages by frontmatter values.
`GET /similar`	You want pages whose frontmatter is structurally closest to a page or a vector.

All paths are relative to http://localhost:3333/api/kiwi. For DQL queries and the link graph, see Metadata and graph.

Full-text search

Run a BM25-ranked keyword search over page content. GET /api/kiwi/search

string

required

Search query. See query syntax.

integer

default:"50"

Maximum results to return. Capped at 200.

integer

default:"0"

Number of results to skip.

string

Restrict results to paths that start with this prefix, for example runbooks/. pathPrefix is accepted as an alias.

string

default:"fts"

fts for BM25 only, or hybrid to fuse BM25 with vector search. See hybrid search. Any other value returns 400.

string

Set to none or off to disable the default trust boost.

string

Keep only pages whose frontmatter scope equals this value.

boolean

default:"false"

Include pages with memory_status: superseded. They are excluded by default.

number

default:"0"

Blend recency into ranking, from 0.0 (relevance only) to 1.0 (recency only). Values outside that range return 400.

string

RFC 3339 timestamp. Keep only pages modified after it, for example 2026-09-01T00:00:00Z.

integer

default:"3"

Maximum edit distance for “did you mean” title suggestions when the first page of results is empty. Capped at 10.

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

string

The query as received.

integer

The effective limit after defaults and caps.

integer

The effective offset.

object[]

Ranked results.

Show result

string

Page path relative to the knowledge root.

object[]

Matching lines, each with line (1-based) and text.

number

Ranking score. Comparable only within one response.

string

Highlighted excerpt, when available.

string

Public URL of the page, when a public URL is configured.

object[]

Present only when the query returned nothing at offset=0. Each entry has query, path, title, and distance.

Response

{
  "query": "payment timeout",
  "limit": 10,
  "offset": 0,
  "results": [
    {
      "path": "concepts/payments.md",
      "matches": [{ "line": 12, "text": "Retries happen after a payment timeout of 30s." }],
      "score": 4.82,
      "snippet": "...retries after a <mark>payment</mark> <mark>timeout</mark>...",
      "permalink": "https://wiki.example.com/page/concepts/payments.md"
    }
  ]
}

Returns 400 when q is missing or a parameter is malformed. Returns 501 when scope is used on a non-SQLite search backend.

By default results get a soft trust boost: status: verified, source-of-truth: true, and a confidence between 0 and 1 nudge a page up, while status: deprecated or outdated nudge it down. Requests that set scope, include_superseded, or recency_weight skip the boost.

Query syntax

Plain words are matched as an implicit AND, and punctuation such as hyphens is handled for you. If the query contains FTS5 syntax (quotes, parentheses, *, ^, :, or uppercase AND/OR/NOT), KiwiFS passes it to FTS5 unchanged.

Syntax	Example	Behavior
Keywords	`payment timeout`	Pages containing both terms
AND	`payment AND timeout`	Same as space-separated
OR	`payment OR billing`	Pages containing either term
NOT	`payment NOT refund`	Excludes pages containing the second term
Phrase	`"payment timeout"`	The exact phrase
Prefix	`auth*`	Terms starting with `auth`

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'

Hybrid search

Fuse BM25 and vector rankings with Reciprocal Rank Fusion (RRF) on the same endpoint. GET /api/kiwi/search?mode=hybrid Hybrid mode accepts q, limit, offset, path_prefix, and boost from full-text search, plus:

number

default:"60"

RRF rank constant. Must be greater than 0. Smaller values let one engine’s top hit dominate; larger values flatten rank differences.

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

string

Always hybrid.

string[]

Engines that contributed: ["fts", "semantic"], or ["fts"] when no vector index is configured. The request still succeeds with 200 in that case.

number

The RRF constant used.

object[]

Each result has path, matches, score (the RRF score), snippet, permalink, fts_rank, and semantic_rank. A rank of 0 means that engine did not return the page.

Response

{
  "query": "payment timeout",
  "mode": "hybrid",
  "limit": 10,
  "offset": 0,
  "engines": ["fts", "semantic"],
  "rrf_k": 60,
  "results": [
    {
      "path": "concepts/payments.md",
      "score": 0.032,
      "snippet": "...retries after a payment timeout...",
      "fts_rank": 1,
      "semantic_rank": 3
    }
  ]
}

Trust-ranked search

Run the same BM25 search, then re-rank hard by trust signals in frontmatter. GET /api/kiwi/search/verified Compared with the default soft boost, status: verified pages get a 2x multiplier, source-of-truth: true pages 3x, status: outdated 0.3x, and status: deprecated 0.1x. Results are re-ranked, not filtered: every BM25 hit is still returned.

string

required

Search query, using the same syntax as full-text search.

integer

default:"50"

Maximum results. Capped at 200.

integer

default:"0"

Number of results to skip.

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

The response has the same shape as full-text search.

Response

{
  "query": "auth",
  "limit": 50,
  "offset": 0,
  "results": [
    {
      "path": "concepts/auth.md",
      "matches": [{ "line": 3, "text": "OAuth2 auth flow with refresh tokens." }],
      "score": 8.91,
      "snippet": "...OAuth2 <mark>auth</mark> flow..."
    }
  ]
}

Returns 501 when the search backend is not SQLite.

Add status: verified or source-of-truth: true to a page’s frontmatter to lift it in trust-ranked results.

Semantic search

Find pages by meaning using vector embeddings. GET /api/kiwi/search/semantic or POST /api/kiwi/search/semantic Send parameters as query parameters, or as a JSON body on POST. Body values win over query parameters.

string

required

Natural-language query. On GET, pass it as q.

integer

default:"10"

Maximum results to return.

integer

default:"0"

Number of results to skip.

string

Keep only pages whose frontmatter scope equals this value.

string

RFC 3339 timestamp. Keep only pages modified after it. Body only.

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

curl 'http://localhost:3333/api/kiwi/search/semantic?q=how+does+auth+work&topK=5'

string

The query as received.

integer

The effective result cap.

integer

The effective offset.

object[]

Ranked chunks.

Show result

string

Page path.

integer

Index of the matching chunk within the page.

number

Similarity score. Higher is closer.

string

Text of the matching chunk.

Response

{
  "query": "how does auth work?",
  "topK": 5,
  "offset": 0,
  "results": [
    {
      "path": "concepts/auth.md",
      "chunkIdx": 0,
      "score": 0.92,
      "snippet": "OAuth2 + JWT based authentication system..."
    }
  ]
}

Returns 400 when no query is given or modifiedAfter is not RFC 3339. Returns 503 when semantic search is not enabled.

Semantic search needs an embedder and vector store. Configure them under [search.vector] in .kiwi/config.toml. See Configuration.

Context pack

Retrieve the most relevant pages and pack them, whole or by section, into a token budget. POST /api/kiwi/brief The pack uses hybrid retrieval and counts real BPE tokens. Content is never summarized or rewritten. Anything that did not fit is listed in dropped with its token cost, so you can fetch it explicitly or raise the budget.

string

required

Retrieval query. You can also pass it as the q query parameter.

integer

default:"4000"

Hard token ceiling. A negative value returns an empty pack whose dropped list still names every candidate, which lets you ask what a query would cost.

integer

default:"20"

Maximum candidate pages considered before packing.

string

Restrict retrieval to paths under this prefix.

string

default:"cl100k_base"

BPE vocabulary used to count tokens.

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}'

string

The query as received.

integer

The effective budget.

integer

Tokens used by items.

string

Encoding used to count tokens.

integer

Pages retrieval offered before budgeting.

object[]

Packed content in relevance order.

Show item

string

Page path.

string

Page title, when known.

string

Section heading. Empty when the whole page is included.

string

Verbatim page or section text.

integer

Token count of content.

number

Retrieval score.

integer

Rank from full-text search, 0 if absent.

integer

Rank from semantic search, 0 if absent.

boolean

true when some of the page’s sections were left out.

object[]

Content that did not make it in. Each entry has path, optional heading, tokens, score, and reason: budget exhausted, page truncated to fit budget, page could not be read, or page has no content.

Response

{
  "query": "how does auth work?",
  "budget_tokens": 4000,
  "used_tokens": 3712,
  "tokenizer": "cl100k_base",
  "items": [
    {
      "path": "concepts/auth.md",
      "title": "Authentication",
      "content": "# Authentication\n\nOAuth2 + JWT based authentication system...",
      "tokens": 2140,
      "score": 0.033,
      "fts_rank": 1,
      "semantic_rank": 1
    }
  ],
  "dropped": [
    { "path": "runbooks/sso-outage.md", "reason": "budget exhausted", "tokens": 1880, "score": 0.016 }
  ],
  "candidates": 7
}

Frontmatter query

Filter pages by frontmatter values using JSON path expressions. GET /api/kiwi/meta Each filter is <field><op><value>, where field is a JSON path starting with $. (for example $.status or $.tags[*]). Operators are =, !=, <>, <, <=, >, >=, LIKE, and NOT LIKE.

string

AND filter. Repeat the parameter to combine several, for example where=$.status=draft&where=$.priority>2.

string

OR filter. Repeat for several alternatives.

string

Shorthand for where=$.scope=<value>.

string

JSON path to sort by, for example $.updated.

string

default:"asc"

asc or desc.

integer

default:"50"

Maximum results. Capped at 200.

integer

default:"0"

Number of results to skip.

curl -G 'http://localhost:3333/api/kiwi/meta' \
  --data-urlencode 'where=$.status=draft' \
  --data-urlencode 'sort=$.updated' \
  --data-urlencode 'order=desc'

integer

Number of results in this response.

integer

The effective limit.

integer

The effective offset.

object[]

Each result has path, frontmatter (the full frontmatter object), and permalink when a public URL is configured.

Response

{
  "count": 1,
  "limit": 50,
  "offset": 0,
  "results": [
    {
      "path": "concepts/billing.md",
      "frontmatter": { "title": "Billing", "status": "draft", "updated": "2026-09-20" }
    }
  ]
}

Returns 400 for a malformed filter or a field that does not start with $.. Returns 501 when the search backend is not SQLite.

For projections, grouping, and sorting across many fields, use DQL instead.

Rank pages by how close their frontmatter is to a given page or to an inline field vector. GET /api/kiwi/similar Similarity uses Gower distance over the numeric and categorical fields named in a [[similarity.profiles]] block in .kiwi/config.toml. Pass vector to ask about a case that is not in the knowledge base yet.

string

Page to find neighbors of. Required unless vector is set.

string

JSON object of field values, for example {"format":"csv","stats.rows":12000}. With path, these values override the page’s own.

string

Similarity profile name. Optional when exactly one profile is configured.

integer

default:"5"

Number of neighbors to return.

.kiwi/config.toml

[[similarity.profiles]]
name = "dataset"
match = { kind = "dataset" }
numeric = ["stats.rows", "stats.columns"]
categorical = ["format", "license"]
weights = { "format" = 2.0 }

curl 'http://localhost:3333/api/kiwi/similar?path=datasets/sales-2025.md&k=3'

string

Profile used.

string

The path you passed, if any.

object

The resolved field vector that was compared.

string[]

Fields in the profile.

integer

Pages compared.

boolean

true when the candidate set hit its cap, so ranking covers only part of the corpus.

object[]

Ranked neighbors.

Show neighbor

string

Page path.

number

1 - rank_distance. Higher is more similar; results are ordered by it.

number

Gower distance over the fields both sides have.

number

Distance that counts missing fields as maximally different.

number

Weighted share of fields that were comparable.

integer

Fields both sides had.

integer

Fields in the profile.

object[]

Per-field breakdown with field, kind, distance, weight, skipped, and the two values a and b.

Response

{
  "profile": "dataset",
  "query_path": "datasets/sales-2025.md",
  "query_vector": { "format": "csv", "license": "cc-by", "stats.rows": 12000, "stats.columns": 14 },
  "fields": ["stats.rows", "stats.columns", "format", "license"],
  "candidate_count": 42,
  "neighbors": [
    {
      "path": "datasets/sales-2024.md",
      "score": 0.94,
      "distance": 0.06,
      "rank_distance": 0.06,
      "coverage": 1,
      "comparable_fields": 4,
      "total_fields": 4,
      "contributions": [
        { "field": "format", "kind": "categorical", "distance": 0, "weight": 2, "skipped": false, "a": "csv", "b": "csv" }
      ]
    }
  ]
}

Returns 400 when neither path nor vector is given, the profile is unknown, k is not a positive integer, or vector is not a JSON object. Returns 503 when no similarity profiles are configured.

Search concepts

How the three search tiers fit together.

Metadata and graph

DQL queries, aggregations, backlinks, and the link graph.

Configuration

Search engine and vector settings.

Analytics

Search analytics and failed queries.

REST API

CLI

Full-text search

Query syntax

Hybrid search

Trust-ranked search

Semantic search

Context pack

Frontmatter query

Similar pages

Search concepts

Metadata and graph

Configuration

Analytics

​Full-text search

​Query syntax

​Hybrid search

​Trust-ranked search

​Semantic search

​Context pack

​Frontmatter query

​Similar pages

​Related

Search concepts

Metadata and graph

Configuration

Analytics

Full-text search

Query syntax

Hybrid search

Trust-ranked search

Semantic search

Context pack

Frontmatter query

Similar pages

Related