Sample - Box Platform API
POST/files/{file_id}

Restore a file from the trash

Restores a file that has been moved to the trash. Use the optional request body to provide a new name or a fallback parent folder when the original location is no longer available.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 parameters · 2 body fields
file_idstringrequired
The unique identifier of the file to restore from the trash.
fieldsarray<string>optional
A comma-separated list of attributes to include in the restored file response.

Optional restoration settings for the file, including a replacement name and fallback parent folder.

namestringoptional
An optional new name for the file.
parentobjectoptional
An optional fallback parent folder, identified by its `id`, used when the original folder no longer exists.

5 status codes
201Returns the restored file object, including its identifier, name, location, version information, and restored status.
idstringrequired
The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.
etagstringoptional
The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened.
typestringrequired
The value will always be `file`.
Allowed:file
sequence_idobjectrequired
namestringoptional
The name of the file.
sha1stringrequired
The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.
file_versionobjectoptional
descriptionstringrequired
The optional description of this file.
sizeintegerrequired
The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow.
path_collectionobjectrequired
created_atstringrequired
The date and time when the file was created on Box.
modified_atstringrequired
The date and time when the file was last updated on Box.
trashed_atstringoptional
The time at which this file was put in the trash - becomes `null` after restore.
purged_atstringoptional
The time at which this file is expected to be purged from the trash - becomes `null` after restore.
content_created_atstringoptional
The date and time at which this file was originally created, which might be before it was uploaded to Box.
content_modified_atstringoptional
The date and time at which this file was last updated, which might be before it was uploaded to Box.
created_byobjectoptional
modified_byobjectrequired
owned_byobjectrequired
shared_linkstringoptional
The shared link for this file. This will be `null` if a file had been trashed, even though the original shared link does become active again.
parentobjectoptional
item_statusstringrequired
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 the authenticated user lacks permission to restore the file or access the destination folder.
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 file 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 file with the same name already exists in the destination folder.
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.
defaultReturned when an unexpected client error occurs.
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 the authenticated user cannot restore the file or cannot access its destination folder. A 404 is returned when the file is not in the trash, and a 409 is returned when another file with the same name already exists in the destination folder. The file_id must identify the file to restore, and parent can specify a fallback folder.