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

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.

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

2 parameters · 2 body fields
file_idstringrequired
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`.
fieldsarray<string>optional
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.
idstringoptional
The file version ID.
typestringoptional
The type to promote.
Allowed:file_version

2 status codes
201Returns a newly created file version object.
idstringrequired
The unique identifier that represent a file version.
typestringrequired
The value will always be `file_version`.
Allowed:file_version
sha1stringoptional
The SHA1 hash of this version of the file.
namestringoptional
The name of the file version.
sizeintegeroptional
Size of the file version in bytes.
created_atstringoptional
When the file version object was created.
modified_atstringoptional
When the file version object was last updated.
modified_byobjectoptional
trashed_atstringoptional
When the file version object was trashed.
trashed_byobjectoptional
restored_atstringoptional
When the file version was restored from the trash.
restored_byobjectoptional
purged_atstringoptional
When the file version object will be permanently deleted.
uploader_display_nameobjectoptional
version_numberstringoptional
The version number of this file version.
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

Any other status is an error: An unexpected client error.