ROroma
Lists

Change a list's name, icon, instructions, layout or properties

Change a list: its name, icon, standing instructions, layout, or its properties. instructions REPLACES the existing text (read it first with list_lists and carry forward what is still true; null clears it). addProperties adds properties (every one in this call), updateProperty renames, retypes or re-options ONE property, deletePropertyIds removes properties, columnOrder reorders them. A retype migrates the items' values; one that would clear or trim values answers a PREVIEW (preview: true, what would be lost) and writes nothing until the same call is repeated with acknowledgeDataLoss: true. The reserved status and due date properties can be renamed, never retyped or removed. The title column is renamed through titleLabel (it stays every item's title), never retyped, removed or hidden. section moves the list into a sidebar section (an id or name from list_lists, or a new name, which makes the section; null puts it back in the default section) — on a list somebody shared with the user it files the list on their own rail. Every other field changes a list shared with the user as it changes their own: a member edits the whole list for everyone in it. Only the fields passed change.

patch/api/v1/lists/{id}

Request

  • Base URL
    https://api.roma.app
  • URL
    https://api.roma.app/api/v1/lists/{id}
  • Auth
    HTTP bearer

Path parameters

idstring required

The list's id (from list_lists or get_context).

Request body

sectionstring nullable

Move the list into a sidebar section: a section's id or name from list_lists, or a NEW name, which makes the section; null moves it to the default section. Omit to leave it where it is.

namestring nullable

New name. Omit, or pass null, to leave it unchanged.

iconstring nullable

New emoji; "" removes it. Omit, or pass null, to leave it unchanged.

instructionsstring nullable

REPLACES the standing rules (max 500 characters); "" clears them. Omit, or pass null, to leave them unchanged.

titleLabelstring nullable

The title column's new name on this list (Name, Book, Client); "" resets it to Title. Omit, or pass null, to leave it unchanged. The column stays every item's title under any name.

layout'list' | 'kanban' | 'table' nullable

How the list opens: 'list', 'kanban' (the board) or 'table'.

columnOrderstring[] nullable

Left-to-right property order: EVERY property exactly once, by property id.

statusMoveTostring nullable

When the reserved status's options drop ONE status that items still hold: the status id those items move to first. Without it the call is refused naming the count.

deletePropertyIdsstring[] nullable

Stable ids of the properties to remove, every one in this call.

acknowledgeDataLossboolean nullable

true ONLY on a repeat call, after a preview reported items that would clear or trim and you told the user what will be lost.

Response

The tool's result.

idstring required
namestring required
iconstring nullable
instructionsstring nullable
titleLabelstring nullable

The title column's name on this list (Name on a CRM, Book on a reading list); null reads as Title. An item's name is its title under any label.

layoutstring
role'tasks' | 'notes' | 'other'

What the list's items are, read from its properties: "tasks" when it keeps the status and the due date, "notes" when it has no properties, "other" when its properties are its own.

statusPropertyIdstring nullable

"status" when the list keeps its items' status in the task columns.

dueDatePropertyIdstring nullable

"dueDate" when the list keeps its items' due date in the task columns.

itemCountnumber

The list's open items: every live item but a repeating template, and never a completed one on a list that keeps its status in the task columns.

isLifeAdminboolean
isPinnedboolean

true when the user pinned the list to the top of the sidebar, beside Tasks.

previewboolean
warningstring

Changes

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