Assets

Assets collection

Assets represent files in a space. An asset can be any file, including an image, a video, an audio file, or PDF. Assets are usually attached to entries with links.

You can localize assets by providing separate files for each locale. Assets which are not localized provide a single file under the default locale.

Creating an asset requires three steps and API calls:

Create an asset.
Process an asset.
Publish an asset.

Get all assets of a space

To fetch specific assets use query search parameter.

Create an asset

When using this endpoint, an ID will be automatically generated for the created asset and returned with the response.

Published assets collection

Get all published assets of a space

Retrieves the published versions of all assets in a space.

Asset

Create or update an asset

Use this endpoint to create a new asset with a specified ID, or update an existing asset with its ID.

When updating an existing asset, you need to specify the last version you have of the asset with X-Contentful-Version.

Get an asset

Delete an asset

Deleting an asset will remove the current asset and all previously referenced files on the CDN. It can take up to 48 hours until these files will be made unavailable from (assets|images|downloads|videos).ctfassets.net.

Asset processing

To publish an asset, or to preview it within the Contentful web app (under the “Media” tab), you need to process it before. This step is fetching the image from the given location to Contentful’s system. This request might return before the asset processing is finished. The asset will have a fields.file.url for the respective locale if processing completed successfully.

Due to security considerations we forbid users to upload and process files with mime type text/html or text/javascript.

If you want to store HTML files in Contentful, please use application/octet-stream as the contentType. Keep in mind that these files will not be rendered by browsers by default.

Process an asset

Asset publishing

To adhere to best security practices and prevent security vulnerabilities, we only allow unicode’s general category letter characters which include almost all supported unicode language scripts (e.g: in regular expressions \p{Letter}), numerals (i.e: 0-9), dots (.), hyphens (-), and underscores (_) in file names. Any other character is replaced by an underscore.

Publish an asset

After publishing the asset, it will be available via the Content Delivery API. It will also be available from our asset domain assets.ctfassets.net as specified in the fields.file.url of the asset or if it is an image, it is available from images.ctfassets.net. In this case, you can use query parameters to define the image size, cropping parameters and other options. Find out more in our Images API reference. Published assets do not need any authentication on the Images or Assets API.

Unpublish an asset

Unpublishing will put the asset back into draft state.

Locale-based publishing

This feature is only available on the Premium/Enterprise pricing plans.

To publish or unpublish asset’s fields in certain locales, use the Asset publishing endpoints and pass in the locales in the payload as show in the examples below:

Publish asset locales:

{
  "add": {
    "fields": {
      "*": [
        "en-US",
        "de-DE"
      ]
    }
  }
}

Unpublish asset locales:

{
  "remove": {
    "fields": {
      "*": [
        "en-US",
        "de-DE"
      ]
    }
  }
}

Asset archiving

You can only archive an asset when it’s unpublished.

Archive an asset

Archiving an asset will remove the current asset and all previously referenced files on the CDN. It can take up to 48 hours until these files will be made unavailable from (assets|images|downloads|videos).ctfassets.net.

Unarchive an asset

Unarchiving an asset will bring back the asset, the current and all previously referenced files into a draft state. It can take up to an hour for the files to be available on the CDN again.