Sample - Box Platform API
POST/folders/{folder_id}

Restore a folder from the trash

Restores a folder that has been moved to the trash. Use name to optionally rename it and parent to provide a fallback destination when its original parent no longer exists; the operation temporarily locks the source, descendants, and destination folders.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

2 parameters · 2 body fields
folder_idstringrequired
The unique identifier of the folder to restore.
fieldsarray<string>optional
A comma-separated list of additional attributes to include in the response; when provided, standard fields are not returned unless you request them explicitly.

Optional restore settings for the trashed folder.

namestringoptional
An optional new name for the folder.
parentobjectoptional
An optional fallback parent folder to use if the original parent no longer exists.

5 status codes
201Returns the restored folder object.
idstringoptional
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`.
etagstringoptional
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.
typestringoptional
The value will always be `folder`.
Allowed:folder
sequence_idobjectoptional
namestringoptional
The name of the folder.
created_atstringoptional
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_atstringoptional
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.
descriptionobjectoptional
sizeintegeroptional
The folder size in bytes. Be careful parsing this integer as its value can get very large.
path_collectionobjectoptional
created_byobjectoptional
modified_byobjectoptional
trashed_atstringoptional
The time at which this folder was put in the trash - becomes `null` after restore.
purged_atstringoptional
The time at which this folder is expected to be purged from the trash - becomes `null` after restore.
content_created_atstringoptional
The date and time at which this folder was originally created.
content_modified_atstringoptional
The date and time at which this folder was last updated.
owned_byobjectoptional
shared_linkstringoptional
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_emailstringoptional
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.
parentobjectoptional
item_statusstringoptional
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.
Allowed:activetrasheddeleted
403Returned when you do not have access to the destination folder or do not have permission to restore folders from the trash.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
404Returned when the folder is not in the trash.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
409Returned when a folder with the same name exists in the destination folder or the source or destination folder is locked by another move, copy, delete, or restore operation.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultAn unexpected client error.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

A 403 is returned when you cannot access the destination folder or do not have permission to restore folders. A 404 is returned when the folder is not in the trash. A 409 is returned when the destination contains a folder with the same name or a source or destination folder is temporarily locked.