Skip to content

Views ​

A view is a saved list of work items: a filter and a way to show what it finds. Views belong to the whole team and work across projects; the project is a filter like any other. Everybody sees in a view only the items of projects they may see, so the same view can show Mara more items than Ida.

Every item list in werkbuch works the same way, saved or not: My items, the list of a project and every view have the filter bar, the Display menu and the four layouts. Filtering, sorting, grouping and paging happen on the server; the browser only shows what comes back.

Views and built-in lists ​

Four lists are built in and cannot be deleted:

ListAddressHoldsStarts with
My items: Assigned/my-itemsOpen items assigned to youGrouped by category, sorted by priority
My items: Created/createdItems you createdGrouped by category, newest first
My items: Watching/subscribedItems you watchGrouped by category, last changed first
Project/projects/WEBThe items of the projectGrouped by status, manual order

A built-in list is a view that is never saved. You can filter and change its display; only a different filter counts as an unsaved change. Save as new view … (in the bar of unsaved changes, or at the end of Display) turns what you see into a view, and keeps what the list stands for as a condition: "Project is Website", "Assignee is me", "Creator is me" or "Watched is yes".

Saved views live under Views (/views) and at /views/<id>. A star puts a view into the sidebar, in your own order; deleting a view takes it out of everybody's sidebar.

The overview of the views of the team, with layout and creator of each

Permissions ​

ActionWho
Read a viewEvery active account
Create a view, save as new view, duplicateOrg admins and org members
Change or delete a viewThe person who created it, and org admins

A view has a name (up to 60 characters), an icon (one of the list in the dialog, or exactly one emoji), a filter and a display. Save replaces the whole view; when two people save the same view at the same time, the second one wins as a whole. Whoever may not change a view can still save a copy with Save as new view … or Duplicate.

A filter may name a project, person or item the reader does not see. werkbuch keeps the condition as it is and shows it as "Hidden project", "Unknown person" and so on; it matches only what the reader sees.

Layouts ​

1 to 4 switch between the layouts; the switch is also in the header of every list. The layout is part of the display and of a saved view.

List ​

Items in groups that fold, the fields of the display as chips behind the title, child items indented below their epic. Each group shows the number of its items from the server and loads its items page by page while you scroll; groups that are folded or far away load nothing.

My items as a list, grouped by category because the items lie in two workflows

Board ​

Every group is a column, empty ones included. Dragging a card, or shift+left and shift+right, changes the grouped field:

  • Status: only along the transitions of the workflow. A move the workflow does not allow stays in its column and a toast says why; into a closed state, werkbuch asks for the resolution.
  • Category: the item takes the first state of that category in its own workflow that it may move to; if there is none, the toast says so.
  • Priority and assignee: the new value; a person who is not a member of the project cannot take the item.
  • Type, project, parent item: cards stay in their column. Label: a board grouped by label cannot be dragged, because an item stands in the column of each of its labels.

The order within a column follows the sort of the display. With the sort Manual, alt+up and alt+down or dragging within the column move a card between its neighbours; with any other sort, werkbuch says that the order follows the sort. When there is no room left between two neighbours, werkbuch first redistributes the order of the card's project (the order stays, the ranks get short again, see Order items by hand) and then moves the card; moves of other cards of the project wait for it. The card stays where it was, and a toast says why: there is no room left when the two neighbours belong to another project; the order has changed when other cards now stand between the two neighbours (in a list of several projects after the redistribution, or after another change of the column), so move the card again from the new order; and the new order has not loaded when it takes longer than five seconds. A move the server refuses puts the card back, and the numbers of the columns are right again. + in the head of a column creates an item that fits the column.

The board of a project, its work items in one column per status

Table ​

One row per item, one column per field of the display, properties included. The head and the first column (key and title) stay in place while you scroll. Cells can be changed in place: enter opens the editor of a cell, escape closes it. Cells of properties the type of the item does not have show "—". Project, created and changed cannot be changed here.

