---
title: "Creates an item category."
method: POST
path: "/api/v1/categories"
tags: ["Categories"]
---

# Creates an item category.

`POST /api/v1/categories`

## Request

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

Requires `ManageInventory` and an `Idempotency-Key` header. Same as "New Category" on
the Item Categories page, with stricter checks: the name must be unique among the categories
with the same parent, and the parent must be one of your categories that is neither the
built-in "No Category" nor Template Builder-generated. The new category has no properties.
Example: `{ "name": "Hardwood", "parentCategoryId": 1 }`.

## Request body

- CreateCategoryApiRequest: Body of `POST /api/v1/categories`. Example: `{ "name": "Hardwood", "description": "Oak, maple, walnut", "parentCategoryId": 1 }`.
  - `name` string, required: Category name, 1-100 characters (trimmed), unique among the categories with the same parent (case-insensitive), e.g. `"Hardwood"`.
  - `description` string, nullable: Optional description, at most 2000 characters; blank is stored as none.
  - `parentCategoryId` integer, nullable: Parent category id (a category of your organization that is not Template Builder-generated), e.g. `1`; omit, null or `0` for a top-level category.

## Response `201`

Created; body is the new category, `Location` points at it.

- 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`: Malformed body, missing or blank `name`, a field over its limit, or missing `Idempotency-Key`.
- `401`: Unauthorized
- `403`: The key lacks `ManageInventory`.
- `409`: A category with this name already exists under the same parent, or the key's creator is unknown on this server.
- `422`: No such (usable) parent category, including a negative `parentCategoryId` (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)