---
title: "Move items onto another list"
method: POST
path: "/api/v1/items/move"
tags: ["Items"]
---

# Move items onto another list

`POST /api/v1/items/move`

## Request

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

Move items onto another list: a task out to the Tasks list ("tasks"), a note onto the Notes list ("notes"), anything onto a list by id. Each item keeps its id, body, chat and history; its values follow their properties by id, then by name and type, select values by label. A value the destination list has no place for would be DROPPED: a first call that would drop values answers a preview (preview: true, droppedValues) and moves nothing; the same call with acknowledgeDataLoss: true then moves. The status and due date ride along unseen onto a list that keeps neither and show again on the way back. An item inside a list shared with the user moves as far as the app lets them: out onto one of their own lists (it becomes theirs, and everyone in the shared list loses it), or into another shared list they are in; such a move changes who can reach the item, so the first call answers a preview (accessChanges, the app's own question) and moves nothing until the repeat with acknowledgeDataLoss: true. An item shared with the user one item at a time stays its owner's to move: it is reported under `refused` with the reason, never moved.

## Request body

- object
  - `itemIds` string[], required: Ids of the items to move.
  - `listId` string, required: The destination list: 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).
  - `acknowledgeDataLoss` boolean, nullable: true ONLY on a repeat call, after a preview reported values the destination list has no place for, or people who will gain or lose access, and you told the user what will happen.

## Response `200`

The tool's result.

- object
  - `preview` boolean
  - `listId` string
  - `listName` string, nullable
  - `items` object[]
    - `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
  - `droppedValues` object[]
    - `itemId` string, required
    - `title` string, nullable, required
    - `dropped` object[], required
      - `propertyId` string, required
      - `name` string, required
      - `count` number, required
  - `accessChanges` object[]
    - `itemId` string, required
    - `title` string, nullable, required
    - `question` string, required
    - `consequence` string, required
  - `refused` string[]
  - `refusals` object[]
    - `itemId` string, required
    - `reason` 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)