Skip to main content

​
Change velocity

Analyze the rate and distribution of changes across your knowledge base over a time period. 
GET /api/kiwi/velocity
​
period
string
default:"30d"
Time window. Supports Nd (days), Nw (weeks), Nm (months).
​
limit
integer
default:"20"
Max number of items in hot/cold spot lists.
​
path_prefix
string
Limit analysis to a subdirectory.
curl 'http://localhost:3333/api/kiwi/velocity?period=14d&limit=5'

{
  "period": "14d",
  "total_changes": 87,
  "hot_spots": [
    {"path": "concepts/auth.md", "changes": 12},
    {"path": "runbooks/deploy.md", "changes": 9}
  ],
  "cold_spots": [
    {"path": "concepts/legacy.md", "changes": 0, "days_since_update": 120}
  ],
  "bursts": [
    {"date": "2026-04-28", "changes": 23, "actor": "agent:importer"}
  ],
  "single_author_pages": 14
}
​
total_changes
integer
Total commits in the period.
​
hot_spots
array
Most frequently changed pages.
​
cold_spots
array
Least recently changed pages.
​
bursts
array
Days with unusually high change counts.
​
single_author_pages
integer
Pages with only one contributor.
Use velocity data to identify knowledge that’s churning (hot spots may need stabilization) and knowledge that’s stale (cold spots may need review).

​
Graph analytics

Structural analysis of the wiki-link graph using PageRank and connectivity metrics. 
GET /api/kiwi/graph/analytics
​
limit
integer
default:"20"
Number of top pages to return.
curl 'http://localhost:3333/api/kiwi/graph/analytics?limit=10'

{
  "total_nodes": 142,
  "total_edges": 387,
  "components": 3,
  "largest_component_size": 138,
  "orphans": ["concepts/legacy.md", "scratch/notes.md"],
  "top_pages": [
    {"path": "concepts/auth.md", "pagerank": 0.042, "in_degree": 18, "out_degree": 5},
    {"path": "concepts/users.md", "pagerank": 0.038, "in_degree": 15, "out_degree": 8}
  ]
}
​
total_nodes
integer
Total pages in the graph.
​
total_edges
integer
Total wiki-link connections.
​
components
integer
Number of disconnected subgraphs.
​
largest_component_size
integer
Pages in the largest connected component.
​
orphans
array
Pages with no incoming or outgoing links.
​
top_pages
array
Highest PageRank pages with degree counts.
Returns 503 if the link indexer is not available.

​
Centrality, communities, path, and walk

Additional graph helpers live alongside /graph/analytics:
EndpointPurpose
GET /graph/centrality?limit=50PageRank and betweenness-style rankings per page.
GET /graph/communitiesLouvain community detection over wiki-link edges.
GET /graph/path?from=a.md&to=b.mdShortest path between two pages.
GET /graph/walk?path=a.mdOne-hop neighbors, backlinks, and optional same-directory siblings.
See Utilities for response notes and error codes.

​
Suggestions

Get semantically similar pages for a given page, useful for “related pages” features and discovering missing links. 
GET /api/kiwi/suggestions
​
path
string
required
File path to find suggestions for.
​
limit
integer
default:"5"
Max suggestions to return.
curl 'http://localhost:3333/api/kiwi/suggestions?path=concepts/auth.md&limit=3'

{
  "suggestions": [
    {"target": "concepts/api-keys.md", "similarity": 0.89, "snippet": "API key authentication..."},
    {"target": "concepts/sessions.md", "similarity": 0.84, "snippet": "Session management..."}
  ]
}
Already-linked pages are filtered out. Requires vector search to be enabled.

​
Embeddings

Retrieve the raw embedding vectors for a page’s chunks. 
GET /api/kiwi/embeddings
​
path
string
required
File path to retrieve embeddings for.
curl 'http://localhost:3333/api/kiwi/embeddings?path=concepts/auth.md'

{
  "path": "concepts/auth.md",
  "dimensions": 768,
  "chunks": [
    {"chunk_idx": 0, "text": "# Authentication\n\nOAuth2...", "vector": [0.012, -0.034, ...]},
    {"chunk_idx": 1, "text": "## Refresh tokens\n\n...", "vector": [0.008, 0.021, ...]}
  ]
}
Returns 503 if vector search is not enabled.

​
Eligible tasks

Retrieve ranked actionable tasks inferred from frontmatter metadata — pages with status fields indicating they are available for work. 
GET /api/kiwi/eligible

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

{
  "tasks": [
    {"path": "tasks/t-42.md", "title": "Fix auth timeout", "status": "open", "priority": "high"},
    {"path": "tasks/t-15.md", "title": "Update onboarding", "status": "open", "priority": "medium"}
  ]
}
Useful for agents that need to pick up the next available task. MCP: kiwi_eligible.

​
Search evaluation

Benchmark your search quality against expected results. 
POST /api/kiwi/eval

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

{
  "fts": {"hit_rate": 1.0, "mrr": 0.75, "precision_at_5": 0.6},
  "semantic": {"hit_rate": 1.0, "mrr": 0.9, "precision_at_5": 0.8},
  "per_query": [
    {"question": "how does authentication work", "fts_rank": 2, "semantic_rank": 1}
  ]
}
​
hit_rate
number
Fraction of queries where the expected page appeared in top-5.
​
mrr
number
Mean Reciprocal Rank across all queries.
​
precision_at_5
number
Average precision in the top-5 results.
Last modified on May 31, 2026