Skip to main content
A thumbnail is a small image, either as .png or as .jpg that can be used in an application as a representation of the file, for example as a placeholder for a link that downloads or previews the file. All thumbnail representations except 1024x1024 and 2048x2048 PNGs are generated upon uploading the source file to Box.
An deprecated way to get a thumbnail for a file is using the .

​
The process

To get a thumbnail representation follow the following steps
  • by passing the x-rep-hints-header for the desired thumbnail format and size, for example [jpg?dimensions=32x32].
  • by calling the url_template, replacing the {+asset_path} with an empty string.
Sometimes the thumbnail can not be created directly. Instead, the API will return a HTTP 202 with a location response header. The location is for a temporary image that can be used while the thumbnail is being generated.
A retry-after response header is also provided to present you with an estimated amount of seconds before retrying this endpoint.

​
Examples

The following a some example x-rep-hints-header values

​
Supported file sizes

The following formats and sizes of thumbnails are available. Some restrictions apply to the sizes marked as *.

​
File size restrictions

​
JPEG 2048x2048

The JPEG 2048x2048 size is only available when the original file is a JPEG. We recommend either requesting a PNG or both a PNG and a JPEG for this dimension.

​
Video files

JPEG 2048x2048, PNG 2048x20148 and PNG 1024x1024 representations are not available for video files.

​
Original file size

Thumbnails are not scaled up. If the original file size of the file uploaded to Box is smaller than the representation dimensions, the resulting thumbnail is capped at the size of the original file.

​
Supported file types

At this time the following file types are supported.
For document file types the representation returned will be a placeholder icon and not an actual thumbnail.
Last modified on March 19, 2026