---
title: "Restore folder"
method: POST
path: "/folders/{folder_id}"
tags: ["Trashed folders"]
---

# Restore folder

`POST /folders/{folder_id}`

Restores a folder that has been moved to the trash.

An optional new parent ID can be provided to restore the folder to in case the
original folder has been deleted.

During this operation, part of the file tree will be locked, mainly
the source folder and all of its descendants, as well as the destination
folder.

For the duration of the operation, no other move, copy, delete, or restore
operation can performed on any of the locked folders.

## Path parameters

- `folder_id` string, required

## Query parameters

- `fields` string[]

## Request body

- object
  - `name` string — An optional new name for the folder.
  - `parent` object — Specifies an optional ID of a folder to restore the folder to when the original folder no longer exists. Please be aware that this ID will only be used if the original folder no longer exists. Use this ID to provide a fallback location to restore the folder to if the original location has been deleted.
    - `id` string — The ID of parent item.

## Response `201`

Returns a folder object when the folder has been restored.

- TrashFolderRestored — Represents a folder restored from the trash.
  - `id` string — The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folders/123` the `folder_id` is `123`.
  - `etag` string, nullable — The HTTP `etag` of this folder. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the folder if (no) changes have happened.
  - `type` 'folder' — The value will always be `folder`.
  - `sequence_id` string — A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource.
  - `name` string — The name of the folder.
  - `created_at` string, date-time, nullable — The date and time when the folder was created. This value may be `null` for some folders such as the root folder or the trash folder.
  - `modified_at` string, date-time, nullable — The date and time when the folder was last updated. This value may be `null` for some folders such as the root folder or the trash folder.
  - `description` string — The optional description of this folder.
  - `size` integer — The folder size in bytes. Be careful parsing this integer as its value can get very large.
  - `path_collection` object — The tree of folders that this file is contained in, starting at the root.
    - `total_count` integer, required — The number of folders in this list.
    - `entries` FolderMini[], required — The parent folders for this item.
      - `id` string, required — The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folders/123` the `folder_id` is `123`.
      - `etag` string, nullable — The HTTP `etag` of this folder. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the folder if (no) changes have happened.
      - `type` 'folder', required — The value will always be `folder`.
      - `sequence_id` string — A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource.
      - `name` string — The name of the folder.
  - `created_by` object — The user who created this folder.
    - `id` string, required — The unique identifier for this user.
    - `type` 'user', required — The value will always be `user`.
    - `name` string — The display name of this user.
    - `login` string, email — The primary email address of this user.
  - `modified_by` object — The user who last modified this folder.
    - `id` string, required — The unique identifier for this user.
    - `type` 'user', required — The value will always be `user`.
    - `name` string — The display name of this user.
    - `login` string, email — The primary email address of this user.
  - `trashed_at` string, nullable — The time at which this folder was put in the trash - becomes `null` after restore.
  - `purged_at` string, nullable — The time at which this folder is expected to be purged from the trash - becomes `null` after restore.
  - `content_created_at` string, date-time, nullable — The date and time at which this folder was originally created.
  - `content_modified_at` string, date-time, nullable — The date and time at which this folder was last updated.
  - `owned_by` object — The user who owns this folder.
    - `id` string, required — The unique identifier for this user.
    - `type` 'user', required — The value will always be `user`.
    - `name` string — The display name of this user.
    - `login` string, email — The primary email address of this user.
  - `shared_link` string, nullable — The shared link for this file. This will be `null` if a folder had been trashed, even though the original shared link does become active again.
  - `folder_upload_email` string, nullable — The folder upload email for this folder. This will be `null` if a folder has been trashed, even though the original upload email does become active again.
  - `parent` object, nullable — The optional folder that this folder is located within. This value may be `null` for some folders such as the root folder or the trash folder.
    - `id` string, required — The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folders/123` the `folder_id` is `123`.
    - `etag` string, nullable — The HTTP `etag` of this folder. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the folder if (no) changes have happened.
    - `type` 'folder', required — The value will always be `folder`.
    - `sequence_id` string — A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource.
    - `name` string — The name of the folder.
  - `item_status` 'active' | 'trashed' | 'deleted' — Defines if this item has been deleted or not. * `active` when the item has is not in the trash, * `trashed` when the item has been moved to the trash but not deleted, * `deleted` when the item has been permanently deleted.

## Other responses

- `403` — Returns an error if the user does not have access to the folder the folder is being restored to, or the user does not have permission to restore folders from the trash.
- `404` — Returns an error if the folder is not in the trash.
- `409` — Returned an error if there is a folder with the same name in the destination folder. `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in process. The operation can be retried at a later point.
- `default` — An unexpected client error.

---

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