Always returns { data, pagination }. Pagination counts root categories only (depth 0). Flat list (withChildren omitted or false): data[i] is a root category. withChildren=true: each data[i] is a root with its children[] (depth 1) attached; children are not independently paged. Optional search matches root name or description (substring, LIKE %value%); in tree mode, a matching direct child also includes its parent root. Optional hasProducts=true limits roots (and in tree mode, each root’s children[]) to categories that have at least one non-deleted product in product_category_map.

Access: Auth methods: JWT bearer or API key. Allowed user types: MVNO, PARTNER. Requires permissions: product-category:read.