Views (Bases)

List, save, delete, and run saved DQL views stored in .kiwi/views.

A view (shown as a Base in the web UI) is a saved DQL query plus display settings: layout, columns, filters, sort, and grouping. Each view is a JSON file at .kiwi/views/{name}.json, so you can edit it on disk or through these endpoints.

All paths are relative to http://localhost:3333/api/kiwi. See Bases and views for how the web UI renders them and DQL for query syntax.

View names must start with a letter or digit and contain only letters, digits, spaces, hyphens, and underscores.

The view object

name · string

View name. Always matches the file name and URL.

query · string

DQL query, for example TABLE status, owner FROM "tasks" WHERE status != "done".

layout · string

table, list, calendar, or kanban.

columns · object[]

Optional column settings.

Show column

property · string

Field shown in this column.

label · string

Header text.

formula · string

Computed value, using + - * /, length(), round(), and if() over row fields. The result is written into property.

summary · string

Footer aggregate: sum, avg, count, min, or max.

filters · object[]

Optional UI filters, each with field, operator (=, !=, >, <, contains, in), and value.

sort · object[]

Optional sort keys, each with field and order (asc or desc).

group_by · string

Optional field to group rows by.

List views

Returns every view in .kiwi/views/.

GET /views

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

Response

{
  "views": [
    {
      "name": "open-tasks",
      "query": "TABLE status, owner, due FROM \"tasks\" WHERE status != \"done\"",
      "layout": "table",
      "sort": [{"field": "due", "order": "asc"}]
    }
  ]
}

Get a view

Returns one view object.

GET /views/:name

name · string · required

View name.

curl 'http://localhost:3333/api/kiwi/views/open-tasks'

Returns 404 if the view does not exist or the name is invalid.

Save a view

Creates or replaces a view. The body is a view object; name is taken from the URL.

PUT /views/:name

name · string · required

View name.

query · string · required

DQL query.

layout · string

table, list, calendar, or kanban.

columns · object[]

Column settings. See the view object.

filters · object[]

UI filters.

sort · object[]

Sort keys.

group_by · string

Grouping field.

curl -X PUT 'http://localhost:3333/api/kiwi/views/open-tasks' \
  -H "Content-Type: application/json" \
  -d '{
    "query": "TABLE status, owner, estimate, spent FROM \"tasks\" WHERE status != \"done\"",
    "layout": "table",
    "columns": [
      {"property": "remaining", "label": "Remaining", "formula": "estimate - spent"}
    ],
    "sort": [{"field": "status", "order": "asc"}]
  }'

Response

{
  "status": "saved",
  "view": {
    "name": "open-tasks",
    "query": "TABLE status, owner, estimate, spent FROM \"tasks\" WHERE status != \"done\"",
    "layout": "table",
    "columns": [{"property": "remaining", "label": "Remaining", "formula": "estimate - spent"}],
    "sort": [{"field": "status", "order": "asc"}]
  }
}

Views are config, not pages. Saving or deleting a view writes .kiwi/views/ directly and does not create a git commit.

Delete a view

Removes a view. Deleting a view that does not exist still succeeds.

DELETE /views/:name

name · string · required

View name.

curl -X DELETE 'http://localhost:3333/api/kiwi/views/open-tasks'

Response

{"status": "deleted"}

Execute a view

Runs the view’s DQL query, fills in formula columns, and returns the rows.

GET /views/:name/execute

name · string · required

View name.

limit · integer · default: "50"

Maximum rows.

offset · integer · default: "0"

Rows to skip.

curl 'http://localhost:3333/api/kiwi/views/open-tasks/execute?limit=50&offset=0'

columns · string[]

_path followed by the queried fields (no _path with WITHOUT ID).

rows · object[]

One object per page, keyed by column. Includes _path, path, and any formula columns.

total · integer

Rows in this response, or -1 when has_more is true.

has_more · boolean

Whether more rows exist past this page.

groups · object[]

Present for GROUP BY queries: key, count, and rows per group.

Response

{
  "columns": ["_path", "status", "owner", "estimate", "spent"],
  "rows": [
    {"_path": "tasks/login-bug.md", "path": "tasks/login-bug.md", "status": "in-progress", "owner": "alice", "estimate": 5, "spent": 3, "remaining": 2}
  ],
  "total": 1,
  "has_more": false
}

Returns 404 if the view does not exist, 400 if its query fails to parse or run, and 503 when the Dataview executor is unavailable (search engines other than SQLite).

The UI filters, sort, and group settings are not applied by this endpoint; put them in the DQL query if you need them server-side.

Related

Bases and views

How views render in the web UI.

DQL

Query syntax for the query field.

Metadata and graph

Run ad-hoc DQL with GET /query.

MCP tools

kiwi_views_list, kiwi_views_get, kiwi_views_save, kiwi_views_delete, kiwi_views_execute.