Velocity, graph, and similarity

These endpoints help you understand the shape of a knowledge base: which pages churn, which are central, how pages connect, which pages are related but not linked, and how well search finds the right page.

Endpoint	Needs
Velocity	Git versioning
Graph endpoints	The link index (on by default). `503` when unavailable.
Suggestions, embeddings	Vector search. `503` when it is off.
Similar	A `[[similarity.profiles]]` block in config. `503` without one.

Change velocity

Analyze git history for a period: which pages change most, which don’t change at all, which are suddenly busy, and which have a single author.

GET /api/kiwi/velocity

string

default:"30d"

Window as a number followed by d (days), w (weeks), or m (months, counted as 30 days).

integer

default:"20"

Maximum entries in hot_spots.

string

Only analyze pages under this prefix.

curl 'http://localhost:3333/api/kiwi/velocity?period=2w&limit=5'

Only markdown files are counted. Returns 500 if git log fails, for example when versioning is off.

string

Period used.

integer

File changes (one per commit per file) in the period.

object[]

Most changed pages, descending.

Show properties

string

Page path.

integer

Commits touching the page.

integer

Distinct commit authors.

integer

Lines added plus lines deleted.

object[]

Every page with no changes in the period, each with path and days_since_change.

object[]

Pages whose change rate over the last 7 days is more than three times their average for the period.

Show properties

string

Page path.

number

Changes per day over the last 7 days.

number

Changes per day over the whole period.

string[]

Pages changed in the period by only one author.

{
  "period": "2w",
  "total_changes": 87,
  "hot_spots": [
    { "path": "concepts/auth.md", "changes": 12, "authors": 3, "lines_changed": 240 }
  ],
  "cold_spots": [
    { "path": "concepts/legacy.md", "days_since_change": 120 }
  ],
  "bursts": [
    { "path": "runbooks/deploy.md", "recent_rate": 1.29, "avg_rate": 0.36 }
  ],
  "single_author_pages": ["runbooks/deploy.md"]
}

Graph analytics

Summarize the wiki link graph: size, connected components, orphans, and the highest PageRank pages.

GET /api/kiwi/graph/analytics

integer

default:"20"

Number of pages in top_pages.

curl 'http://localhost:3333/api/kiwi/graph/analytics?limit=10'

integer

Pages in the link graph.

integer

Wiki links.

integer

Disconnected subgraphs.

integer

Pages in the largest component.

string[]

Pages with no incoming links.

object[]

Highest PageRank pages, each with path, pagerank, in_degree, and out_degree.

{
  "total_nodes": 142,
  "total_edges": 387,
  "components": 3,
  "largest_component_size": 138,
  "orphans": ["concepts/legacy.md"],
  "top_pages": [
    { "path": "concepts/auth.md", "pagerank": 0.042, "in_degree": 18, "out_degree": 5 }
  ]
}

Centrality

Return PageRank, betweenness, and degree for every page, highest PageRank first.

GET /api/kiwi/graph/centrality

integer

Maximum pages. Omit to return all.

curl 'http://localhost:3333/api/kiwi/graph/centrality?limit=20'

object[]

Show properties

string

Page path.

number

PageRank score.

number

How often the page sits on shortest paths between other pages.

integer

Incoming links.

integer

Outgoing links.

{
  "pages": [
    { "path": "concepts/auth.md", "pagerank": 0.042, "betweenness": 0.18, "in_degree": 18, "out_degree": 5 }
  ]
}

Communities

Group pages into topic clusters with Louvain community detection. Links are treated as undirected.

GET /api/kiwi/graph/communities

curl 'http://localhost:3333/api/kiwi/graph/communities'

object[]

Clusters, each with a numeric id and its pages.

{
  "communities": [
    { "id": 0, "pages": ["concepts/auth.md", "concepts/sessions.md", "runbooks/login-flow.md"] },
    { "id": 1, "pages": ["concepts/billing.md", "concepts/invoices.md"] }
  ]
}

Shortest path

