---
title: "Restore file"
method: POST
path: "/files/{file_id}"
tags: ["Trashed files"]
---

# Restore file

`POST /files/{file_id}`

Restores a file that has been moved to the trash.

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

## Path parameters

- `file_id` string, required

## Query parameters

- `fields` string[]

## Request body

- object
  - `name` string — An optional new name for the file.
  - `parent` object — Specifies an optional ID of a folder to restore the file 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 file to if the original location has been deleted.
    - `id` string — The ID of parent item.

## Response `201`

Returns a file object when the file has been restored.

- TrashFileRestored — Represents a file restored from the trash.
  - `id` string, required — 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`.
  - `etag` string, nullable — 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.
  - `type` 'file', required — The value will always be `file`.
  - `sequence_id` string, required — 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 file.
  - `sha1` string, digest, required — The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.
  - `file_version` object — The information about the current version of the file.
    - `id` string, required — The unique identifier that represent a file version.
    - `type` 'file_version', required — The value will always be `file_version`.
    - `sha1` string — The SHA1 hash of this version of the file.
  - `description` string, required — The optional description of this file.
  - `size` integer, required — The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow.
  - `path_collection` object, required — 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_at` string, date-time, required — The date and time when the file was created on Box.
  - `modified_at` string, date-time, required — The date and time when the file was last updated on Box.
  - `trashed_at` string, nullable — The time at which this file was put in the trash - becomes `null` after restore.
  - `purged_at` string, nullable — The time at which this file 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 file was originally created, which might be before it was uploaded to Box.
  - `content_modified_at` string, date-time, nullable — The date and time at which this file was last updated, which might be before it was uploaded to Box.
  - `created_by` object — The user who created this file.
    - `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, required — The user who last modified this file.
    - `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.
  - `owned_by` object, required — The user who owns this file.
    - `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 file had been trashed, even though the original shared link does become active again.
  - `parent` object, nullable — The folder that this file is located within.
    - `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', required — 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 file is being restored to, or the user does not have permission to restore files from the trash.
- `404` — Returns an error if the file is not in the trash.
- `409` — Returns an error if there is an file with the same name in the folder the file is being restored to.
- `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)