---
title: "Bulk add, update, remove, and reorder items"
method: PATCH
path: "/api/v1/lists/{id}/items"
tags: ["lists"]
---

# Bulk add, update, remove, and reorder items

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

## Request

- Base URL: `https://www.listdrop.co`
- URL: `https://www.listdrop.co/api/v1/lists/{id}/items`
- Auth: OAuth 2 (authorization code, authorization URL `https://www.listdrop.co/oauth/authorize`, token URL `https://www.listdrop.co/api/oauth/token`, scopes: `lists:write`)

Structured item operations in one call on a list the connected account can edit (owner or collaborator). `ops` is an ordered array of {op:'add', text, note?} / {op:'update', id, text?, note?} / {op:'remove', id}; the optional `order` array of root item ids reorders the list (listed ids first, the rest keep their relative order). Root items only; adds run through the magic-paste pipeline (a URL in the text unfurls into a titled, linked item). Followers see one activity entry per verb, not one per item. Caps: 100 ops per call, 60 calls/hour.

## Path parameters

- `id` string, required

## Request body

- BulkItemsRequest
  - `ops` object[]: Ordered operations. add: {op, text, note?}; update: {op, id, text?, note?}; remove: {op, id}.
    - `op` 'add' | 'update' | 'remove', required
    - `id` string: Target item id (update/remove).
    - `text` string
    - `note` string, nullable: null/empty clears the note.
  - `order` string[]: Root item ids in the desired order (listed first; the rest keep their relative order).

## Response `200`

Applied. Lists the created item ids and the update/remove counts.

- BulkItemsResponse
  - `ok` boolean, required
  - `added` object[], required: Created items, in op order (text is the post-unfurl title).
    - `id` string, required
    - `text` string, required
  - `updatedCount` integer, required
  - `removedCount` integer, required
  - `reordered` boolean, required

## Other responses

- `400`: Malformed ops (unknown op, empty text, item not on this list).
- `401`: Missing/invalid bearer token.
- `404`: List not found, or the account can't edit it.
- `429`: Rate limit hit. Honor Retry-After.

---

[API](https://skmtc.dev/listdrop/apis/listdrop-public-api.md) · [All operations](https://skmtc.dev/listdrop/apis/listdrop-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/listdrop/apis/listdrop-public-api/revisions/699b5367e2f3?raw)