# 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. ## Discussion 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](/documentation/AppStoreConnectAPI/uploading-and-managing-image-assets), [Uploading and managing video assets](/documentation/AppStoreConnectAPI/uploading-and-managing-video-assets), and [Placing assets on your App Store surfaces](/documentation/AppStoreConnectAPI/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](/documentation/AppStoreConnectAPI/migrating-to-the-app-asset-library). ## Understand the model The asset library is built from a small set of resources: - Asset library: The per-app container that holds every reusable asset. Each app has exactly one library, reachable through the app’s `assetLibrary` relationship. For more information, see [App Asset Libraries](/documentation/AppStoreConnectAPI/app-asset-libraries). - Image and video assets: The reusable media you upload. You upload each [`AppAssetLibraryImage`](/documentation/AppStoreConnectAPI/AppAssetLibraryImage) or [`AppAssetLibraryVideo`](/documentation/AppStoreConnectAPI/AppAssetLibraryVideo) once, and App Store Connect processes it once. The asset then lives in the library independently of where it appears. For more information, see [App Asset Library images](/documentation/AppStoreConnectAPI/app-asset-library-images) and [App Asset Library videos](/documentation/AppStoreConnectAPI/app-asset-library-videos). - Placements: A placement ([`AppAssetLibraryPlacement`](/documentation/AppStoreConnectAPI/AppAssetLibraryPlacement)) positions one asset on one App Store surface: an App Store version localization, a custom product page localization, an in-app event localization, or an App Store version experiment treatment localization. For more information, see [App Asset Library placements](/documentation/AppStoreConnectAPI/app-asset-library-placements). - Ordering requests: A single request that sets the display order of placements within one localization and placement group, such as the order of screenshots. For more information, see [App Asset Library placement ordering requests](/documentation/AppStoreConnectAPI/app-asset-library-placement-ordering-requests). - Reference data: A machine-readable catalog of valid specifications: dimensions, aspect ratios, file formats, placement groups, and per-placement limits. Query it instead of hard-coding requirements. For more information, see [App Asset Library reference data](/documentation/AppStoreConnectAPI/app-asset-library-reference-data). ## 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 type ([`AppAssetLibraryPlacementType`](/documentation/AppStoreConnectAPI/AppAssetLibraryPlacementType)): Names the kind of slot: `APP_SCREENSHOT`, `APP_PREVIEW`, `PRODUCT_PAGE_HEADER_ASSET`, `EVENT_CARD_ASSET`, and so on. - Placement group: Narrows that slot to a family of devices. Group identifiers are strings such as `IPHONE_DYNAMIC_ISLAND_LARGE_PROFILE` or `MAC_PROFILE`, and the full list comes from the reference data. Each group maps to a platform ([`AppAssetLibraryPlacementPlatform`](/documentation/AppStoreConnectAPI/AppAssetLibraryPlacementPlatform)) and a display class ([`AppAssetLibraryDisplayClass`](/documentation/AppStoreConnectAPI/AppAssetLibraryDisplayClass)). - Specification: Describes the file itself: exact pixel dimensions, aspect ratio, formats, and maximum size. You don’t choose a specification; App Store Connect matches your uploaded file to one during processing and reports it back as the asset’s `specId`. 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](/documentation/AppStoreConnectAPI/discovering-asset-specifications). ## Follow the end-to-end workflow A typical integration moves through these stages: 1. **Find the library.** Read the app’s asset library with `GET /v1/apps/{id}/assetLibrary` ([`Read related asset library`](/documentation/AppStoreConnectAPI/GET-v1-apps-_id_-assetLibrary)) and note its `id`. You relate every asset you upload to this library. 2. **Check the specifications.** Query the reference data with `GET /v1/appAssetLibraryRefData` ([`List app asset library ref data`](/documentation/AppStoreConnectAPI/GET-v1-appAssetLibraryRefData)) to learn the dimensions, formats, placement groups, and limits that apply to the surfaces you’re targeting. 3. **Upload your assets.** Reserve, upload, and commit each image or video, then wait for processing. For more information, see [Uploading and managing image assets](/documentation/AppStoreConnectAPI/uploading-and-managing-image-assets) and [Uploading and managing video assets](/documentation/AppStoreConnectAPI/uploading-and-managing-video-assets). 4. **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](/documentation/AppStoreConnectAPI/placing-assets-on-your-app-store-surfaces). 5. **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`](/documentation/AppStoreConnectAPI/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: - `FAILED`: Processing didn’t succeed. Read `stateDetails` for the reason. - `REJECTED`: App Review declined the asset. - `ARCHIVED`: You retired an approved asset from active use. Re-fetch an asset at any time to read its current `state` and `stateDetails`. Placements track their own `state` ([`AppAssetLibraryPlacementState`](/documentation/AppStoreConnectAPI/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`](/documentation/AppStoreConnectAPI/AppAssetLibraryAssetCategory)): - `APP_SCREENSHOTS_AND_PREVIEWS`: Screenshots and app previews for your product pages. - `CREATIVE_ASSETS`: Other marketing media, such as in-app event artwork and product page header assets. 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`](/documentation/AppStoreConnectAPI/UserRole) and [Program Roles](https://developer.apple.com/support/roles). If you’re new to the API, see [Creating API Keys for App Store Connect API](/documentation/AppStoreConnectAPI/creating-api-keys-for-app-store-connect-api), [Generating Tokens for API Requests](/documentation/AppStoreConnectAPI/generating-tokens-for-api-requests), and [Identifying Rate Limits](/documentation/AppStoreConnectAPI/identifying-rate-limits). ## Topics ### Uploading assets [Uploading and managing image assets](/documentation/AppStoreConnectAPI/uploading-and-managing-image-assets) Reserve, upload, and commit an image to your app’s asset library, then update, archive, or delete it. [Uploading and managing video assets](/documentation/AppStoreConnectAPI/uploading-and-managing-video-assets) Reserve, upload, and commit a video to your app’s asset library, set its preview frame, then update, archive, or delete it. ### Placing assets [Placing assets on your App Store surfaces](/documentation/AppStoreConnectAPI/placing-assets-on-your-app-store-surfaces) Create placements that position library assets on App Store surfaces, then set their display order within a localization. [Discovering asset specifications](/documentation/AppStoreConnectAPI/discovering-asset-specifications) Query the asset library reference data to learn the valid dimensions, formats, placement groups, and limits before you upload. ### Migrating existing media [Migrating to the App Asset Library](/documentation/AppStoreConnectAPI/migrating-to-the-app-asset-library) Move your screenshots, app previews, and in-app event media from the deprecated set-based resources to the asset library. --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)