---
title: "Change a list's name, icon, instructions, layout or properties"
method: PATCH
path: "/api/v1/lists/{id}"
tags: ["Lists"]
---

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

`PATCH /api/v1/lists/{id}`

## Request

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

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.

## Path parameters

- `id` string, required

## Request body

- object
  - `section` string, 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.
  - `name` string, nullable: New name. Omit, or pass null, to leave it unchanged.
  - `icon` string, nullable: New emoji; "" removes it. Omit, or pass null, to leave it unchanged.
  - `instructions` string, nullable: REPLACES the standing rules (max 500 characters); "" clears them. Omit, or pass null, to leave them unchanged.
  - `titleLabel` string, 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'.
  - `columnOrder` string[], nullable: Left-to-right property order: EVERY property exactly once, by property id.
  - `addProperties` object[], nullable: Properties to ADD, every one in this call. Existing items leave a new property unset.
    - `name` string, required: The property's name.
    - `type` 'text' | 'number' | 'date' | 'url' | 'select' | 'multiSelect' | 'person', required: The property's type. 'select' = ONE choice from a fixed set; 'multiSelect' = ANY NUMBER of choices (tags, genres); 'person' = people with access to the item, by id or name; text / number / date / url otherwise.
    - `options` string[], nullable: select/multiSelect properties only: the choice labels.
  - `updateProperty` object, nullable: ONE property to rename, retype or re-option.
    - `propertyId` string, required: The property's stable id (e.g. 'c2'; 'status' / 'dueDate' for the reserved ones).
    - `name` string, nullable: New name, or null to leave it unchanged.
    - `type` 'text' | 'number' | 'date' | 'url' | 'select' | 'multiSelect' | 'person', nullable: New type, or null to keep the current type. Existing values migrate (text→select/multiSelect builds options from the current values; select ↔ multiSelect keeps the options; multiSelect → select keeps each item's first choice; →person keeps each value that names exactly one person with access to the item, by id or name). A change that would clear or trim values returns a PREVIEW first — see acknowledgeDataLoss.
    - `options` object[], nullable: For a select or multiSelect property: the FULL replacement option list, in display order. Every existing option you want to KEEP must appear, by id — anything omitted is REMOVED and the items using it lose their value. On the reserved status these are WHICH of the workspace's statuses the list uses — their order is the workspace's, set in Settings, and is not read here: name each by its id or its word (todo, inProgress, completed always; backlog, inReview, canceled and the person's own where Settings has them on); a word that is no status of the workspace is refused — statuses are made in Settings → General → Statuses, never here; a status left out is removed from this list, and one still held by items needs statusMoveTo. null leaves the options untouched.
      - `id` string, nullable: The EXISTING option's id when keeping or RENAMING it; null for a brand-new option. Renaming without the id is how a rename becomes a delete.
      - `label` string, required: The option's label — the new text when renaming.
  - `statusMoveTo` string, 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.
  - `deletePropertyIds` string[], nullable: Stable ids of the properties to remove, every one in this call.
  - `acknowledgeDataLoss` boolean, 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 `200`

The tool's result.

- object
  - `id` string, required
  - `name` string, required
  - `icon` string, nullable
  - `instructions` string, nullable
  - `titleLabel` string, 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.
  - `layout` string
  - `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.
  - `properties` object[]
    - `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
  - `statusPropertyId` string, nullable: "status" when the list keeps its items' status in the task columns.
  - `dueDatePropertyId` string, nullable: "dueDate" when the list keeps its items' due date in the task columns.
  - `itemCount` number: 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.
  - `isLifeAdmin` boolean
  - `section` object, nullable: The sidebar section the list stands in (id and name); the default section's id is "lists". null on a list somebody shared with the user that they have not filed into a section (it stands under Shared with me).
    - `id` string, required
    - `name` string, required
  - `isPinned` boolean: true when the user pinned the list to the top of the sidebar, beside Tasks.
  - `preview` boolean
  - `warning` string

## 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)