# Retrieve the item category tree

Operation ID: `readItemCategoryTree`

Group: Inventory › Item Categories

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/readItemCategoryTree)

`GET /inventory/item-categories/tree`

Read-only: Reads and returns; changes nothing.

Retrieves the item category tree. Each category comes back with its parent, its depth in level, and in path the names from the top level down to the category itself. A category that has never been placed under a parent is at the top level, with level 0.

Categories are ordered by name, not by position in the tree, so build the tree from parentId.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | string · v1 | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |

## Response

`200` Success

Under `data` (readItemCategoryTreeOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | Every item category, each with its position in the tree, ordered by name. Example: `[{"id":"a2f47b91-0c6d-4e38-95b1-7d3e6a428c50","name":"Hardware","description":"Fasteners, fittings and tooling","level":0,"path":["Hardware"],"hasChildren":true},{"id":"4e08c752-9b1f-4a63-8d20-c5f7134e9ab8","name":"Servers","parentId":"a2f47b91-0c6d-4e38-95b1-7d3e6a428c50","level":1,"path":["Hardware","Servers"],"hasChildren":true},{"id":"9d61b0af-3c58-4e17-b942-06ea8c73f215","name":"Rack","parentId":"4e08c752-9b1f-4a63-8d20-c5f7134e9ab8","level":2,"path":["Hardware","Servers","Rack"],"hasChildren":false}]`. |
| `data[].id` | string | yes | The unique identifier for the item category. |
| `data[].name` | string | yes | The display name of the category, for example 'Hardware'. Not unique: two categories can share a name, so use id to address one. |
| `data[].description` | string | no | A free-form description of what the category covers. Absent when none was set. |
| `data[].parentId` | string | no | The identifier of the category this one sits under. Absent for a top-level category. See id on GET inventory/item-categories/:id. |
| `data[].level` | number | yes | The depth in the tree: 0 for a top-level category, 1 for its children, and so on, up to 5. |
| `data[].path` | array<string> | yes | The ancestor names from the root down, ending with this category's own name. A root's path is its own name alone. |
| `data[].hasChildren` | boolean | yes | Whether any category sits beneath this one. |

```json
{
  "data": {
    "data": [
      {
        "id": "a2f47b91-0c6d-4e38-95b1-7d3e6a428c50",
        "name": "Hardware",
        "description": "Fasteners, fittings and tooling",
        "level": 0,
        "path": [
          "Hardware"
        ],
        "hasChildren": true
      },
      {
        "id": "4e08c752-9b1f-4a63-8d20-c5f7134e9ab8",
        "name": "Servers",
        "parentId": "a2f47b91-0c6d-4e38-95b1-7d3e6a428c50",
        "level": 1,
        "path": [
          "Hardware",
          "Servers"
        ],
        "hasChildren": true
      },
      {
        "id": "9d61b0af-3c58-4e17-b942-06ea8c73f215",
        "name": "Rack",
        "parentId": "4e08c752-9b1f-4a63-8d20-c5f7134e9ab8",
        "level": 2,
        "path": [
          "Hardware",
          "Servers",
          "Rack"
        ],
        "hasChildren": false
      }
    ]
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Statuses

- `400` — Invalid request or business failure
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error