> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/_mcp/server.

## 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:

1. Create an asset.
2. Process an asset.
3. Publish an asset.

[Get all assets of a space](/references/content-management-api/assets/get-all-assets-of-a-space)

To fetch specific assets use [query search parameter](/references/content-management-api/search-parameters).

[Create an asset](/references/content-management-api/assets/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](/references/content-management-api/assets/get-all-published-assets-of-a-space)

Retrieves the published versions of all assets in a space.

## Asset

[Create or update an asset](/references/content-management-api/assets/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.

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

[Get an asset](/references/content-management-api/assets/get-an-asset)

[Delete an asset](/references/content-management-api/assets/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](/references/content-management-api/assets/process-an-asset)

## Asset publishing

> **Info**
>
> 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](/references/content-management-api/assets/publish-an-asset)

After publishing the asset, it will be available via the [Content Delivery API](/references/content-delivery-api/overview). 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](/references/images-api/overview) reference. Published assets do not need any authentication on the Images or Assets API.

[Unpublish an asset](/references/content-management-api/assets/unpublish-an-asset)

Unpublishing will put the asset back into draft state.

## Locale-based publishing

> **Info**
>
> This feature is only available on the [Premium/Enterprise pricing plans](https://www.contentful.com/pricing/).

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](/references/content-management-api/assets/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](/references/content-management-api/assets/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.


## API Docs

- Assets [Get all assets of a space](https://contentful.com/developers/docs/references/content-management-api/assets/get-all-assets-of-a-space.md)
- Assets [Create an asset](https://contentful.com/developers/docs/references/content-management-api/assets/create-an-asset.md)
- Assets [Get all published assets of a space](https://contentful.com/developers/docs/references/content-management-api/assets/get-all-published-assets-of-a-space.md)
- Assets [Get an asset](https://contentful.com/developers/docs/references/content-management-api/assets/get-an-asset.md)
- Assets [Create or update an asset](https://contentful.com/developers/docs/references/content-management-api/assets/create-or-update-an-asset.md)
- Assets [Delete an asset](https://contentful.com/developers/docs/references/content-management-api/assets/delete-an-asset.md)
- Assets [Process an asset](https://contentful.com/developers/docs/references/content-management-api/assets/process-an-asset.md)
- Assets [Publish an asset](https://contentful.com/developers/docs/references/content-management-api/assets/publish-an-asset.md)
- Assets [Unpublish an asset](https://contentful.com/developers/docs/references/content-management-api/assets/unpublish-an-asset.md)
- Assets [Archive an asset](https://contentful.com/developers/docs/references/content-management-api/assets/archive-an-asset.md)
- Assets [Unarchive an asset](https://contentful.com/developers/docs/references/content-management-api/assets/unarchive-an-asset.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://contentful.com/developers/docs/openapi.json)
- [OpenAPI YAML](https://contentful.com/developers/docs/openapi.yaml)