---
title: "Move Folder"
method: PUT
path: "/v2/folder/{folder_id}/position"
tags: ["Folders"]
---

# Move Folder

`PUT /v2/folder/{folder_id}/position`

## Request

- Base URL: `https://api.clickup.com/api`
- URL: `https://api.clickup.com/api/v2/folder/{folder_id}/position`
- Auth: API key in header `Authorization`

Move a Folder, either by nesting it inside another Folder as a subfolder or by moving it to another Space as a top-level Folder.

Provide `parent_folder_id` to nest the Folder inside another Folder, or `space_id` to move it to another Space as a top-level Folder. If both are provided, `parent_folder_id` takes precedence and `space_id` is ignored, so the Folder inherits the Space of its new parent Folder. Use `position` to control placement among siblings in the destination; the Folder is placed at the top when `position` is omitted.

Nesting a Folder requires subfolder support to be enabled for the Workspace. Lists and tasks in the Folder move with it. To rename a Folder instead, use the [Update Folder](#tag/Folders/operation/UpdateFolder) endpoint.

## Path parameters

- `folder_id` number, required

## Request body

- object
  - `parent_folder_id` string: ID of the Folder to nest this Folder inside of, making it a subfolder. The destination Folder must be in the same Workspace. Subfolder support must be enabled for the Workspace.
  - `space_id` string: ID of the Space to move this Folder to as a top-level Folder. Ignored when `parent_folder_id` is also provided, in which case the Folder inherits the Space of its new parent Folder.
  - `position` integer: Position of the Folder among its siblings in the destination. Defaults to the top of the destination when omitted.
  - `custom_type_map` object: Map of task type IDs in the Folder to the task type IDs to use after the move, as `{"<source_type_id>": <destination_type_id>}`. Required when moving to a destination where a task type used in the Folder is unavailable.

## Response `200`

- object

## Other responses

- `400`: The move is not allowed. `ECODE` identifies the reason: * `CAT_147` - a Folder cannot be its own parent. * `CAT_148` - the destination Folder is a subfolder of the Folder being moved, which would create a circular reference. * `CAT_137` - the move would exceed the Workspace's subfolder nesting limit. * `CAT_158` - the move would exceed the nesting limit because of archived subfolders. * `CAT_159` - a Folder cannot be nested inside a hidden Folder. * `CAT_140` - a Sprint Folder already exists in the destination's parent chain. * `CAT_141` - a Sprint Folder cannot be moved into a Folder that contains a Sprint Folder.

## Changes

- **2026-11-03** `a0a72ec97ddb`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/clickup/apis/clickup-api-v2-reference/changes/v2/folder/:folder_id/position/put.md)

---

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