ContentSync Logo

Assets API

The assets API provides four different modes of access to your assets:

  • source: Provide the file as-is without setting additional disposition headers.

  • embed: Treat the file as embedded content. E.g., to display a PDF rather than downloading it.

  • download: Treat the file as an attachment that will trigger a download action by most browsers instead of displaying the file inline.

  • image: Only available for the image MIME type group. Allows additional parameters to resize and optimize images for different uses.

The URLs to all of these endpoints are provided per asset automatically when you query for asset details. For content assets, this can be found under entry.sys.assetEntry in the GraphQL API and under entry.assetEntry in the REST API.

The URLs will automatically use the Preview Assets or standard Assets API depending on the user permissions.

The asset URL will include certain metadata like the source image width and height within the URL as well as the version hash. This makes it easy for applications to request optimized, targeted versions of files and images and simplifies caching. The end of the URL will always be the filename provided by the asset to maximize compatibility with browsers and downloads.

Image API

Use the image API to provide optimized versions of your images for your current applications. You don’t have to configure Drupal image styles, etc., but rather request the image dynamically in the version you need for your application.

To use the image optimization API, you can simply add the parameters to the imageUrl.

If you’re using the GraphQL API, you can also request a URL with the parameters already set, for example:

Code
1
... {
2
  sys {
3
    assetEntry {
4
      thumbnail: imageUrl(urlOptions: {width: 100})
5
    }
6
  }
7
}

If you are using the GraphQL API, please use the options provided in the API. If you are appending the parameters to the URL directly, you can use:

  • width: Set the width of the image in pixels.

  • height: Set the height of the image in pixels.

  • format: Change the image format to one of:

    • webp

    • jpeg

    • png

    • gif

    • avif

    • svg

  • fit: When changing the size of an image:

    • contain 

    • cover (alias fill)

    • crop

    • Pad

  • background: When changing the size of an image, add this color to the background for missing areas.

  • gravity: When resizing an image, focus on this area. Can be one of:

    • auto: Use the focal point value from Drupal for the image.

    • (X/Y coordinates): E.g., 0.5x0.5 to focus on the center of the image.

  • quality: The quality for lossy types like JPEG.

    • An integer between 1 (worst, smallest) and 100 (best, largest).