Metadata and graph

DQL queries, frontmatter aggregations, computed view refresh, backlinks, and the wiki link graph.

Query frontmatter as structured data with DQL, aggregate it by field, and walk the wiki link graph. All paths are relative to http://localhost:3333/api/kiwi.

DQL, aggregations, and view refresh need the SQLite search backend (the default). With another backend they return 501.

DQL query

Run a Dataview Query Language (DQL) query over the frontmatter index.

GET /api/kiwi/query

q · string · required

DQL query. See query types and the DQL reference.

limit · integer · default: "50"

Overrides the query’s own LIMIT. Capped at 200.

offset · integer · default: "0"

Overrides the query’s own OFFSET.

format · string · default: "json"

json returns the structure below. table, list, count, or distinct return the result rendered as plain text (markdown) instead.

curl -G 'http://localhost:3333/api/kiwi/query' \
  --data-urlencode 'q=TABLE title, status FROM "concepts" WHERE status = "draft" SORT title ASC'

columns · string[]

Column names. Includes _path first unless the query uses WITHOUT ID.

rows · object[]

One object per row, keyed by column name (or alias). Page rows also carry path.

total · integer

Rows in this response, or -1 when has_more is true. It is not a count of all matches; use a COUNT query for that.

has_more · boolean

true when more rows exist past this page.

groups · object[]

Present for GROUP BY queries. Each group has key, count, and rows.

Response

{
  "columns": ["_path", "title", "status"],
  "rows": [
    { "_path": "concepts/billing.md", "path": "concepts/billing.md", "title": "Billing", "status": "draft" },
    { "_path": "concepts/users.md", "path": "concepts/users.md", "title": "Users", "status": "draft" }
  ],
  "total": 2,
  "has_more": false
}

Returns 400 when q is missing or the query does not parse.

Query types

Type	Returns	Example
TABLE	Selected fields per page. Supports AS aliases and WITHOUT ID.	TABLE title, status FROM "concepts"
LIST	Matching pages, optionally with one or more fields.	LIST FROM #runbook WHERE status = "verified"
COUNT	A single count column.	COUNT FROM "concepts" WHERE status = "draft"
DISTINCT	Unique values of one field.	DISTINCT status FROM "concepts"
CALENDAR	Pages placed by a date field.	CALENDAR due FROM "tasks"
TASK	Markdown checklist items with text, completed, line, tags, and due.	TASK FROM "projects"
JSON	Selected fields as JSON values.	JSON title, tags FROM "concepts"

After the type, add any of these clauses: FROM "folder/" or FROM #tag (also FROM RECORDS "<kind>" and FROM CLAIMS), WHERE <expression> (repeatable, AND-joined), SORT field ASC|DESC (repeatable), GROUP BY field, FLATTEN field, LIMIT n, and OFFSET n.

Count

curl -G 'http://localhost:3333/api/kiwi/query' \
  --data-urlencode 'q=COUNT FROM "concepts" WHERE status = "draft"'

Aggregate frontmatter

Group pages by a frontmatter field and compute counts, sums, averages, minimums, and maximums.

GET /api/kiwi/query/aggregate

group_by · string · required

Frontmatter field to group by, for example status.

calc · string · default: "count"

Comma-separated calculations. Use count, or func:field where func is avg, sum, min, or max, for example count,avg:priority.

path_prefix · string

Only include pages whose path starts with this prefix.

curl 'http://localhost:3333/api/kiwi/query/aggregate?group_by=status&calc=count,avg:priority'

groups · object

Map from group value to an object of results keyed by calculation label (count, avg:priority, and so on). Pages without the field are grouped under (none).

Response

{
  "groups": {
    "draft": { "count": 12, "avg:priority": 2.3 },
    "verified": { "count": 45, "avg:priority": 1.8 },
    "(none)": { "count": 3, "avg:priority": null }
  }
}

Returns 400 when group_by is missing or a field name or calculation is invalid.

Refresh a computed view

Re-run the query in a computed view page and rewrite its generated section if the result changed.

POST /api/kiwi/view/refresh

A computed view is a markdown page with kiwi-view: true and a kiwi-query DQL string in its frontmatter. An optional kiwi-format (default table) picks how the result is rendered. Generated output sits after the <!-- kiwi:auto --> marker.

path · string · required

Path of the view page. You can also pass it as the path query parameter.

curl -X POST 'http://localhost:3333/api/kiwi/view/refresh' \
  -H "Content-Type: application/json" \
  -d '{"path": "dashboards/open-incidents.md"}'

path · string

The view page path.

status · string

regenerated when the file was rewritten, unchanged otherwise.

Response

{ "path": "dashboards/open-incidents.md", "status": "regenerated" }

Returns 400 when path is missing, the page is not a computed view, or its query fails.

Views are marked stale when pages change and regenerate the next time you read them through GET /file. Call this endpoint to regenerate one immediately, for example after edits made outside KiwiFS. For saved DQL views stored in .kiwi/views/, see Views.

Backlinks

List pages that link to a given page.

GET /api/kiwi/backlinks

path · string · required

Target page path.

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

path · string

The target page.

backlinks · object[]

Linking pages. Each has path, count (number of links from that page), and relation for links that come from frontmatter fields such as supersedes or contradicts.

Response

{
  "path": "concepts/auth.md",
  "backlinks": [
    { "path": "concepts/users.md", "count": 2 },
    { "path": "decisions/auth-v2.md", "count": 1, "relation": "supersedes" }
  ]
}

Returns 400 when path is missing. With the grep search backend, which keeps no link index, backlinks is always empty.

Link graph

Return every page and every wiki link as a node and edge list. This powers the graph view in the web UI.

GET /api/kiwi/graph

This endpoint takes no parameters. The result is cached and rebuilt after writes.

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

nodes · object[]

One per file. Each has path and, when the page has tags (or labels) in frontmatter, tags.

edges · object[]

One per link. Each has source (page path), target (the raw text inside the wiki link, not resolved to a path), and relation when typed.

Response

{
  "nodes": [
    { "path": "concepts/auth.md", "tags": ["security"] },
    { "path": "concepts/billing.md" },
    { "path": "concepts/users.md" }
  ],
  "edges": [
    { "source": "concepts/users.md", "target": "auth" },
    { "source": "concepts/billing.md", "target": "users" }
  ]
}

Edge targets are unresolved, so match them to node paths by exact path, file stem, or prefix. For ready-made analysis, use graph centrality, communities, path, and walk or graph analytics.

Related

DQL

Full query language reference.

Views

Saved DQL views and their execution.

Search

Full-text, semantic, and frontmatter search.

Wiki links

How links are parsed and resolved.