My Apps

    Request Desired Representation

    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.