ROroma
Items

Filter, sort, count or sum the items of one list

Filter, sort, count or sum the items of ONE list by its properties — exact numbers instead of eyeballing a dump: "how many are unread", "expenses in March", "the wines rated 5". where clauses AND-combine on a property by id or name (on a list that keeps them, status and dueDate are properties too); a select value may be its label. mode 'list' (default) returns the matching items, paged with offset and limit; 'count' how many match; 'sum' the total of sumPropertyId across the matches. Archived items are left out unless includeArchived: true; each item reports its archivedAt.

post/api/v1/items/query

Request

  • Base URL
    https://api.roma.app
  • URL
    https://api.roma.app/api/v1/items/query
  • Auth
    HTTP bearer

Request body

listIdstring required

The list to query: a list id (from list_lists or get_context), or the word "tasks" (the Tasks list, the unsorted pool) or "notes" (the Notes list, made afresh when the user deleted theirs).

mode'list' | 'count' | 'sum' nullable

'list' (default) returns matching items; 'count' how many match; 'sum' totals sumPropertyId across matches.

sumPropertyIdstring nullable

For mode 'sum': the numeric property to total (its stable id or name).

createdAfterstring nullable

ISO 8601 instant — items added on/after this.

createdBeforestring nullable

ISO 8601 instant — items added before this (exclusive).

updatedAfterstring nullable

ISO 8601 instant — items last edited on/after this. A read that repeats on a schedule passes the instant of its previous read here, or uses list_items' changedSince, which also carries deletions.

updatedBeforestring nullable

ISO 8601 instant — items last edited before this (exclusive).

includeArchivedboolean nullable

true also includes archived items (hidden from every list by default), so one can be brought back with update_items.

limitinteger nullable

mode 'list': max items per page (default 50).

offsetinteger nullable

mode 'list': items to skip — page through a big list with offset + limit until hasMore is false.

includeImageUrlsboolean nullable

mode 'list': true additionally returns a short-lived signed url per attachment.

Response

The tool's result.

mode'list' | 'count' | 'sum' required
listIdstring required
listNamestring required
listIconstring nullable

The list's own icon, an emoji, when it has one.

countnumber required

How many items match.

sumnumber
sumPropertyIdstring
offsetnumber
hasMoreboolean

Changes

No recorded changes to this operation across all 1 revision of this API.