---
title: "Update File Folder"
method: PATCH
path: "/api/v1/file-folders/{folder_id}"
tags: ["file-folders"]
---

# Update File Folder

`PATCH /api/v1/file-folders/{folder_id}`

Rename and/or toggle merge and/or update write-semantics (incl. the
full_delivery batch fields) on a FileFolder.

Ordering: deterministic pre-checks FIRST, then write-semantics, then
rename, then merge_enabled. Each of the three blocks commits its own
transaction internally (full cross-block atomicity is out of scope — see
the "Atomicity contract" comment below), so every failure mode that's
deterministic from the request body + the folder's state at the start of
the request (not a race) is checked upfront, before any block runs: a
request like ``{merge_enabled: true, write_semantics: "replace_overlap",
coverage_columns: ["bad_col"]}`` on a folder with existing subfolders
fails on the pre-check with no side effect at all, instead of committing
the semantics change and then 409-ing on ``merge_enabled``. Similarly a
rename that collides with a sibling name is caught before the semantics
block runs, not after.
Note the collection-schema subset check inside the semantics block still
uses the CURRENT ``merge_database_id``, which is ``None`` when
``merge_enabled`` is being turned on in this same request (the check is
then skipped since there's no collection schema yet); a bad coverage
column in that combination surfaces later as a per-file ``merge_error``
on the next merge rather than a 400 here.

## Path parameters

- `folder_id` string, uuid, required

## Request body

- FileFolderUpdate — PATCH payload — every field is optional so the same endpoint covers rename and merge toggle (mutually exclusive at most use sites; a single request that sets both is honoured in declaration order: rename first, then merge toggle, so a rename of a soon-to-be-merge folder picks up the new collection name without an extra round-trip).
  - `name` string, nullable
  - `merge_enabled` boolean, nullable
  - `write_semantics` 'append' | 'replace_overlap' | 'replace_all' | 'full_delivery', nullable
  - `coverage_columns` string[], nullable
  - `coverage_granularity` 'exact' | 'day' | 'month' | 'quarter' | 'year', nullable
  - `batch_key_pattern` string, nullable
  - `batch_size` integer, nullable
  - `batch_timeout_hours` number, nullable

## Response `200`

Successful Response

- FileFolderRead
  - `id` string, required
  - `name` string, required
  - `parent_folder_id` string, nullable
  - `merge_enabled` boolean, required
  - `schema_mode` string, required
  - `merge_database_id` string, nullable, required
  - `write_semantics` string
  - `coverage_columns` string[], nullable
  - `coverage_granularity` string
  - `batch_key_pattern` string, nullable
  - `batch_size` integer, nullable
  - `batch_timeout_hours` number, nullable
  - `sealed_batch_key` string, nullable
  - `member_count` integer
  - `has_children` boolean

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/netter/apis/dmi-backend.md) · [All operations](https://skmtc.net/netter/apis/dmi-backend/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/netter/dmi-backend/versions/a59877bf911b/schema)