A view as a table, with the properties client and effort as columns

Timeline ​

The timeline shows the epics of the list (items of a type marked "Epic"), grouped by project and ordered by start date, whatever the grouping and the sort of the display say. A bar runs from the start date to the due date and is filled by the share of closed child items. Drag a bar to move it and its ends to change one date. Epics without dates stand in the side list No dates; drag them onto the axis, or use Plan from today (two weeks from today). The zoom (week, month, quarter) stays in the address as ?zoom=week or ?zoom=quarter; Today scrolls to today.

The roadmap as a timeline: three epics with their progress, and the marker for today

Grouping ​

GroupingGroups, in this orderEmpty groups
StatusThe order of the workflowAll states of the workflow
CategoryBacklog, Unstarted, Started, Completed, CanceledAll five
AssigneePeople before bots, by name; "Unassigned" last"Unassigned" always
PriorityUrgent, High, Medium, Low, NoneAll five
TypeThe order of the catalogThe enabled types of the one project the filter names, else none
LabelBy name; "No label" last"No label" always
ProjectBy nameThe one project the filter names
Parent itemBy key; "No parent item" last"No parent item" always
NoneOne group—

Grouping by status works only while all items found share one workflow; otherwise werkbuch groups by category and says so above the list. An item with two labels stands in both label groups, and counts once in the total.

Sorting ​

SortOver the API (sort.field)Order (ascending)
ManualrankThe order you give items by dragging (rank)
PrioritypriorityUrgent first
Due date, start datedue_date, start_dateEarliest first
Created, changedcreated_at, updated_atOldest first
KeykeyIdentifier of the project, then the number (A2-1 before A10-1, WEB-9 before WEB-10)
Categorystate_categoryBacklog first
A property (number, date, text or address)property:<key>Smallest, earliest or alphabetical first (Item 9 before Item 10)

Items without a value come last in both directions; equal values keep the manual order. Texts and identifiers are compared without regard to case and accents, and numbers in them as numbers: Item 9 comes before Item 10, Version 1.2 before Version 1.10. Leading zeros do not count (Item 007 and Item 7 are equal), and only the digits 0 to 9 are numbers.

Filters ​

A filter is a list of conditions that all must hold. Each condition has a field, an operator and, for most operators, a value. In the interface, f or Filter adds a condition and / searches in the title; over the API, a filter is JSON in the same form everywhere:

json
{
  "version": 1,
  "conditions": [
    { "field": "assignee", "op": "is", "value": "me" },
    { "field": "state_category", "op": "in", "value": ["unstarted", "started"] },
    { "field": "due_date", "op": "before", "value": { "relative": "+7d" } },
    { "field": "property:customer", "op": "is", "value": "01m6dd2rc7syc8r8s7q2my2j51" }
  ]
}

A filter holds up to 50 conditions, a list up to 100 values, a text up to 255 characters. An unknown field, an operator the field does not offer or a value of the wrong form is refused (422 at filter.conditions.<n>.field, .op or .value), never silently ignored.

Fields ​

FieldKindNotes
project, type, state, created_byIDULID; created_by also me
assignee, parentID, may be emptyULID; assignee also me
state_categoryChoicebacklog, unstarted, started, completed, canceled
priorityChoiceurgent, high, medium, low, none
labelListULIDs of labels
start_date, due_dateDaydue_date also overdue
created_at, updated_at, closed_atTimeCompared by day; closed_at may be empty
has_children, blocked, blocking, archived, epic, subscribedYes/noepic: a type marked "Epic"; subscribed: you watch the item
titleTextOnly contains
property:<key>By field typeSee below

Operators ​