Return the shortest chain of wiki links from one page to another, following link direction.

GET /api/kiwi/graph/path

string

required

Start page.

string

required

End page.

curl 'http://localhost:3333/api/kiwi/graph/path?from=concepts/auth.md&to=concepts/billing.md'

Returns 400 if either parameter is missing, and 404 if a page isn’t in the graph or no path exists.

string[]

Pages from from to to, inclusive.

{ "path": ["concepts/auth.md", "concepts/users.md", "concepts/billing.md"] }

Graph walk

Return one page’s immediate neighborhood: outgoing links, backlinks, and pages in the same folder or with a shared tag.

GET /api/kiwi/graph/walk

string

required

Page path.

boolean

default:"true"

Set to false to skip folder and tag siblings, which requires scanning every page.

curl 'http://localhost:3333/api/kiwi/graph/walk?path=concepts/auth.md'

Returns 404 if the page does not exist.

string

Page path.

string[]

Wiki link targets in the page, as written.

string[]

Pages that link here.

object[]

Each with path, relation (sibling_dir or sibling_tag), and shared_tag for tag siblings.

number

Incoming links divided by pages in the graph.

integer

Length of links_in.

integer

Length of links_out.

{
  "path": "concepts/auth.md",
  "links_out": ["sessions", "api-keys"],
  "links_in": ["index.md", "runbooks/login-flow.md"],
  "siblings": [
    { "path": "concepts/sessions.md", "relation": "sibling_dir" },
    { "path": "runbooks/login-flow.md", "relation": "sibling_tag", "shared_tag": "security" }
  ],
  "hub_score": 0.014,
  "in_degree": 2,
  "out_degree": 2
}

Link suggestions

Find pages that are semantically close to a page but not yet linked to or from it. Use this to discover missing wiki links.

GET /api/kiwi/suggestions

string

required

Page path.

integer

default:"10"

Maximum suggestions.

curl 'http://localhost:3333/api/kiwi/suggestions?path=concepts/auth.md&limit=3'

Returns 400 if path is missing, 404 if the page does not exist, and 503 if vector search is off. suggestions is null when nothing qualifies.

object[]

Show properties

string

Suggested page.

number

Vector similarity score.

string

Matching text from the suggested page.

{
  "suggestions": [
    { "target": "concepts/api-keys.md", "similarity": 0.89, "snippet": "API key authentication..." }
  ]
}

{
  "profile": "dataset",
  "query_vector": { "format": "parquet", "stats.rows": 120000 },
  "fields": ["stats.rows", "stats.columns", "format", "license"],
  "candidate_count": 38,
  "neighbors": [
    {
      "path": "datasets/orders.md",
      "score": 0.81,
      "distance": 0.06,
      "rank_distance": 0.19,
      "coverage": 0.5,
      "comparable_fields": 2,
      "total_fields": 4,
      "contributions": [
        { "field": "format", "kind": "categorical", "distance": 0, "weight": 1, "skipped": false, "a": "parquet", "b": "parquet" }
      ]
    }
  ]
}

Embeddings

Return the stored text chunks and embedding vectors for a page.

GET /api/kiwi/embeddings

string

required

Page path.

curl 'http://localhost:3333/api/kiwi/embeddings?path=concepts/auth.md'

Returns 400 if path is missing, 404 if the page has no embeddings, and 503 if vector search is off.

string

Page path.

integer

Vector length.

object[]

Each with chunk_idx, text, and vector.

{
  "path": "concepts/auth.md",
  "dimensions": 768,
  "chunks": [
    { "chunk_idx": 0, "text": "# Authentication\n\nOAuth2...", "vector": [0.012, -0.034, 0.051] }
  ]
}

Search evaluation

Score full-text, semantic, and hybrid search against questions with known answers. Reports hit rate, MRR, precision, and nDCG at top_k. Same as kiwifs eval.

POST /api/kiwi/eval

string

Golden set name. Loads <set>.topics and <set>.qrels from .kiwi/eval/. Use either set or queries.

