ROroma
Items

Update items, many in one call

Update items, many in one call, each with its own title, body edits and values; the status, due date, archive and favorite flags apply to every item in the call. Only the fields passed change; null leaves a field as it is. The body is edited with edits against the handles get_item returns in body — replace, insert, delete, setChecked, move, replaceText, or rewrite pinned to bodyVersion — applied in order, all or nothing; a refused call writes nothing on that item and returns the current body with fresh handles. The older way, body with the call's merge mode (append by default, prepend, insertAfter with anchor, replace with confirmReplace: true), still works; an item uses one or the other. values MERGE into the item (only the properties sent change; "" clears one; an unknown property is an error naming the valid ones). imageUrls add images (clearImages: true drops the old ones first). taskStatus, dueAt, reminderAt and muteReminder apply only on a list that keeps them: a due date is a day, or a local time when one was stated, which also arms a reminder at that moment; reminderAt arms a reminder on a day without touching the date; muteReminder turns it off; dueAt "none" clears the due date and its reminder. Items are written in order; a refusal stops the batch and names the items already written, so re-send only the rest. Returns each item, with body, bodyVersion and applied after a body write.

patch/api/v1/items

Request

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

Request body

mode'prepend' | 'append' | 'replace' | 'insertAfter' nullable

Legacy: how each item's body merges: 'append' (default, at the bottom), 'prepend' (at the top), 'insertAfter' (right after the line named in anchor), or 'replace' (swap the whole body — only when the user explicitly asked to rewrite it; requires confirmReplace: true).

anchorstring nullable

For mode 'insertAfter' only: a verbatim snippet of the existing line to insert after. Errors if not found.

confirmReplaceboolean nullable

Required (true) for mode 'replace': confirms the user explicitly asked to swap the WHOLE body, deleting everything in it. Never pass it on the user's behalf without that explicit ask.

taskStatusstring nullable

On a list that keeps a status: 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. Applies to every item in the call. Status transitions report progress.

dueAtstring nullable

On a list that keeps a due date, for every item in the call: YYYY-MM-DD for a day the person named with no time (the usual case; nothing rings); YYYY-MM-DDTHH:MM in their local time when they stated a time, which also arms a push reminder at that moment. An instant with a zone (2026-10-28T09:00:00Z) is read as the day it falls on in their zone unless hasDueTime is true. A reminder already armed follows a moved day. "none" removes the due date with its time and reminder.

hasDueTimeboolean nullable

With a dueAt that carries a zone: true when its time of day is meant (the due is that moment and the reminder is armed), false to keep the day alone. Not needed for the two plain shapes.

reminderAtstring nullable

Arms a reminder without changing the visible due date, for every item in the call: YYYY-MM-DD (that day at the person's default reminder hour) or YYYY-MM-DDTHH:MM in their local time. An undated item is dated that day. A moment already passed arms nothing. Not beside dueAt "none" or muteReminder.

muteReminderboolean nullable

true turns the reminder off and leaves the due date and its time as they are, for every item in the call. Not beside reminderAt.

archivedboolean nullable

true sets the item(s) aside (hidden from every list, kept and reversible); false brings them back.

favoritedboolean nullable

true pins the item(s) in the app's Favorites; false unpins them.

Response

The tool's result.

updatednumber required
imagesAttachednumber required

Changes

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