KindOperators
IDis, is_not, in, not_in; is_empty, is_not_empty where the field may be empty
Choiceis, is_not, in, not_in
Listis, is_not, in, not_in, contains, is_empty, is_not_empty
Dayis, before, after, between, is_empty, is_not_empty; overdue only for due_date
Timeis, before, after, between; is_empty, is_not_empty only for closed_at
Yes/nois
Textcontains; text and address properties also is, is_empty, is_not_empty
Numberis, gt, lt, between, is_empty, is_not_empty
Rich textcontains, is_empty, is_not_empty

is and is_not take one value or a list, in and not_in a list. On a list field such as labels, is, in and contains mean "has one of them", is_not and not_in "has none of them". A missing value is never equal to anything, so is_not and not_in also match items without a value. before and after exclude the day itself, between takes two values and includes both. overdue takes no value: the due date is before today and the item is not in a Completed or Canceled state.

Values ​

ValueMeaning
"me"The person reading the list. Only for assignee, created_by and person properties.
"2026-11-02"A day.
"today", "this_week", "this_month"Today, the current week, the current month.
{ "relative": "+7d" }Days or weeks from today: -3d, +2w, up to five digits.
true, falseFor yes/no fields.
A numberFor number properties, below 10²⁰ in amount.
A textFor contains and is on texts, 1 to 255 characters.

The dynamic values work only where the field takes them: "today" in a title search is the word "today". On a range such as this_week, is means "within it", before "before its first day" and after "after its last day".

Dates and time zone ​

"Today", weeks and months count in the time zone of the organization, and weeks start on the weekday it sets. For created, changed and closed, werkbuch compares the day the moment falls on in that time zone: an item created at 00:30 in Berlin counts as created that day, also in the summer and winter time change.

Properties ​

The operators of a property follow its field type:

Field typeKindOperators
Dropdown, person (one value)IDis, is_not, in, not_in, is_empty, is_not_empty
Dropdown, person (several values)Listis, is_not, in, not_in, contains, is_empty, is_not_empty
DateDayis, before, after, between, is_empty, is_not_empty
Yes/noYes/nois
NumberNumberis, gt, lt, between, is_empty, is_not_empty
Text, addressTextcontains, is, is_empty, is_not_empty
Rich textRich textcontains, is_empty, is_not_empty

A condition on a property (property:<key>) only ever matches items whose type has the property, also with is_empty, is_not, not_in and is false. A yes/no property that was never set reads as "no". Texts are compared without regard to case and accents ("uber" finds "Über"); rich text is searched in its plain text. When a property is deleted, a saved view keeps its condition, which then matches nothing and shows as "Unknown field" until you remove it.

Archived items ​

Archived items stay out of every list, unless a condition on archived asks for them or the request sets include_archived. Items of an archived project show up only where a project condition with is or in names the project: the list of an archived project shows its open items, read-only.

State in the address ​

Everything you change in a list stands in its address, as far as it differs from the saved view or the built-in list: filter (the conditions as JSON), layout, group, sort (due_date:desc), fields (comma-separated), sub (0 hides child items) and, in the timeline, zoom. A link shows the same list to someone else, and reloading the page keeps it. Discard goes back to the saved state.

Keyboard ​

? lists every shortcut that applies at the moment.

Lists ​

KeysAction
j, k or down, upNext or previous item
shift+j, shift+k or shift+down, shift+upExtend the selection
xSelect the item
shift+xSelect the range up to the item
mod+aSelect all (loads every page first)
escapeClear the selection
enterOpen the item
spaceShow or close the preview
fAdd a condition
/Filter by title
1, 2, 3, 4List, board, table, timeline

The item shortcuts (s status, a assign, i assign to me, p priority, l labels, t type, d due date, shift+d start date, shift+p parent, mod+backspace archive or delete) act on the selection, or else on the item under the cursor. With several items selected, a bar above the list changes status, assignee, priority and labels of all of them at once, and archives them when all are closed. An action applies to a selection only when it is allowed for every selected item: when some of them are archived or belong to a project you only read (or, for archiving, some are still open), the bar leaves the action out, so does the palette, and its shortcut says why without changing anything. mod+backspace archives a selection only when all its items are closed and deletes it only when none is closed (open and archived items alike); when it would archive some and delete others, it does nothing and says why. What the server still refuses for one item, such as a transition its workflow forbids, is named in a single toast. e edits the title only in the preview and on the item page.

