---
title: "Create a segment folder"
method: POST
path: "/api/v1/ackdb/observe/segment-folders"
tags: ["ackDB"]
---

# Create a segment folder

`POST /api/v1/ackdb/observe/segment-folders`

## Request

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

Creates a folder at the END of the caller's rail, so appending never reshuffles what they already arranged. Names are unique per owner, case-insensitively — two identically named folders in one rail are indistinguishable to the person reading it.

## Request body

- object
  - `name` string, required

## Response `201`

Folder created.

- object
  - `data` AckdbSegmentFolder, required: A folder in ONE user's segment rail (#470). Folders are a personal filing layer: they are created, read, and written only by their owner, they are flat (a folder never contains another folder), and they span grains — one folder can hold company, contact and person segments, which is what keeps a derived segment filed next to the base it was pivoted from.
    - `id` string, required
    - `name` string, required
    - `ownerEmail` string, required: The owner's lowercased email. Always the caller — folders are personal.
    - `position` integer, required: Manual rail order within the owner's set, ascending.
    - `segmentCount` integer: Segments in this folder the caller can currently SEE, narrowed to the requested `entityKind` (all grains when none is given). Not a raw row count: a segment that was unshared from the caller keeps its placement but is not counted, since the rail cannot render it. Present on the list response only.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required

## Other responses

- `400`: Missing/blank/too-long name, no user identity, or the 200-folder ceiling reached.
- `409`: FOLDER_NAME_CONFLICT — the caller already has a folder with this name.

---

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