---
title: "Replace a folder's contents (move + reorder)"
method: PUT
path: "/api/v1/ackdb/observe/segment-folders/{id}/items"
tags: ["ackDB"]
---

# Replace a folder's contents (move + reorder)

`PUT /api/v1/ackdb/observe/segment-folders/{id}/items`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/ackdb/observe/segment-folders/{id}/items`
- Auth: HTTP bearer

Replaces the folder's ordered contents. This is BOTH the move and the reorder call: array order becomes each segment's `position`, and filing a segment here pulls it out of whatever folder it was in (a segment sits in at most one folder per user), so a drag from folder A to folder B is ONE request against B. Segments previously in this folder and absent from the body are unfiled; segments the caller filed in OTHER folders and did not mention are untouched. Every id must be a segment the caller can SEE — `view` access is enough, since organising your own rail is not editing the segment. Unknown and invisible ids are reported together in one 400 (`error.details.errors.segmentIds`) so the response cannot be used to discover whether a private segment exists; nothing is moved.

## Path parameters

- `id` string, required

## Request body

- object
  - `segmentIds` string[], required: Segment ids in the desired order. Empty array empties the folder.

## Response `200`

The folder's contents after the write.

- object
  - `data` object, required
    - `folderId` string, required
    - `items` AckdbSegmentFolderItem[], required
      - `segmentId` string, required
      - `position` integer, required: Manual order within the folder, ascending.

## Other responses

- `400`: Malformed segmentIds, an id the caller cannot see, or no user identity.
- `404`: FOLDER_NOT_FOUND — no such folder, or it belongs to another user.

---

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