Group headings are not tab stops: left on an item goes to the heading of its group; on a heading, left folds, right unfolds or goes to the first item, down and up go to the next or previous heading.

Board ​

KeysAction
left, rightColumn to the left or right
j, k or down, upNext or previous card in the column
shift+left, shift+rightMove the card to the nearest column it may go to
alt+up, alt+downMove the card up or down (sort "Manual" only)
escape while draggingCancel the drag

The command palette (mod+k) offers the same moves, as long as they are possible.

Table ​

The table is a grid with one tab stop:

KeysAction
left, rightPrevious or next column
up, downPrevious or next row; with shift they extend the selection
home, endFirst or last column; with mod the first or last row
enterOpen the editor of the cell (on the first column: the item)
escapeClose the editor

j, k, x and space work as in the list, and so do the keys of the group headings.

Timeline ​

KeysAction
shift+left, shift+rightMove the epic one unit of the zoom (day, week, month) earlier or later; shift+right plans an epic without dates from today
alt+left, alt+rightMake the epic shorter or longer (its due date)

Moves are saved after a short pause; escape while dragging puts the bar back. The command palette (mod+k) offers the same moves, as long as they are possible.

REST ​

Reading needs a token with read. The three requests below that read with POST (query, groups, counts) are reads too: a token with only read may send them. Creating, changing and deleting views needs write. Messages come in the language of the account. Tokens, errors, pages and limits are explained on the page REST API; the list of views takes filter[created_by], filter[name] and sort like every list there.

RequestAnswer
GET /api/v1/work-itemsA page of items: view, filter[…] (short form), sort, show_sub_items (1 or 0, by default as the view says, otherwise 1), include_archived, lean, cursor, per_page
POST /api/v1/work-items/queryA page of items for a filter in the body
POST /api/v1/work-items/groupsThe groups of a grouping with their numbers
POST /api/v1/work-items/countsNumbers for up to 50 named filters
GET, POST /api/v1/viewsThe views, by name; 201 with a new one
GET, PUT, DELETE /api/v1/views/{id}One view; PUT replaces it as a whole; 204
POST /api/v1/favorites/toggle{"kind": "view", "id": "…"} stars a view or takes the star away

Read a view ​

?view=<id> returns the items of a view: its filter, its sort and whether it shows child items. filter[…] narrows it further (all conditions hold), sort replaces its sort: the API name from Sorting, with - in front for descending (sort=-due_date).

bash
curl -g -H "Authorization: Bearer <Token>" \
  "https://werkbuch.example.com/api/v1/work-items?view=01m6dd2re3zvh9g281chdw9hmv&filter[state_category]=unstarted,started&sort=-due_date&lean=1"

The short form takes these keys; several values are separated by commas and mean "one of them":

KeyValue
projectIdentifier, former identifier or ULID; unknown or hidden is a 404
parentKey or ULID of an item; unknown or hidden is a 404
qA key (WEB-47) finds this item, any other text searches the title
assignee, created_byULIDs or me; none alone for "nobody"
type, state, labelULIDs
state_categorybacklog, unstarted, started, completed, canceled
priorityurgent, high, medium, low, none
archivedtrue or false

sort takes a field (due_date), a field with - for descending (-due_date) or a property (property:effort). lean=1 leaves out description, description_json and values_markdown, which makes long lists much smaller. Any other key of filter[…] is a 422.

Query with a filter ​

POST /api/v1/work-items/query takes a filter in the body. Besides filter it takes view_id, shorthand (the short form as an object), q, sort ({"field", "direction"}), show_sub_items, group_by and group (one group of a grouping, for example one column of a board), include_archived, lean, cursor and per_page. Any other key is a 422.

