> For the complete documentation index, see [llms.txt](https://docs.ibexa.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ibexa.ai/developers/rest-api/knowledge-base/list-node-tree.md).

# List Node Tree

List the node hierarchy for the caller's organisation as a nested forest.

With `root_id`, returns that node's subtree (404 if it does not exist in the caller's organisation); otherwise the whole organisation tree. Siblings are ordered by type (folders before documents), then by name A-Z, unless `sort_by=citations` reorders every level by citation count instead. This is a structure view: nodes carry neither a document body nor their `metadata` — read those per node from the document and get-node endpoints.

With `search` (at least 3 characters, 400 below that), the tree keeps only nodes whose name contains it (case-insensitive substring), the ancestors leading to them, and — for a folder that matched — its whole subtree. `children: []` always means a node with no children, filter or not. The filters compose: with both, only matches inside `root_id`'s subtree are returned.

`citation_count` is how often agents have read a document; for a folder it is the sum over its whole subtree, and it is unaffected by `search` — a folder reports everything it contains, not just what the filter kept.

```json
{"openapi":"3.1.0","info":{"title":"Ibexa Agentic Marketing Platform","version":"0.1.0"},"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/api/v1/login/access-token"}}}},"schemas":{"KnowledgeNodeSortField":{"type":"string","enum":["name","citations"],"title":"KnowledgeNodeSortField","description":"What a node listing is ordered by.\n\n`NAME` is the default and means the tree's natural reading order: folders\nbefore documents, then name A-Z. `CITATIONS` orders by how often agents have\nread a node's documents, which deliberately drops the folders-first grouping\n(see `SortDirection`) — ranking by usage is pointless if containers and\nleaves are ranked in separate blocks."},"SortDirection":{"type":"string","enum":["asc","desc"],"title":"SortDirection","description":"Ascending or descending order for a sorted listing."},"KnowledgeNodeTreeResponseSchema":{"properties":{"id":{"type":"integer","title":"Id"},"organisation_id":{"type":"integer","title":"Organisation Id"},"node_type":{"$ref":"#/components/schemas/NodeType"},"name":{"type":"string","title":"Name"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"parent_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Parent Id"},"path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Path"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary"},"citation_count":{"type":"integer","title":"Citation Count"},"status":{"anyOf":[{"$ref":"#/components/schemas/VersionStatus"},{"type":"null"}]},"created_by":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeNodeUserSchema"},{"type":"null"}]},"updated_by":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeNodeUserSchema"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"children":{"items":{"$ref":"#/components/schemas/KnowledgeNodeTreeResponseSchema"},"type":"array","title":"Children"},"name_translations":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Name Translations","description":"Per-language display-name overrides (ISO 639-1 keys), for the two system-managed root folders only — null for every other node. `name` always stays the canonical English string; the caller decides which (if any) of these to show."}},"type":"object","required":["id","organisation_id","node_type","name","slug","parent_id","path","summary","citation_count","status","created_by","updated_by","created_at","updated_at","children"],"title":"KnowledgeNodeTreeResponseSchema","description":"Recursive response schema for a node hierarchy (tree view).\n\nDeliberately narrower than `KnowledgeNodeResponseSchema`: this is a structure\nview covering a whole organisation, so per-node payload multiplies across every\nnode in the tree. Audit fields are left out for that reason and `metadata` is\ntoo — read it per node from the get-node endpoint."},"NodeType":{"type":"string","enum":["folder","document"],"title":"NodeType","description":"The node-type discriminator — the single extension point for new types.\n\nOnly the local types exist today (`folder`, `document`); the CTI design\nkeeps adding types additive."},"VersionStatus":{"type":"string","enum":["draft","publishing","published","archived"],"title":"VersionStatus","description":"Publication state of a single knowledge-document version.\n\nA version is created `DRAFT` (editable, not live). Requesting publication\nmoves it to `PUBLISHING` (edit-locked) while its chunks are embedded; once\nthe embeddings are ready the pointer flip marks it `PUBLISHED` and the\npreviously published version becomes `ARCHIVED`. A rollback re-publishes an\n`ARCHIVED` version through the same `PUBLISHING` state. A failed go-live\nreturns the version to its pre-attempt state: a failed publish reverts to\n`DRAFT`, a failed rollback reverts to `ARCHIVED` (see `PublishOrigin`).\n\nLegal transitions are enforced by the `KnowledgeDocumentVersion` entity (its\nstatus setter is a state machine); this enum only names the states. Only\n`knowledge_document.published_version_id` decides what retrieval serves —\nthe status is descriptive history metadata for the UI."},"KnowledgeNodeUserSchema":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"email":{"type":"string","title":"Email"},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"}},"type":"object","required":["id","email","full_name"],"title":"KnowledgeNodeUserSchema","description":"Basic info about a node's creator/updater."}}},"paths":{"/api/v1/knowledge-base/nodes/tree":{"get":{"tags":["knowledge-base","public"],"summary":"List Node Tree","description":"List the node hierarchy for the caller's organisation as a nested forest.\n\nWith `root_id`, returns that node's subtree (404 if it does not exist in\nthe caller's organisation); otherwise the whole organisation tree. Siblings\nare ordered by type (folders before documents), then by name A-Z, unless\n`sort_by=citations` reorders every level by citation count instead. This is a\nstructure view: nodes carry neither a document body nor their `metadata` —\nread those per node from the document and get-node endpoints.\n\nWith `search` (at least 3 characters, 400 below that), the tree keeps only\nnodes whose name contains it (case-insensitive substring), the ancestors\nleading to them, and — for a folder that matched — its whole subtree.\n`children: []` always means a node with no children, filter or not. The\nfilters compose: with both, only matches inside `root_id`'s subtree are\nreturned.\n\n`citation_count` is how often agents have read a document; for a folder it\nis the sum over its whole subtree, and it is unaffected by `search` — a\nfolder reports everything it contains, not just what the filter kept.","operationId":"knowledge-base-list_node_tree","parameters":[{"name":"sort_by","in":"query","required":false,"schema":{"$ref":"#/components/schemas/KnowledgeNodeSortField","description":"Order by name (folders first, then A-Z) or by citation count. Sorting by citations interleaves folders and documents, since a ranking split into two blocks would not be a ranking","default":"name"},"description":"Order by name (folders first, then A-Z) or by citation count. Sorting by citations interleaves folders and documents, since a ranking split into two blocks would not be a ranking"},{"name":"sort_order","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SortDirection","description":"Ascending or descending. Most-cited first is sort_by=citations&sort_order=desc","default":"asc"},"description":"Ascending or descending. Most-cited first is sort_by=citations&sort_order=desc"},{"name":"root_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Return only this node's subtree instead of the whole tree","title":"Root Id"},"description":"Return only this node's subtree instead of the whole tree"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":3,"maxLength":255},{"type":"null"}],"description":"Keep nodes whose name contains this value (case-insensitive substring), plus their ancestors; if a folder matches, its whole subtree is included","title":"Search"},"description":"Keep nodes whose name contains this value (case-insensitive substring), plus their ancestors; if a folder matches, its whole subtree is included"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeNodeTreeResponseSchema"},"title":"Response Knowledge-Base-List Node Tree"}}}},"400":{"description":"Invalid request payload or parameters","content":{"application/json":{}}},"401":{"description":"User not authenticated","content":{"application/json":{}}},"403":{"description":"User lacks permission","content":{"application/json":{}}},"404":{"description":"Resource not found or user has no permission to access it","content":{"application/json":{}}}}}}}}
```