---
title: Manage Assets
description: Storyblok includes a digital asset management system for asset management and delivery.
url: https://www.storyblok.com/docs/concepts/assets
---

# Manage Assets

Storyblok includes a native [digital asset manager](https://www.storyblok.com/mp/asset-management-system) (DAM) for asset management and delivery. To upload and manage assets, open the space’s **Assets** library.

> [!NOTE]
> Learn how to use Storyblok’s asset manager in the [Assets manual](/docs/manuals/assets).

> [!TIP]
> Upload and manage assets programmatically using the Management API’s [assets endpoints](/docs/api/management/assets/).

## Shared asset libraries

> [!NOTE]
> Shared asset libraries are only available on specific Storyblok plans. Refer to the [pricing](https://www.storyblok.com/pricing) page for details.

Assets in Storyblok can be organized in a specific space or made available across multiple spaces via a shared asset library. Multiple libraries are supported, and each library can make its assets available to a specific set of spaces. A shared asset library is tied to a specific region. Shared assets are available only to spaces in the same region. Refer to the Assets [manual](/docs/manuals/assets) for more information.

## Asset CDN

Storyblok delivers all assets via AWS CloudFront [CDN](/docs/api/content-delivery/v2#caching). Assets are first served from the origin service, and subsequent calls are cached on the CDN to minimize latency. Learn more in the [caching concept](/docs/concepts/caching).

Images are served from different domains, depending on the [space’s region](/docs/manuals/spaces).

> [!TIP]
> To resolve potential CORS-related limitations, use the `a2` domains.

Ensure the project’s frontend references the correct domain when handling assets:

| Region | URL |
| --- | --- |
| United States | `https://a-us.storyblok.com`, `https://a2-us.storyblok.com` |
| Europe | `https://a.storyblok.com`, `https://a2.storyblok.com` |
| Australia | `https://a-ap.storyblok.com`, `https://a2-ap.storyblok.com` |
| Canada | `https://a-ca.storyblok.com` |
| China | `https://a.storyblokchina.cn` |

> [!NOTE]
> Asset URLs
> 
> URLs for shared and space assets share the same base URL but differ in structure. Note the differences between the two:
> 
> -   Space Asset URLs: `https://a.storyblok.com/f/`
> -   Shared Asset URLs: `https://a.storyblok.com/g/<org_id>`

## Custom assets domain

To set up a custom domain for assets, follow the tutorial for your cloud service:

[Set up a Custom Assets Domain Using Amazon CloudFront](https://www.storyblok.com/tp/set-up-a-custom-assets-domain-using-amazon-cloudfront)

[Set up a Custom Assets Domain Using Microsoft Azure](https://www.storyblok.com/tp/set-up-a-custom-assets-domain-using-microsoft-azure)

[Set up a Custom Assets Domain Using Google Cloud](https://www.storyblok.com/tp/set-up-a-custom-assets-domain-using-google-cloud)

## Image Service

Use Storyblok’s [Image Service](/docs/api/image-service) to modify files programmatically: change the file format, optimize the quality, resize, set a focal point, or apply various filters.

## Asset MIME types

The asset library supports the following MIME types:

-   **Image:** `image/x-png`, `image/png`, `image/gif`, `image/jpeg`, `image/avif`, `image/svg+xml`, `image/webp`
-   **Video:** `video/*`, `application/mp4`, `application/x-mpegurl`, `application/vnd.apple.mpegurl`, `audio/webm`
-   **Audio:** `audio/*`
-   **Text:** `application/msword`, `text/plain`, `application/pdf`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`

> [!WARNING]
> Spaces without payment info only accept assets with the `image/*` MIME type.
> 
> Unverified spaces accept assets of most MIME types, except `text/*` and `application/*`.

## Metadata fields

Metadata simplifies asset management and improves the site visitor’s experience. Storyblok’s DAM includes default fields—namely, alt text, title/caption, copyright, and source. Developers can extend these with custom fields that match the organization’s and project’s specific needs.

> [!NOTE]
> Custom metadata fields and translatable assets metadata may not be available on your plan. Check Storyblok’s [pricing](https://www.storyblok.com/pricing).

To manage default metadata fields and create custom fields, open **Settings** → **Assets Library**. Under **Custom metadata fields**, name the new field, choose the asset file type, select **Add**, and **Save**.

Custom metadata fields support regular expression (regex) validation similar to the standard [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/pattern) `pattern` [attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/pattern). Like their default counterparts, custom fields can also be set as **Required** and **Translatable**.

> [!TIP]
> Learn how to work with multiple languages in the [Internationalization concept](/docs/concepts/internationalization).

Both default and custom metadata fields can be managed programmatically via Storyblok’s APIs:

-   **Content Delivery API:** to retrieve an array of assets associated with stories in a space, use [the](/docs/api/content-delivery/v2/stories/retrieve-multiple-stories.html#:~:text=resolve_assets%20number) `resolve_assets` [query parameter](/docs/api/content-delivery/v2/stories/retrieve-multiple-stories.html#:~:text=resolve_assets%20number) of the `stories` endpoint.
-   **Management API:** to retrieve or update metadata fields of assets, use the [assets endpoint](/docs/api/management/assets). The asset object includes a `meta_data` [object](/docs/api/management/assets/the-asset-object#:~:text=to%20the%20public-,meta_data%20object,-Includes%20custom%20metadata) that lists all metadata fields of each file, both default and custom ones.

## Obtain image dimensions via the API

The example below demonstrates how to extract the width and height of an image from a Storyblok asset URL:

```javascript
const assetUrl = "//a.storyblok.com/f/51376/664x488/f4f9d1769c/visual-editor-features.webp";
const dimensions = {
  width: assetUrl.split("/")[5].split("x")[0],
  height: assetUrl.split("/")[5].split("x")[1],
};
console.log(dimensions);
```

This method only works with unmodified images. The asset URL doesn’t reflect changes in the following scenarios:

-   If a user resized the image using the [**Image Editor**](/docs/manuals/image-editor)
-   if a user replaced the image with a resized version using the [Replace Asset](/docs/apps/replace-asset) app

> [!NOTE]
> Deleted assets return a 403 or 404 [error message](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status). The Image Service returns a 502 for a transformed image whose original asset was deleted. To recover one or multiple files, follow the [Assets manual](/docs/manuals/assets#:~:text=The%20Deleted%20assets%20tab).

A more reliable way to track image dimensions is to use the Content Delivery API’s [stories endpoint](/docs/api/content-delivery/v2/stories/retrieve-a-single-story#:~:text=relations%20is%20reached.-,resolve_assets,-number). In the request, set `resolve_assets=1` to retrieve all assets associated with the story. The response now includes the `assets` array, where each object contains a `meta_data` object with a `size` key.

```json
"assets": [
    {
      "id": 17075319,
      "content_type": "image/webp",
      "content_length": 6333586,
      "created_at": "2025-08-21T08:17:24.429Z",
      "updated_at": "2025-08-21T08:18:02.522Z",
      "deleted_at": null,
      "alt": "",
      "title": "",
      "copyright": "",
      "focus": "",
      "s3_filename": "f/51376/664x488/f4f9d1769c/visual-editor-features.webp",
      "meta_data": {
        "size": "400x300"
      }
    }
  ]
```

It may take a few minutes for the `size` property to apply the updated image dimensions.

## Private assets

To temporarily or permanently hide assets from the library and restrict access to these files, mark them as private. Private assets are only accessible via the Content Delivery API with an [Asset type access token](/docs/concepts/access-tokens#content-delivery-api-access-tokens).

> [!TIP]
> Retrieve a [private asset’s URL](/docs/api/content-delivery/v2/assets/get-signed-url) using the Content Delivery API, or follow a tutorial on [how to serve gated content with Storyblok private assets](https://www.storyblok.com/tp/how-to-serve-gated-content-with-storyblok-private-assets).

The following example uses the [@storyblok/js](/docs/libraries/js/js-sdk) SDK to retrieve a private asset:

```javascript
import { apiPlugin, storyblokInit } from "@storyblok/js";

const { storyblokApi } = storyblokInit({
  accessToken: SPACE_TOKEN,
  use: [apiPlugin],
});

const getSignedUrl = async (filename) => {
  const response = await storyblokApi.get("cdn/assets/me", {
    filename: filename,
    token: ASSET_TOKEN,
  });

  return response.data.asset.signed_url;
};

const assetUrl = await getSignedUrl("https://a.storyblok.com/f/184738/2560x1946/d20c274998/earth.jpg");

document.querySelector("#app").innerHTML = `
  <img src="${assetUrl}" width="200">
`;
```

Learn how to manipulate private assets using the [Image Service](/docs/api/image-service/usage-with-protected-images).

## Troubleshoot assets

A request to an asset URL that returns a `403` status receives an access error from the storage provider:

```xml
<Error>
  <Code>AccessDenied</Code>
  <Message>Access Denied</Message>
</Error>
```

Two causes trigger this response:

-   **The asset is in the trash.** Deleting an asset revokes public access while the URL stays in the content. Install the [Trash bin app](/docs/apps/trash-bin) and restore the asset.
-   **The asset is private.** Private assets resolve only through a signed URL. Follow the instructions in the [Private assets](#private-assets) section above.

## Related resources

[Assets in the Management API](/docs/api/management/assets)

[Assets Manual](/docs/manuals/assets)

[Developer Concept: Traffic](/docs/concepts/traffic)

## Pagination

-   [Previous: Access Tokens](/docs/concepts/access-tokens)
-   [Next: Backups](/docs/concepts/backups)