bash
curl -X POST https://werkbuch.example.com/api/v1/work-items/query \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "version": 1, "conditions": [
      { "field": "assignee", "op": "is", "value": "me" },
      { "field": "due_date", "op": "before", "value": { "relative": "+7d" } },
      { "field": "state_category", "op": "in", "value": ["unstarted", "started"] }
    ] },
    "sort": { "field": "due_date", "direction": "asc" },
    "lean": true,
    "per_page": 50
  }'

The answer is a page as in every list, with the items in data. A filter that does not fit is refused with every problem at once:

json
{
  "type": "urn:werkbuch:problem:validation_failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "The input is not valid.",
  "reason": "validation_failed",
  "errors": {
    "filter.conditions.0.field": ["This field does not exist."],
    "filter.conditions.1.op": ["This field does not offer this operator."]
  }
}

Groups ​

POST /api/v1/work-items/groups takes view_id, filter, q, sort, show_sub_items, include_archived and group_by (required), and answers with the grouping that applies, the number of all items and the groups in their order:

bash
curl -X POST https://werkbuch.example.com/api/v1/work-items/groups \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{"view_id": "01m6dd2re4m3z0aez8e2qzc19p", "group_by": "state"}'
json
{
  "data": {
    "group_by": "category",
    "total": 3,
    "groups": [
      { "key": "backlog", "count": 1 },
      { "key": "unstarted", "count": 0 },
      { "key": "started", "count": 2 },
      { "key": "completed", "count": 0 },
      { "key": "canceled", "count": 0 }
    ]
  }
}

Here the items span several workflows, so the server groups by category. Read the items of one group with query, the same group_by as in the answer and "group": "<key>". Groups of a parent item carry the item (id, key, title, type_id).

Counts ​

POST /api/v1/work-items/counts counts up to 50 named filters at once. Names are 1 to 64 letters, digits, _, ., : or -; include_archived applies to all.

bash
curl -X POST https://werkbuch.example.com/api/v1/work-items/counts \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "overdue": { "version": 1, "conditions": [{ "field": "due_date", "op": "overdue" }] },
      "mine": { "version": 1, "conditions": [{ "field": "assignee", "op": "is", "value": "me" }] }
    }
  }'
json
{ "data": { "overdue": 10, "mine": 8 } }

Groups and counts only count what the account of the token sees. A filter on a project it does not see counts 0, as if the project did not exist.

Pages and cursors ​

A page holds up to 100 items (per_page, 100 by default); meta.total counts all of them, meta.next_cursor leads on. With GET, follow links.next: it keeps the query (view, filter, sort, per_page). With POST, links.next is null: send the same request again with cursor set to meta.next_cursor; the sort decides the order, ties are broken by the manual order and the ULID, so every item comes exactly once. A cursor belongs to its sort and group: one from another list is a 422 at cursor, and an empty cursor starts at the first page.

Manage views ​

bash
curl -X POST https://werkbuch.example.com/api/v1/views \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Overdue at Nordlicht",
    "icon": "timer",
    "filter": { "version": 1, "conditions": [
      { "field": "property:customer", "op": "is", "value": "01m6dd2rc7syc8r8s7q2my2j51" },
      { "field": "due_date", "op": "overdue" }
    ] },
    "display": {
      "layout": "table",
      "group_by": "assignee",
      "sort": { "field": "due_date", "direction": "asc" },
      "fields": ["key", "title", "state", "assignee", "due_date", "property:customer"],
      "show_sub_items": true
    }
  }'

All four parts are required, also for PUT, which replaces the view as a whole; sending back an answer unchanged changes nothing. display takes layout (list, board, table, timeline), group_by (state, category, assignee, priority, type, label, project, parent, none), sort, fields (up to 30: key, title, state, assignee, priority, labels, start_date, due_date, project, created_at, updated_at and property:<key>) and show_sub_items.