---
title: "Move a folder"
method: PUT
path: "/v1/assets/folders/{folder_id}/parent"
tags: ["assets"]
---

# Move a folder

`PUT /v1/assets/folders/{folder_id}/parent`

## 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/{folder_id}/parent`
- Auth: HTTP bearer

Move a folder into another folder, or send `parent_id: null` to move it to the top level. The files in it and the folders inside it move with it. Sending the same body twice leaves the same state. Answers 404 when the folder or the destination does not exist or belongs to another workspace, 409 when the destination already has a folder with this name, and 400 when the move would put a folder inside itself or nest folders too deeply.

## Path parameters

- `folder_id` string, uuid, required: The folder to move.

## Headers

- `X-Tenant-Id` string, nullable

## Request body

- AssetFolderReparent: Move a folder into another folder, or out to the top level. ``parent_id`` is REQUIRED and nullable rather than optional, exactly like :class:`AssetFolderAssign`: "move it to the top level" is a real, ordinary request, and an optional field cannot tell it apart from a body that forgot to say.
  - `parent_id` string, uuid, nullable, required: The folder to move it into, or null to move it to the top level. A folder cannot be moved into itself or into anything inside it.

## Response `200`

Successful Response

- AssetFolderSummary: One folder as the rail draws it: where it sits, what it holds, and what its branch holds.
  - `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.

## 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)
- `404`: No such folder in this workspace.
- `409`: A folder with that name already exists.
- `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)