cURL

curl -i -X POST "https://api.box.com/2.0/files/12345/versions/current" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "type": "file_version",
       "id": "456456"
     }'

{
  "id": "12345",
  "type": "file_version",
  "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
  "name": "tigers.jpeg",
  "size": 629644,
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "modified_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "trashed_at": "2012-12-12T10:53:43-08:00",
  "trashed_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "restored_at": "2012-12-12T10:53:43-08:00",
  "restored_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "purged_at": "2012-12-12T10:53:43-08:00",
  "uploader_display_name": "Ellis Wiggins",
  "version_number": "1"
}

Endpoints

Promote file version

Promote a specific version of a file.

If previous versions exist, this method can be used to promote one of the older versions to the top of the version history.

This creates a new copy of the old version and puts it at the top of the versions history. The file will have the exact same contents as the older version, with the same hash digest, etag, and name as the original.

Other properties such as comments do not get updated to their former values.

Don’t use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar.

POST

files

{file_id}

versions

current

cURL

curl -i -X POST "https://api.box.com/2.0/files/12345/versions/current" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "type": "file_version",
       "id": "456456"
     }'

{
  "id": "12345",
  "type": "file_version",
  "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
  "name": "tigers.jpeg",
  "size": 629644,
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "modified_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "trashed_at": "2012-12-12T10:53:43-08:00",
  "trashed_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "restored_at": "2012-12-12T10:53:43-08:00",
  "restored_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "purged_at": "2012-12-12T10:53:43-08:00",
  "uploader_display_name": "Ellis Wiggins",
  "version_number": "1"
}

This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

file_id

string

required

The unique identifier that represents 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.

Query Parameters

fields

string[]

A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response.

Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.

Body

application/json

The file version to promote.

string

The file version ID.

Example:

"11446498"

type

enum<string>

The type to promote.

Available options:

file_version

Example:

"file_version"

Response

Returns a newly created file version object.

A full representation of a file version, as can be returned from any file version API endpoints by default.

string

required

The unique identifier that represent a file version.

Example:

"12345"

type

enum<string>

required

The value will always be file_version.

Available options:

file_version

Example:

"file_version"

sha1

string

The SHA1 hash of this version of the file.

Example:

"134b65991ed521fcfe4724b7d814ab8ded5185dc"

name

string

The name of the file version.

Example:

"tigers.jpeg"

size

integer<int64>

Size of the file version in bytes.

Example:

629644

created_at

string<date-time>

When the file version object was created.

Example:

"2012-12-12T10:53:43-08:00"

modified_at

string<date-time>

When the file version object was last updated.

Example:

"2012-12-12T10:53:43-08:00"

modified_by

User (Mini) · object

The user who last updated the file version.

Show child attributes

trashed_at

string<date-time> | null

When the file version object was trashed.

Example:

"2012-12-12T10:53:43-08:00"

trashed_by

User (Mini) · object

The user who trashed the file version.

Show child attributes

restored_at

string<date-time> | null

When the file version was restored from the trash.

Example:

"2012-12-12T10:53:43-08:00"

restored_by

User (Mini) · object

The user who restored the file version from the trash.

Show child attributes

purged_at

string<date-time> | null

When the file version object will be permanently deleted.

Example:

"2012-12-12T10:53:43-08:00"

uploader_display_name

string

The display name of the user that uploaded the file. In most cases this is the name of the user logged in at the time of the upload.

If the file was uploaded using a File Request form that requires the user to provide an email address, this field is populated with that email address. If an email address was not required in the File Request form, this field is set to return a value of File Request.

In all other anonymous cases where no email was provided this field will default to a value of Someone.

Example:

"Ellis Wiggins"

version_number

string

The version number of this file version.

Example:

"1"

List all file versions

Remove file version

⌘I