---
title: "Asset"
description: "Asset"
url: "https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/swift/reference/asset"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-09-14"
---

# Asset

## Asset

The Asset class represents media files (eg, images, videos, PDFs, audio, etc.) in your Contentstack repository. Use it to fetch a single asset by UID or to build an asset query.

## cachePolicy Property

The cachePolicy property defines the caching strategy for the asset request (network vs cache).

Name

Type

Required

Default

Description

cachePolicy

CachePolicy

No

.networkOnly

Defines the retrieval strategy manually set on the Asset instance to determine whether the request uses the network, cache, or both.

  

**CachePolicy values:**

Value

Description

networkOnly

Fetches data from the network and updates the cache with the results. This is the default policy.

cacheOnly

Returns data exclusively from the cache without initiating a network request.

cacheElseNetwork

Attempts to retrieve from the cache first; initiates a network call only if a cache miss or failure occurs.

networkElseCache

Prioritizes the network request; returns cached data only if the network call fails.

cacheThenNetwork

The completion handler is invoked twice: first with the cached result (response == .cache), then with the network result (response == .network). If a cache miss occurs, the first invocation returns a failure. Use the response parameter to identify which result is being processed.

  

**Example**

Assign a CachePolicy value to the Asset instance before calling fetch:

```
let stack = Contentstack.stack(apiKey: apiKey,
                              deliveryToken: deliveryToken,
                              environment: environment)
let asset = stack.asset(uid: assetUID)
asset.cachePolicy = .networkOnly   // or .cacheOnly, .cacheElseNetwork, etc.
asset.locale("en-us").fetch { (result: Result<AssetModel, Error>, response: ResponseType) in
    switch result {
    case .success(let model): // Model retrieved from API
    case .failure(let error): // Error message
    }
}
```

## locale

The locale method sets the locale code used when fetching the asset so the response is in the requested language.

```
Returns the same Asset instance with the locale set for the next request. Use it to chain more options (e.g., includeDimension()) or to call fetch.
let stack = Contentstack.stack(apiKey: apiKey,
                 deliveryToken: deliveryToken,
                 environment: environment)

     // To retrieve a single asset with a specific locale
     stack.asset(uid: assetUID).locale("en-us")
     .fetch { (result: Result<AssetModel, Error>, response: ResponseType) in
        switch result {
        case .success(let model): //Model retrieved from API
        case .failure(let error): //Error Message
        }
     }
```

## includeRelativeURL()

The includeRelativeURL() method includes the relative URLs of the assets in the response instead of absolute URLs.

```
The same Asset instance. The next fetch returns that asset with relative URLs including includeRelativeURL().
let stack = Contentstack.stack(apiKey: "<API_KEY>", deliveryToken: "<DELIVERY_TOKEN>", environment: "<ENVIRNOMENT>")
stack.asset(uid: "<ASSET_UID>").includeRelativeURL()
```

## includeFallback()

The includeFallback() method includes fallback published content when the requested locale has no published content.

```
The same Asset instance to enable chaining. The next fetch returns fallback locale content if the requested locale has none including includeFallback().
let stack = Contentstack.stack(apiKey: "<API_KEY>", deliveryToken: "<DELIVERY_TOKEN>", environment: "<ENVIRNOMENT>")
stack.asset(uid: "<ASSET_UID>").includeFallback()
```

## includeDimension()

The includeDimension() method includes the image's dimensions (height and width) in the response.

**Supported image types:** JPG, GIF, PNG, WebP, BMP, TIFF, SVG, PSD.

**Note:** For non-image asset types (e.g., PDF, ZIP, video, or audio), the API may omit dimension data or return null. In these cases, the SDK does not throw an error; the dimension property on the AssetModel remains available but is set to nil. It is recommended to verify asset.dimension != nil before accessing width or height properties to avoid processing errors.

```
Returns the asset instance with image dimensions (width and height) using includeDimension().
let stack = Contentstack.stack(apiKey: "<API_KEY>", deliveryToken: "<DELIVERY_TOKEN>", environment: "<ENVIRNOMENT>")
stack.asset(uid: "<ASSET_UID>").includeDimension()
```

## includeMetadata()

The includeMetadata() method includes asset metadata in the response body.

```
Returns extra asset metadata fields in addition to the standard asset data using includeMetadata().
let stack = Contentstack.stack(apiKey: "<API_KEY>", deliveryToken: "<DELIVERY_TOKEN>", environment: "<ENVIRNOMENT>")
stack.asset(uid: "<ASSET_UID>").includeMetadata()
```

## query()

The query() method returns an AssetQuery to retrieve multiple assets with filters and pagination.

Single Asset by UID: Use fetch.

*   Method: stack.asset(uid: "ASSET\_UID").fetch { … }.
*   Result: Returns one AssetModel.

Multiple Assets (Collection): Use query.

*   Method: stack.asset().query().
*   Result: Chain methods (e.g., where, limit) and call find { … } to get a ContentstackResponse<AssetModel>.

**Note:**

*   Calling query() on an asset initialized with a UID (e.g., stack.asset(uid: "x").query()) is valid but redundant.
*   For a single asset by UID, prefer stack.asset(uid: "ASSET\_UID").fetch().

```
An AssetQuery instance for method chaining.
let stack = Contentstack.stack(apiKey: "<API_KEY>", deliveryToken: "<DELIVERY_TOKEN>", environment: "<ENVIRNOMENT>")
stack.asset().query()
```

## fetch(completion:)

The fetch(completion:) call fetches the latest version of a specific Asset of a particular stack. The result is delivered to the completion handler.

```
No value. When the request finishes, the completion handler is invoked with Result<AssetModel, Error> and ResponseType.
Name
Type
Required
Default
Description
completion
(Result<AssetModel, Error>, ResponseType) -> Void
Yes
none
Defines the callback handler manually set in .fetch() to receive either the AssetModel results or an error once the request completes.
let stack = Contentstack.stack(apiKey: "<API_KEY>", deliveryToken: "<DELIVERY_TOKEN>", environment: "<ENVIRNOMENT>")
stack.asset(uid: "<ASSET_UID>")
.fetch { (result: Result<AssetModel, Error>, response: ResponseType) in
   switch result {
   case .success(let model):
   case .failure(let error):
   }
}
```

A handler which will be called on completion of the operation.

## Asset | Swift Delivery SDK | Contentstack

The Asset class in the Swift Delivery SDK represents media files like images, videos, and PDFs, letting you fetch a single asset by UID or build asset queries.