Box Developer Documentation
Log in

Request Desired Representation

Guides Representations Request Desired Representation
Edit this page

Required Guides

Request Desired Representation

To select a specific representation call the GET /files/:id endpoint with a x-rep-hints-header defining the required representation format.

curl https://api.box.com/2.0/files/123?fields=representations \
    -H "x-rep-hints: [pdf]" \
    -H "authorization: Bearer ACCESS_TOKEN"

Multiple dimensions

Some formats will require the dimensions to be passed in to select a specific size. This can be achieved by appending the dimensions to the header.

curl https://api.box.com/2.0/files/123?fields=representations \
    -H "x-rep-hints: [jpg?dimensions=94x94]" \
    -H "authorization: Bearer ACCESS_TOKEN"

Multiple representations

Multiple representations can be fetched by chaining the different types in the x-rep-hints-header.

curl https://api.box.com/2.0/files/123?fields=representations \
    -H "x-rep-hints: [pdf][jpg?dimensions=94x94]" \
    -H "authorization: Bearer ACCESS_TOKEN"

API Response

This API call will result in one or more representations with a url_template value that includes a {+asset_path} value.

{
  "etag": "1",
  "id": "123",
  "representations": {
    "entries": [
      {
        "content": {
          "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/pdf/content/{+asset_path}"
        },
        "info": {
          "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/pdf"
        },
        "properties": {},
        "representation": "pdf",
        "status": {
          "state": "success"
        }
      }
    ]
  },
  "type": "file"
}

The url_template in this response is an opaque URL. This URL format might change over time and no assumptions should be made about its format except for the presence of the {+asset_path} variable.