---
title: Understanding the App Asset Library
framework: App Store Connect API
role: collectionGroup
path: appstoreconnectapi/understanding-the-app-asset-library
---

# Understanding the App Asset Library

Upload an image or video once, then reuse it across your app’s App Store surfaces with per-surface placements.

## Overview

Overview The App Asset Library gives your app a single, shared collection of marketing and product media. Instead of uploading the same screenshot or app preview separately to every App Store version, custom product page, and in-app event, you upload each asset once into the library and then create placements that position it on specific surfaces. One asset can back many placements at the same time. This article explains how the pieces fit together. For the step-by-step workflows, see Uploading and managing image assets, Uploading and managing video assets, and Placing assets on your App Store surfaces. For a comparison of the App Asset Library and the previous approach, see Migrating to the App Asset Library. Understand the model The asset library is built from a small set of resources: Learn the vocabulary of a placement Three values describe where an asset appears. You supply the first two when you create a placement, and App Store Connect provides the third: Placement group identifiers and their limits come from the reference data rather than an enumeration, so you need to read them at runtime. For more information, see Discovering asset specifications. Follow the end-to-end workflow A typical integration moves through these stages: Find the library. Read the app’s asset library with GET /v1/apps/{id}/assetLibrary (Read related asset library) and note its id. You relate every asset you upload to this library. Check the specifications. Query the reference data with GET /v1/appAssetLibraryRefData (List app asset library ref data) to learn the dimensions, formats, placement groups, and limits that apply to the surfaces you’re targeting. Upload your assets. Reserve, upload, and commit each image or video, then wait for processing. For more information, see Uploading and managing image assets and Uploading and managing video assets. Place the assets. Create placements that link each asset to a target localization, then set their order within each placement group. For more information, see Placing assets on your App Store surfaces. Submit for review. Placements travel through App Review as part of their parent surface. A placement’s state reflects the review state of that parent. Track asset state Every image and video reports a state (AppAssetLibraryAssetState). Reserving, uploading, and processing an asset moves it through: AWAITING_UPLOAD → UPLOAD_COMPLETE → PREPARE_FOR_SUBMISSION After the asset reaches PREPARE_FOR_SUBMISSION, it’s processed and you can place it. Submitting the parent surface for review advances the asset through READY_FOR_REVIEW, WAITING_FOR_REVIEW, IN_REVIEW, ACCEPTED, and APPROVED. Three states sit outside that progression: Re-fetch an asset at any time to read its current state and stateDetails. Placements track their own state (AppAssetLibraryPlacementState), which mirrors the review state of the parent surface, from ASSET_PROCESSING through PARENT_APPROVED. Choose an asset category When you create an asset, you assign it a category (AppAssetLibraryAssetCategory): The category determines the placement types for which an asset is eligible. Each placement type in the reference data lists the categories it accepts in acceptsAssetCategories, and creating a placement with a category that doesn’t match that list returns an error. Review roles and access To manage the asset library with the App Store Connect API, you need one of the following user roles: ACCOUNT_HOLDER ADMIN APP_MANAGER For the full list of App Store Connect user roles, see UserRole and Program Roles. If you’re new to the API, see Creating API Keys for App Store Connect API, Generating Tokens for API Requests, and Identifying Rate Limits.

## Topics

### Uploading assets

- [Uploading and managing image assets](appstoreconnectapi/uploading-and-managing-image-assets.md)
- [Uploading and managing video assets](appstoreconnectapi/uploading-and-managing-video-assets.md)

### Placing assets

- [Placing assets on your App Store surfaces](appstoreconnectapi/placing-assets-on-your-app-store-surfaces.md)
- [Discovering asset specifications](appstoreconnectapi/discovering-asset-specifications.md)

### Migrating existing media

- [Migrating to the App Asset Library](appstoreconnectapi/migrating-to-the-app-asset-library.md)

## See Also

### Essentials

- [Uploading and managing image assets](appstoreconnectapi/uploading-and-managing-image-assets.md)
- [Uploading and managing video assets](appstoreconnectapi/uploading-and-managing-video-assets.md)
- [Placing assets on your App Store surfaces](appstoreconnectapi/placing-assets-on-your-app-store-surfaces.md)
- [Discovering asset specifications](appstoreconnectapi/discovering-asset-specifications.md)
- [Migrating to the App Asset Library](appstoreconnectapi/migrating-to-the-app-asset-library.md)