Customizing media URLs

Understand ButterCMS CDN URLs, set up custom URL redirects, and implement image transformations for media assets.

CDN & performance

All stored files in your application are available over the ButterCMS CDN, making it fast for your customers to download those assets as needed.

CDN benefits

• Global Distribution - Content served from edge locations worldwide
• Automatic Caching - Reduced load times for repeat visits
• High Availability - Reliable image delivery
• SSL/HTTPS - Secure image serving

CDN URL structure

https://cdn.buttercms.com/[file-identifier]

Example:

https://cdn.buttercms.com/Lvv0MCF0QhCoKLSuEJzD

Understanding CDN URLs

All files you upload to your ButterCMS account will have a ButterCMS CDN URL. Files in the Media Library are assigned a random CDN URL slug so that each asset has its own unique URL.

Example URLs

Type	Example
ButterCMS CDN URL	https://cdn.buttercms.com/Cw5z1qzSq5qtVMCbUDwQ
Your desired URL	https://mywebsite.com/HeadlessCMSvsTraditionalCMS.pdf

A URL on your site (e.g. https://mywebsite.com/HeadlessCMSvsTraditionalCMS.pdf) cannot link to a file in ButterCMS (e.g. https://cdn.buttercms.com/Cw5z1qzSq5qtVMCbUDwQ) since that asset resides on your domain. If you want to redirect a URL to an asset stored in your ButterCMS media library, you’ll need to set up a URL route in your web application that is hardcoded to load the asset from ButterCMS.

Setting up custom URL redirects

If you want to set up multiple redirects for ButterCMS media assets, follow these steps:

Step 1: create a resources Collection

Create a “Resources” Collection in ButterCMS with:

• A Name short text field
• A Resource media field

Example Collection Structure

Field Name	Field Type	Purpose
Name	Short Text	URL-friendly slug for the resource
Resource	Media	The actual file to serve

Step 2: add a route in your application

Create a route that matches your desired URL pattern, for example:

mywebsite.com/files/<resource-name>/

Step 3: query the Collection

Look up the resource by slug (or name) in your Resources collection.

// Example: Fetching resource from collection
const butter = require('buttercms')('your-api-key');

async function getResource(resourceName) {
  const response = await butter.content.retrieve(['resources'], {
    'fields.name': resourceName
  });
  return response.data.data.resources[0];
}

// In your route handler
app.get('/files/:resourceName', async (req, res) => {
  const resource = await getResource(req.params.resourceName);
  res.redirect(resource.resource); // Redirects to CDN URL
});

Step 4: proxy or redirect to the asset

Redirect users to the CDN URL (recommended), or proxy the response through your app if you need to add headers or access controls.

Image URL transformations

ButterCMS integrates with Filestack’s Image API, allowing you to transform images by modifying the URL. This gives you powerful optimization capabilities without changing the original file.

URL structure

Processing tasks can be added to any CDN URL. Tasks follow this structure:

https://cdn.buttercms.com/TASK=option:value/FILE_ID

Multiple tasks can be chained by separating them with forward slashes:

https://cdn.buttercms.com/TASK1=option:value/TASK2=option:value/FILE_ID

Common transformations

Task	Example	Description
resize	resize=height:300	Resize to 300px height
resize	resize=width:800	Resize to 800px width
resize	resize=width:800,height:600	Resize to specific dimensions
crop	crop=dim:[x,y,width,height]	Crop to specific area
rotate	rotate=deg:90	Rotate by degrees
flip	flip	Flip image vertically
flop	flop	Flip image horizontally

To preserve aspect ratio, specify only width or height (for example, resize=width:800). If you set both width and height, the image is resized to those exact dimensions.

Examples

Original URL:

https://cdn.buttercms.com/Lvv0MCF0QhCoKLSuEJzD

Resize to 300px height:

https://cdn.buttercms.com/resize=height:300/Lvv0MCF0QhCoKLSuEJzD

Resize to 800px width:

https://cdn.buttercms.com/resize=width:800/Lvv0MCF0QhCoKLSuEJzD

Multiple transformations:

https://cdn.buttercms.com/resize=width:800/rotate=deg:90/Lvv0MCF0QhCoKLSuEJzD

Using URL transformations creates a new optimized version of the image on the CDN, improving page load times without modifying your original file.

For more advanced image transformations, refer to the Filestack Processing API documentation.

Best practices

Cache Transformed Images

URL transformations are cached on the CDN, so subsequent requests are fast

Responsive Images

Use URL parameters to serve different image sizes for different screen sizes

Original Backup

Your original files are always preserved; transformations create new versions

Descriptive Names

Use SEO-friendly slugs in your Resources collection for readable URLs