---
title: "Move an item"
method: POST
path: "/v1/content/items/{id}/move"
tags: ["Content"]
---

# Move an item

`POST /v1/content/items/{id}/move`

## Request

- Base URL: `https://api.banksync.io`
- URL: `https://api.banksync.io/v1/content/items/{id}/move`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Move a folder or an item into a folder (or to the top level), before a sibling or at the end. `anchor` is `stale` when the sibling you named had moved: the item went to the end.

## Path parameters

- `id` string, required: Item or folder ID, from the tree

## Headers

- `Idempotency-Key` string: Makes a retry safe: the same key with the same request replays the first answer for 24 hours instead of running twice, and the same key with a different request is a 409 `IDEMPOTENCY_KEY_REUSED`. Refusals a retry can outlive — 408, 409, 423, 425, 429 and every 5xx — are never replayed, so retrying with the same key after the cause clears runs the request.

## Request body

- object
  - `placement` object, required
    - `parentId` string, nullable, required: The folder, or null for the top level
    - `before` string, nullable, required: The sibling to go before, or null for the end
  - `expectedVersion` integer: The version you read; a change since answers 409 CONTENT_VERSION_CONFLICT

## Response `200`

The item, moved

- object
  - `success` true, required
  - `data` object, required
    - `item` object, required
      - `id` string, required
      - `kind` string, required
      - `resourceId` string
      - `parentId` string, nullable, required
      - `position` integer, required
      - `name` string, required
      - `icon` string, nullable, required
      - `color` string, nullable, required
      - `version` integer, required
      - `createdBy` object, required
        - `kind` string, required
      - `updatedBy` object, required
        - `kind` string, required
      - `createdAt` string, required
      - `updatedAt` string, required
      - `deletedAt` string, nullable, required
      - `level` 'view' | 'edit' | 'full'
      - `locked` boolean
      - `relocated` boolean
      - `decoration` object
        - `kind` 'badge' | 'marker', required
        - `label` string, required
      - `can` object
        - `rename` boolean, required
        - `move` boolean, required
        - `icon` boolean, required
        - `trash` boolean, required
        - `favourite` boolean, required
        - `trashReason` string
        - `trashAction` 'remove'
        - `hold` union
          - 'any' | 'none'
          - string[]
    - `anchor` 'resolved' | 'end' | 'stale', required

## Other responses

- `400`: Invalid input, a folder cycle or a tree too deep, or an item of a kind this workspace does not arrange here (`CONTENT_UNKNOWN_KIND`)
- `401`: Unauthorized
- `403`: Forbidden — a missing scope, a role below editor for a change, or an installed app (the tree is the whole workspace’s)
- `404`: Not found — no such item or folder (`CONTENT_NOT_FOUND`), or the tree is not enabled for this workspace
- `409`: Conflict — the item changed since you read it (`CONTENT_VERSION_CONFLICT`: read it again), or it is in trash (`CONTENT_IN_TRASH`: restore it first)
- `429`: Too many requests — the key’s rate limit
- `503`: Changes are paused (`CONTENT_STOPPED`) or the tree is unavailable (`CONTENT_UNAVAILABLE`); retry shortly

---

[API](https://skmtc.dev/banksync/apis/banksync-api.md) · [All operations](https://skmtc.dev/banksync/apis/banksync-api/llms.txt) · [OpenAPI document](https://skmtc.dev/banksync/apis/banksync-api/revisions/94465f5ee922?raw)