---
title: "Lists the organization's item categories, one page at a time."
method: GET
path: "/api/v1/categories"
tags: ["Categories"]
---

# Lists the organization's item categories, one page at a time.

`GET /api/v1/categories`

## Request

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

Requires `ViewInventory`. Categories are flat with a `parentCategoryId`; nest them
client-side. The built-in system category is not listed. Example:
`GET /api/v1/categories?parentCategoryId=0` returns the top-level categories.
Also available as CSV (`Accept: text/csv` or `?format=csv`); paging cursor in `X-Next-Cursor`.

## Query parameters

- `search` string
- `parentCategoryId` integer
- `updatedSince` string, date-time
- `after` string
- `limit` integer
- `format` 'csv'

## Response `200`

A page of categories.

- PagedResponseOfCategoryDto: One page of a cursor-paginated /api/v1 collection (API_AND_MCP.md: `?after=<syncId>&limit=`).
  - `items` CategoryDto[]: Items of this page in ascending creation order.
    - `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.
  - `nextCursor` string, nullable: SyncId of the last item; pass it back as `?after=` to fetch the next page. `null` when this is the last page.

## Other responses

- `400`: Malformed `after` cursor.
- `401`: Unauthorized
- `403`: Forbidden
- `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)