---
title: "List the workspace's folders"
method: GET
path: "/v1/assets/folders"
tags: ["assets"]
---

# List the workspace's folders

`GET /v1/assets/folders`

## Request

- Base URL: `https://api.patricia.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.patricia.app/v1/assets/folders`
- Auth: HTTP bearer

Every folder in the workspace, in alphabetical order. Each carries its `parent_id` and its full `path`, the number of live files filed directly in it, and the number in its whole branch. Folders nest, so two folders can share a name in different parents and the `path` is what tells them apart. `total` is the true number, so a capped list can never read as the whole set.

## Headers

- `X-Tenant-Id` string, nullable

## Response `200`

Successful Response

- AssetFolderList: Every folder the workspace has, plus the true count. ``total`` is a real ``COUNT(*)``, like :class:`AssetPage`'s: the list is capped, and a capped rail that reported its own length as the total would read as the whole set.
  - `items` AssetFolderSummary[], required
    - `id` string, uuid, required
    - `name` string, required: The folder's label. UNTRUSTED text: render escaped.
    - `parent_id` string, uuid, nullable: The folder this one is inside, or null when it sits at the top level.
    - `path` string: The full path, separated by '/' (e.g. 'Clients/Acme'). UNTRUSTED text: render escaped. Names repeat across folders, so this is what tells two folders called 'Q3' apart.
    - `depth` integer: How deep the folder sits. A top-level folder is 1.
    - `asset_count` integer, required: Live files filed in THIS folder. Removed files are not counted.
    - `byte_size` integer, required: What those files weigh, in bytes.
    - `subtree_asset_count` integer: Live files in this folder AND everything inside it. The rail shows both numbers ('Clients (3, 47 in all)') because one number that could mean either is a number nobody can act on.
    - `subtree_byte_size` integer: What the whole branch weighs, in bytes.
    - `created_at` string, date-time, required: When the folder was made (UTC).
    - `is_shared` boolean, required: Whether this folder currently holds a live share link. When true, every live file in it is readable outside the workspace through that link, whatever each file's own 'Only me' / 'My team' / 'Anyone with the link' setting says.
    - `content_modified_at` string, date-time, nullable: The newest 'last touched' stamp across this folder's whole branch (UTC); null when the branch holds no live file. 'Touched' matches the file grouping's own meaning: a new version, but also filing a file here or favoriting it, moves this — not only editing content.
    - `author` AssetAuthor: Who made a file, as a person reads it — the designs' "Made by" column and detail row. Two fields answer two different questions and neither substitutes for the other. ``display_name`` is WHOSE work this is; ``made_by_patricia`` is whether Patricia's hands did it. A file Patricia generated because Ricardo asked her to carries both — the dashboard renders "Patricia for Ricardo" — and that is the ordinary case, not an edge one. ``display_name`` is ``null`` only when nothing resolves: an API-key upload (not a person), a headless cron run with no requester, or a workspace member whose chat profile was never enriched. It is NEVER a raw platform id — it comes from :meth:`~repositories.actor.ActorRepository.resolve_actor_displays`, the one resolver every human-facing render site shares, which humanizes a placeholder id back into ``null`` here.
      - `actor_id` string, uuid, nullable: The workspace member credited with this file. The key the author filter takes; null when no person is recorded (an API-key upload, or a run with no requester).
      - `display_name` string, nullable: That member's name. Null when nothing resolves — render 'Patricia' or 'Someone'.
      - `made_by_patricia` boolean: Whether a Patricia run created this file. True with a display_name reads 'Patricia for <name>'; true without one reads 'Patricia'; false reads the name alone.
  - `total` integer, required: Folders in this workspace, including any beyond the returned list.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden. Inspect response body `code` for the specific reason (for example: PERMISSION_DENIED, EMAIL_NOT_VERIFIED, TENANT_ACCESS_REQUIRED, ROLE_UNRESOLVED)
- `422`: Validation error

---

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