Lists with your own columns, items, ticking, due days and resets.
Base URL https://app.heybmo.comFor agents: llms.txt · OpenAPI
Operations
WritePOST /api/ops/lists.create
Create a list
Create a list (a checklist or to-do list) with its own columns. Every item has a text, a tick and an optional due day; columns can be text, number, date, checkbox, choice, multi-choice, link or rating. copyOf makes a new list with the columns of another one, and its items unticked when withItems is true. Add items with lists.addItems.
Read a list’s details: its columns (names, types and choices), default view and how many items are still to do. Read this before adding or changing items, to use the right column names. The items themselves come from lists.items.
MCP tool lists_getCLI heybmo lists getLimit readSafe to retryInput
listIdrequiredidThe list id (from lists.list, lists.search or lists.create).
List your lists, pinned first, then most recently changed, with how many items each still has to do. Archived lists are not shown unless archived is true. unfinished keeps only lists with items still to tick. query keeps the lists whose name contains it, in any case and with or without accents (lists.search also forgives typos). Pass nextCursor back as cursor for the next page.
MCP tool lists_listCLI heybmo lists listLimit readSafe to retryInput
archivedtrue or falsetrue lists the archive instead. Default false.
querytextOnly lists named like this. Up to 100 characters.
unfinishedtrue or falsetrue: only lists with items still to tick. Default false.
limitnumberDefault 100.
cursortextnextCursor from the previous page, for the page after it. Up to 300 characters.
Change a list’s name, description, pinned or archived state, or its default view (sort and grouping, e.g. group by an aisle column to show sections). Columns change with lists.addField, lists.updateField and lists.removeField.
listIdrequiredidThe list id (from lists.list, lists.search or lists.create).
revisionnumberThe revision you last read. If it changed since, the change is refused so nothing is overwritten.
nametextUp to 100 characters.
descriptiontextUp to 1000 characters.
pinnedtrue or false
archivedtrue or falseArchived lists leave the normal overview.
viewobjectHow the list shows by default. sort.by: position (your order), text, ticked, due, created or a column; group: ticked, due, or a choice, checkbox, rating or date column (null stops grouping).
Add a column to a list (up to 30). Types: text, number, date, checkbox, choice and multi-choice (with options), link, rating (1 to 5). It is empty on existing items.
Change a column: rename it (items keep their values), replace its options, move it before another column, or change its type when no value is lost (e.g. number to text, choice to multi-choice, multi-choice to choice when no item has more than one picked, text to choice, which turns its values into options). Removing an option that items use is refused.
Remove a column from a list and delete its values from every item, for good (it cannot be undone). Ask the person first.
Deletes for good. The first call changes nothing and answers CONFIRMATION_REQUIRED with what would be deleted; call again with confirm: true once the person agrees.
MCP tool lists_removeFieldCLI heybmo lists removeFieldLimit deleteSafe to retryInput
listIdrequiredidThe list id (from lists.list, lists.search or lists.create).
revisionnumberThe revision you last read. If it changed since, the change is refused so nothing is overwritten.
columnrequiredtextThe column’s current name. Up to 50 characters.
confirmtrue or falseSet to true once the person agreed. Without it nothing is deleted and you get a description of what would be.
Read a list’s items with their values by column name. By default in the list’s own order (or its saved view), ticked items last. Filter by the tick, by text, due day or any column (tests: is, isNot, contains, lessThan, atMost, greaterThan, atLeast, isEmpty, isNotEmpty); sort and group by a column. query finds items by words in their text or any text or link column (any case, with or without accents; every word must appear). For a long list, filter or search rather than reading every page.
MCP tool lists_itemsCLI heybmo lists itemsLimit readSafe to retryInput
listIdrequiredidThe list id (from lists.list, lists.search or lists.create).
tickedtrue or falseOnly ticked (true) or only unticked (false) items.
filterslist of objectDefault []. Up to 10 items.Each item:
columnrequiredtextA column name, or text or due. Up to 50 characters.
Add one or more items (up to 100) to a list in one call, at the end or before another item. Each item has a text, an optional due day and values for the list’s columns by name (read the columns with lists.get first). Add several at once rather than one call each.
Change up to 100 items of one list: text, due day (null removes it) and column values by name (only the values given change; null clears one). To tick items use lists.tick; to move them, lists.moveItems.
Tick items as done (or untick them with ticked: false), up to 100 of one list at a time. The answer says how many are still to do and whether the list is now complete. To untick a whole list for reuse, lists.reset is simpler.
MCP tool lists_tickCLI heybmo lists tickLimit writeSafe to retryInput
Tick (or untick, with to: unticked) every item of a list that matches the filters and query, however many: e.g. every item in the Dairy aisle. For a few known items, lists.tick is simpler.
MCP tool lists_tickMatchingCLI heybmo lists tickMatchingLimit writeSafe to retryInput
listIdrequiredidThe list id (from lists.list, lists.search or lists.create).
tickedtrue or falseOnly ticked (true) or only unticked (false) items.
filterslist of objectThe same filters as lists.items; none: every item. Default []. Up to 10 items.Each item:
columnrequiredtextA column name, or text or due. Up to 50 characters.
Move items within their list (before another item, or to the end) or to another list. Moving to another list keeps the values of columns it has with the same name and type; others are dropped, and the answer says which.
Move every item of a list that matches the filters and query to the end of another list, however many. Values of columns the other list has with the same name and type are kept; others are dropped, and the answer says which. For a few known items, lists.moveItems is simpler.
Unticked items with a due day, across every list, soonest first: e.g. what is due this week (until the last day) or overdue (until yesterday). Archived lists are included.
MCP tool lists_dueCLI heybmo lists dueLimit readSafe to retryInput
untilrequireddateThe last day to include, YYYY-MM-DD.
fromdateThe first day (default: no limit, so overdue items too).
Find items by their text and text values across every list (or one), and lists by name, best matches first. Typos are forgiven. Use it to find an item or a list the person names without knowing ids.
MCP tool lists_searchCLI heybmo lists searchLimit readSafe to retryInput
What is in the trash and until when it can be restored: deleted lists, or the deleted items of one list when listId is given (most recent first). Pass nextCursor back as cursor for the next page.
MCP tool lists_trashCLI heybmo lists trashLimit readSafe to retryInput
listIdidShow this list’s deleted items instead.
limitnumberDefault 50.
cursortextnextCursor from the previous page, for the page after it. Up to 300 characters.
Move items of one list to the trash (up to 100). They can be restored with lists.restoreItems for 30 days. To remove every ticked item, lists.clearTicked is simpler.
Goes to the trash: it can be restored for 30 days.
MCP tool lists_deleteItemsCLI heybmo lists deleteItemsLimit deleteSafe to retryInput
Move every item of a list that matches the filters and query to the trash, however many (restorable for 30 days with lists.restoreItems). For a few known items, lists.deleteItems is simpler; for the ticked ones, lists.clearTicked.
Goes to the trash: it can be restored for 30 days.
MCP tool lists_deleteMatchingCLI heybmo lists deleteMatchingLimit deleteSafe to retryInput
listIdrequiredidThe list id (from lists.list, lists.search or lists.create).
tickedtrue or falseOnly ticked (true) or only unticked (false) items.
filterslist of objectThe same filters as lists.items; none: every item. Default []. Up to 10 items.Each item:
columnrequiredtextA column name, or text or due. Up to 50 characters.
Bring items back from the trash, at the end of their list. Name them (itemIds, found with lists.trash and a listId), or give the listId and deletedAt of a lists.deleteItems or lists.deleteMatching answer to bring back all it moved.
Move every ticked item of a list to the trash (restorable for 30 days with lists.restoreItems). To keep the items and only untick them, use lists.reset.
Goes to the trash: it can be restored for 30 days.
MCP tool lists_clearTickedCLI heybmo lists clearTickedLimit deleteSafe to retryInput
listIdrequiredidThe list id (from lists.list, lists.search or lists.create).
Delete lists that are in the trash for good, with their items: the ones named (listIds), or the whole trash (all: true). It cannot be undone, so ask the person first. Lists not in the trash are refused: lists.delete moves a list there.
Deletes for good. The first call changes nothing and answers CONFIRMATION_REQUIRED with what would be deleted; call again with confirm: true once the person agrees.
MCP tool lists_deleteForeverCLI heybmo lists deleteForeverLimit deleteSafe to retryInput
listIdslist of idLists in the trash to delete for good (from lists.trash). Up to 100 items.
alltrue or falsetrue: empty the whole trash instead.
confirmtrue or falseSet to true once the person agreed. Without it nothing is deleted and you get a description of what would be.