---
title: "Renames, re-describes or moves an item category; only the fields sent change."
method: PATCH
path: "/api/v1/categories/{id}"
tags: ["Categories"]
---

# Renames, re-describes or moves an item category; only the fields sent change.

`PATCH /api/v1/categories/{id}`

## Request

- Base URL: `https://app.flexonthejob.com`
- URL: `https://app.flexonthejob.com/api/v1/categories/{id}`
- Auth: HTTP bearer

Requires `ManageInventory` and an `Idempotency-Key` header. Same as editing the
category (or dragging it in the tree) on the Item Categories page. Moving a category
(`parentCategoryId`; `0` = top level) is refused when it would create a cycle, and
recalculates every item's inherited parent categories. Template Builder-generated categories
are managed by their Template Builder and cannot be changed here.
Example: `{ "name": "Softwood", "parentCategoryId": 0 }`.

## Path parameters

- `id` integer, required

## Request body

- UpdateCategoryApiRequest: Body of `PATCH /api/v1/categories/{id}`: omitted (or null) fields are unchanged; at least one is required. Example: `{ "name": "Softwood", "parentCategoryId": 0 }` renames the category and moves it to the top level.
  - `name` string, nullable: New name, 1-100 characters (trimmed), unique among the categories with the same parent (case-insensitive).
  - `description` string, nullable: New description, at most 2000 characters; `""` clears it.
  - `parentCategoryId` integer, nullable: New parent category id; `0` moves the category to the top level. The parent may not be the category itself or one of its descendants (no cycles), a system or a Template Builder-generated category.

## Response `200`

Changed; body is the category.

- CategoryDto: An item category of the calling organization, as returned by `GET /api/v1/categories`. Categories form a tree via `parentCategoryId`; an item's `categoryId` points here. System categories (the built-in "No Category") are not listed.
  - `id` integer: Numeric category id, e.g. `4`; the `categoryId` of items and the id used by `/api/v1/categories/{id}/properties`.
  - `syncId` string, uuid: Globally unique sync id (GUID). Use it as the `after` pagination cursor.
  - `name` string: Category name, e.g. `"Lumber"`.
  - `description` string, nullable: Optional description; null when unset.
  - `parentCategoryId` integer, nullable: Id of the parent category; null for a top-level category.
  - `isTemplateBuilderCategory` boolean: True when the category was generated by a Template Builder (its name and place in the tree are managed there, not on the Item Categories page).
  - `createdAt` string, date-time: UTC creation timestamp (ISO-8601).
  - `updatedAt` string, date-time, nullable: UTC timestamp of the last edit of the category itself; null when never edited. Property changes do not move it.

## Other responses

- `400`: Empty body (no field to change), malformed body, a field over its limit, or missing `Idempotency-Key`.
- `401`: Unauthorized
- `403`: The key lacks `ManageInventory`.
- `404`: No such category in this organization.
- `409`: The category is Template Builder-generated, another category under the (new) parent already has the name, or the key's creator is unknown on this server.
- `422`: Blank name, no such (usable) parent, or the parent is the category itself or one of its descendants (the field is listed in `errors`); or `Idempotency-Key` reused with a different body.
- `429`: Too Many Requests

---

[API](https://skmtc.dev/flexonthejob/apis/flex-api.md) · [All operations](https://skmtc.dev/flexonthejob/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flexonthejob/apis/flex-api/revisions/19c8f4d27acf?raw)