---
title: "See the folder tree"
method: GET
path: "/api/v1/folders/tree"
tags: ["authed"]
---

# See the folder tree

`GET /api/v1/folders/tree`

## Request

- Base URL: `https://api.teaflask.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.teaflask.com/api/v1/folders/tree`
- Auth: none declared

Every folder with its doc count, and every filed doc's place, in one
read; docs not in any folder are counted in unfiled_doc_count (list_docs
lists every doc).

## Response `200`

Successful Response

- FolderTreeResponse: The whole containment picture in one call: every folder (roots first, then children grouped by parent, in position order within each group), every filed doc's placement, and how many docs remain unfiled.
  - `folders` FolderNodeResponse[], required: Every folder: top-level folders first, then each folder's subfolders, in order.
    - `id` string, uuid, required: The folder's id.
    - `organization_id` string, uuid, required: The organization the folder belongs to.
    - `parent_id` string, uuid, nullable, required: The folder it sits inside; null for a top-level folder.
    - `position` integer, required: Its place among the folders that share its parent, from 0.
    - `name` string, required: The folder's name.
    - `icon` string, nullable, required: The folder's icon; null when it has none.
    - `created_at` string, date-time, required: When the folder was created.
    - `updated_at` string, date-time, required: When the folder last changed.
    - `doc_count` integer, required: How many docs sit directly in this folder, not counting its subfolders' docs.
    - `effective_tags` EffectiveTagResponse[], required: The tags the folder wears: its own and those passed down from the folders above it.
      - `id` string, uuid, required: The tag's id.
      - `slug` string, required: The tag's slug.
      - `name` string, required: The tag's display name.
      - `own` boolean, required: Whether the tag is assigned directly.
      - `inherited_from` TagProvenanceResponse[], required: The ancestor folders that pass the tag down, nearest first.
        - `folder_id` string, uuid, required: The folder the tag is inherited from.
        - `folder_name` string, required: That folder's name.
  - `docs` DocPlacementResponse[], required: Where each doc filed in a folder sits.
    - `doc_id` string, uuid, required: The doc's id.
    - `folder_id` string, uuid, required: The folder the doc is filed in.
    - `position` integer, required: The doc's place among the docs in that folder, from 0.
    - `title` string, required: The doc's title.
    - `slug` string, required: The doc's slug.
    - `effective_tags` EffectiveTagResponse[], required: The tags the doc wears: its own and those passed down from its folders.
      - `id` string, uuid, required: The tag's id.
      - `slug` string, required: The tag's slug.
      - `name` string, required: The tag's display name.
      - `own` boolean, required: Whether the tag is assigned directly.
      - `inherited_from` TagProvenanceResponse[], required: The ancestor folders that pass the tag down, nearest first.
        - `folder_id` string, uuid, required: The folder the tag is inherited from.
        - `folder_name` string, required: That folder's name.
  - `unfiled_doc_count` integer, required: How many docs are not in any folder.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `405`: Method not allowed
- `422`: Validation error
- `500`: Internal server error

---

[API](https://skmtc.dev/teaflask/apis/teaflask-api.md) - [All operations](https://skmtc.dev/teaflask/apis/teaflask-api/llms.txt) - [OpenAPI document](https://skmtc.dev/teaflask/apis/teaflask-api/revisions/d23e9286b847?raw)