---
title: "Move Folder"
method: PUT
path: "/v1/external/folders/{folderId}/move"
tags: ["Folder"]
---

# Move Folder

`PUT /v1/external/folders/{folderId}/move`

Move a folder under a new parent, or to the root level with
`newParentId: null`. The target parent must be in the same workspace and you
must have access to it. You cannot move a folder into its own subtree.

Use `sharingTypeUpdateStrategy` to control how the folder's sharing
permissions are handled after the move (defaults to `KEEP_EXISTING`).

Requires edit access to the folder.

## Path parameters

- `folderId` string, required

## Request body

- MoveFolderRequest — Move a folder under a new parent, or to the root level.
  - `newParentId` string, nullable — Target parent folder ID. Omit or set to `null` to move the folder to the root level. The target parent must be in the same workspace and you must have access to it.
  - `sharingTypeUpdateStrategy` 'KEEP_EXISTING' | 'INHERIT_FROM_PARENT' — How the moved folder's sharing permissions are handled. | Strategy | Behavior | |----------|----------| | `KEEP_EXISTING` | Keep the folder's current `sharingType`. | | `INHERIT_FROM_PARENT` | Adopt the new parent folder's `sharingType`. | - `KEEP_EXISTING`: The folder retains its current access control after the move. - `INHERIT_FROM_PARENT`: The folder adopts its new parent's `sharingType` and its member list. You must have access to the new parent. Moving to the root level (`newParentId: null`) has no parent to inherit from, so the folder keeps its existing `sharingType`.

## Response `200`

Folder moved

- FolderDetail — A folder and its metadata.
  - `id` string, required — Unique identifier for the folder
  - `workspaceGuid` string, required — GUID of the workspace the folder belongs to
  - `title` string, required — Folder title (max 50 characters)
  - `description` string, required — Folder description. Empty string when unset.
  - `sharingType` 'PRIVATE' | 'ALL_MEMBER_VIEWER' | 'ALL_MEMBER_EDITOR' | 'LIMITED', required — Who can access a folder and the notes inside it. | Type | View | Edit | |------|------|------| | `PRIVATE` | Only you | Only you | | `ALL_MEMBER_VIEWER` | All workspace members | No member-wide edit access | | `ALL_MEMBER_EDITOR` | All workspace members | All workspace members | | `LIMITED` | Invited members only | Invited members only (per-member role) | - `PRIVATE`: Personal folder. Not shared with the workspace. - `ALL_MEMBER_VIEWER`: Every workspace member can view; no member-wide edit access is granted. - `ALL_MEMBER_EDITOR`: Every workspace member can view and edit. - `LIMITED`: Only explicitly invited members can access, each with an individual role (`VIEWER` or `EDITOR`).
  - `parentId` string, nullable, required — Parent folder ID. `null` for root-level folders. In the List Folders response, `parentId` is also `null` when the parent folder is not accessible to you.
  - `color` string, required — Folder color in hex format (#RRGGBB)
  - `isTeamFolder` boolean, required — `true` when the folder is shared with the workspace (any `sharingType` except `PRIVATE`); `false` for `PRIVATE` folders. Retained for backward compatibility — use `sharingType` for the precise access level.
  - `createdAt` string, date-time, required — ISO-8601 creation timestamp (UTC)
  - `updatedAt` string, date-time, required — ISO-8601 last-update timestamp (UTC)

## Other responses

- `400` — Bad request — target parent not found or in a different workspace, a circular move into the folder's own subtree, or the move would nest folders more than 5 levels below the root level
- `401` — Unauthorized — missing API key, or a team-only key was used
- `403` — Forbidden — no edit access to the folder or the target parent
- `404` — Folder not found

---

[API](https://skmtc.net/tiro/apis/tiro-api.md) · [All operations](https://skmtc.net/tiro/apis/tiro-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tiro/tiro-api/versions/ae18d7961aa4/schema)