object[]

Inline questions.

Show properties

string

required

Search text.

string[]

Relevant pages, each graded 1.

object

Map from path to graded relevance (higher is more relevant). Only nDCG uses grades.

string | string[]

Path prefixes hidden from retrieval before ranking. Use this for leave-one-out evaluation.

integer

default:"5"

Cutoff for every metric.

curl -X POST 'http://localhost:3333/api/kiwi/eval' \
  -H "Content-Type: application/json" \
  -d '{"set": "leave-one-out", "exclude_prefix": "drafts/", "top_k": 10}'

curl -X POST 'http://localhost:3333/api/kiwi/eval' \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {"question": "how does authentication work", "expected_paths": ["concepts/auth.md"]},
      {"question": "deploy checklist", "expected_paths": ["runbooks/deploy.md"]}
    ]
  }'

Returns 400 when both or neither of set and queries are given or the set can’t be loaded, and 500 if every search failed.

integer

Cutoff used.

string[]

Prefixes excluded, if any.

object

Full-text search metrics. semantic and hybrid have the same shape; hybrid only has data when vector search is on.

Show properties

number

Share of questions with a relevant page in the top top_k.

number

Mean reciprocal rank of the first relevant page.

number

Mean precision in the top top_k.

number

deprecated

Same value as precision_at_k.

number

Mean nDCG at top_k.

integer

Questions scored.

object

Semantic search metrics.

object

Hybrid (reciprocal rank fusion) metrics.

object[]

Per question: question, relevant, and for each engine its rank (fts_rank, semantic_rank, hybrid_rank; 0 means not found), hits, and nDCG.

object[]

Questions that couldn’t be scored, each with question and reason.

integer

Failed searches.

{
  "top_k": 5,
  "fts": { "hit_rate": 1.0, "mrr": 0.75, "precision_at_k": 0.3, "precision_at_5": 0.3, "ndcg": 0.81, "queries": 2 },
  "semantic": { "hit_rate": 1.0, "mrr": 0.9, "precision_at_k": 0.4, "precision_at_5": 0.4, "ndcg": 0.88, "queries": 2 },
  "hybrid": { "hit_rate": 1.0, "mrr": 0.92, "precision_at_k": 0.4, "precision_at_5": 0.4, "ndcg": 0.9, "queries": 2 },
  "per_query": [
    {
      "question": "how does authentication work",
      "relevant": ["concepts/auth.md"],
      "fts_rank": 2, "semantic_rank": 1, "hybrid_rank": 1,
      "fts_hits": ["concepts/sessions.md", "concepts/auth.md"],
      "semantic_hits": ["concepts/auth.md"],
      "hybrid_hits": ["concepts/auth.md"],
      "fts_ndcg": 0.63, "semantic_ndcg": 1, "hybrid_ndcg": 1
    }
  ],
  "errors": 0
}

MCP equivalents

kiwi_velocity, kiwi_graph_analytics, kiwi_graph_centrality, kiwi_graph_communities, kiwi_graph_path, kiwi_graph_walk, kiwi_suggestions, kiwi_similar, kiwi_embeddings, and kiwi_eval. The kiwi_eligible task-ranking tool is MCP-only; there is no REST endpoint for it.

Analytics and health

Page views, failed searches, and health checks.

Search

Full-text, semantic, and hybrid search.

REST API

CLI

Change velocity

Graph analytics

Centrality

Communities

Shortest path

Graph walk

Link suggestions

Similar pages

Embeddings

Search evaluation

MCP equivalents

Analytics and health

Search

​Change velocity

​Graph analytics

​Centrality

​Communities

​Shortest path

​Graph walk

​Link suggestions

​Similar pages

​Embeddings

​Search evaluation

​MCP equivalents

​Related

Analytics and health

Search

Change velocity

Graph analytics

Centrality

Communities

Shortest path

Graph walk

Link suggestions

Similar pages

Embeddings

Search evaluation

MCP equivalents

Related