---
title: "List and filter items"
method: GET
path: "/api/v1/items"
tags: ["Items"]
---

# List and filter items

`GET /api/v1/items`

## Request

- Base URL: `https://api.roma.app`
- URL: `https://api.roma.app/api/v1/items`
- Auth: HTTP bearer

List, filter and search items. Omit listId for the Tasks set — every item on a list that keeps a status and a due date (the Tasks list and every list made for tasks), ordered by due date then creation, completed tasks left out by default. Pass listId for one list's items, whatever its shape: a notes list's prose, a reading list's rows. Each row carries the item's title, body as Markdown, status and due date where its list keeps them, values keyed by property id, and its list. get_item reads one item in full with handles for editing, and is the call when the person asks to see, open or show one item; query_items filters, counts and sums by property. A read that repeats on a schedule passes `changedSince`, the `nextChangedSince` of its previous read: only what moved since comes back on the person's own lists, deletions included, one call per cycle instead of the whole list.

## Query parameters

- `listId` string: One list's items: 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). Omit for the Tasks set.
- `changedSince` string: An ISO 8601 instant (exclusive), or the `nextChangedSince` of the previous read verbatim. The changes feed for a worker that polls: every item of the list (or of the person's own lists that keep the task columns, trashed and archived ones included) whose record moved after it — edits, completions, archives, restores, deletions — oldest change first, the deleted ones as `deleted` tombstones, then `hasMore` and `nextChangedSince` to pass next time. Items shared with the person are not in the feed (list_items without changedSince reads them). `query` is refused beside it; the other filters and `sort` do not apply.
- `ids` string[]: Specific item ids to fetch (the other filters still apply).
- `assignedTo` string: Only the items assigned to one of the person's agents: "me" for the agent this call is made under (register_agent), else the agent's name or id. The work handed to an agent, for one that reads on its own schedule.
- `query` string: Free-text search across title and body.
- `taskStatus` string[]: Filter to these statuses, on lists that keep one — each a status id of the list's Status property (todo, inProgress, completed on every list that keeps one; backlog, inReview, canceled and the list's own ids where list_lists shows them). A done-stage status completes the item. A stage word (open, active, done) stands for every status of that stage on every list. Omit for the default: every status that is not done.
- `dueAfter` string: ISO 8601 instant — only items due on/after this (inclusive).
- `dueBefore` string: ISO 8601 instant — only items due before this (exclusive). Today = dueAfter today 00:00 local, dueBefore tomorrow 00:00 local; overdue = dueBefore today 00:00 alone.
- `createdAfter` string: ISO 8601 instant — only items created on/after this.
- `createdBefore` string: ISO 8601 instant — only items created before this (exclusive).
- `updatedAfter` string: ISO 8601 instant — only items last edited on/after this. A poll that wants deletions too uses `changedSince` instead.
- `updatedBefore` string: ISO 8601 instant — only items last edited before this (exclusive).
- `completedAfter` string: ISO 8601 instant — only items completed on/after this. Implies completed items unless taskStatus says otherwise.
- `completedBefore` string: ISO 8601 instant — only items completed before this (exclusive).
- `sort` 'due' | 'created' | 'updated' | 'completed': Row order. Default 'due' (due date, then creation); a timestamp sort returns newest first.
- `limit` integer: Max results (default 50).
- `includeImageUrls` boolean: true additionally returns a short-lived signed `url` per attachment so the images can be viewed. Off by default.

## Response `200`

The tool's result.

- object
  - `count` number, required
  - `listId` string, nullable, required
  - `listName` string, nullable, required
  - `listIcon` string, nullable, required: The list's own icon, an emoji, when it has one; null for the Tasks set.
  - `properties` object[]: The list's own properties, on a read of one list that has some.
    - `id` string, required
    - `name` string, required
    - `type` string, required
    - `kind` string: What the property IS: "status" / "dueDate" for the reserved pair a list binds to the task columns, else its type. A select named Status on any other list is a plain select.
    - `options` object[]
      - `id` string, required
      - `label` string, required
    - `optionCount` number
  - `items` object[], required
    - `id` string, required
    - `identifier` string, nullable: The item's fixed ID — its list's prefix and a number, TASK-1601 — which every item tool takes as its id too.
    - `title` string, nullable
    - `body` string, nullable: The body as Markdown; with a short handle in front of every block on a read made for editing.
    - `bodyVersion` string: A fingerprint of the body as read; a whole-body `rewrite` names it as `baseVersion`.
    - `taskStatus` string, nullable: On a list that keeps a status.
    - `dueAt` string, nullable: On a list that keeps a due date: the instant stored; a day when hasDueTime is false.
    - `hasDueTime` boolean, nullable: Whether dueAt's time of day is meant; false for a day.
    - `reminderAt` string, nullable: When the reminder rings, as an instant; null for none.
    - `completedAt` string, nullable
    - `values` object: The item's values keyed by property id; a select value is an option id.
    - `cells` object: The item's values by property NAME, as text, where its list has properties of its own.
    - `isSharedWithMe` boolean: Shared with the person by its owner; `editable` says what update_items admits on it.
    - `editable` 'all' | 'titleAndBody': On a row shared with the person: `titleAndBody` for an item shared with them one by one (its status, due date, values and images are its owner's; update_items refuses them by name), `all` for an item on a list shared with them (every field but the owner's favorite).
    - `listId` string, nullable
    - `listName` string, nullable
    - `listIcon` string, nullable: The list's own icon, an emoji, when it has one.
    - `expertId` string, nullable: The id of the item's standing expert (one of the user's experts, list_experts), when the user's own item carries one: that expert answers by default in the item's chat in Roma. Absent on a row shared with the user.
    - `createdAt` string, nullable
    - `updatedAt` string, nullable
    - `editedAt` string, nullable
    - `archivedAt` string, nullable
    - `recordingStatus` string
    - `attachments` object[]
      - `bucketPath` string, required
      - `mimeType` string, required
      - `sizeBytes` number, required
      - `url` string
    - `bodyImages` object[]: The pictures the body shows (`![…](roma://attachment/<bucketPath>)`), whether or not they are attachments, with the size each was stored at (null when unknown) and its alt text; with includeImageUrls, a short-lived signed url on each; with includeImages on get_item, the pictures themselves as image content blocks.
      - `bucketPath` string, required
      - `width` number, nullable, required
      - `height` number, nullable, required
      - `alt` string, required
      - `url` string
  - `deleted` object[]: With changedSince: the items deleted since, as tombstones.
    - `id` string, required
    - `title` string, required
    - `deletedAt` string, required
    - `updatedAt` string, required
  - `serverTime` string: With changedSince: the server's clock when this read began.
  - `hasMore` boolean: With changedSince: more changed than `limit`; continue with `nextChangedSince`.
  - `nextChangedSince` string: With changedSince: what to pass as the next call's changedSince, verbatim (an instant, or the last row's stamp and id while more is pending).
  - `links` object, required: The roots of a row's links: `<webOrigin>/artifacts/<id>` is the item's page in Roma, `<appScheme>://artifacts/<id>` the same item in the Roma Mac app.
    - `webOrigin` string, required
    - `appScheme` string, required

## Other responses

- `400`: The request was understood and refused; the error says what to change.
- `401`: No usable bearer token.
- `404`: No such item for this account.
- `405`: The path exists but not with this method; Allow lists the ones that work.
- `429`: Over the rate limit; wait for Retry-After.

---

[API](https://skmtc.dev/roma/apis/roma-api.md) - [All operations](https://skmtc.dev/roma/apis/roma-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roma/apis/roma-api/revisions/3dd91459b0fb?raw)