How to Migrate App Store Connect API 4.5.1 Screenshot Endpoints? 2026

The key change is not simply a new upload endpoint. Apple’s migration guidance directs you toward App Asset Library resources and placements. Model the asset itself separately from where it appears. That distinction matters when one image or video is reused across a version localization, a Custom Product Page, or an experiment.

Apple’s 4.5.1 release notes mark four named legacy resource types as deprecated: App Screenshot Sets, App Screenshots, App Preview Sets, and App Previews. They also identify some in-app event media resources as deprecated. The notes recommend moving to library images, videos, and placements, but do not give an immediate shutdown date for the old resources. Check Apple’s release notes before treating an old call as unavailable.

The mapping is conceptual, not a one-to-one ID conversion. An old screenshot set represents a grouping in the legacy model. Do not assume that the same set can be copied unchanged into a new placement. Apple describes library resources and the act of placing assets on App Store surfaces as separate parts of the workflow.

Migration risk: If your current database stores a screenshot set ID as both the file identity and its destination, split those responsibilities before changing API calls. Otherwise, a reused image can be uploaded more than once, or a placement can point to the wrong page.

Which screenshot and preview resources are deprecated?

Treat the four named resource types as deprecated, not as confirmed unavailable. Search your code, API client wrappers, scheduled jobs, and release scripts for those resource names and for the relationships they use. Also inspect the code paths managing in-app event media; the release notes identify some of those resources as deprecated, so verify each resource against the current Apple documentation rather than assuming all event media has the same migration path.

For each match, record the operation and its purpose: listing, creating, updating, deleting, or checking state. A resource name found in a generated client is not enough to prove that production uses it. Trace actual requests and their response IDs through a representative release log.

Do not set a forced cutover date based only on the word “deprecated.” The published notes establish the status and recommended direction, but do not announce an immediate stop date for the old resources. Keep a compatibility path only if you can monitor it and have a defined removal plan.

How should a legacy screenshot set map to App Asset Library?

Create an explicit migration record for each destination. At minimum, track the app, page or surface, localization, asset type, source asset, intended order, new library asset ID, and placement ID. Keep the old resource IDs as audit references, but do not use them as substitutes for new asset and placement relationships.

For a shared image, create one library identity only when the content is genuinely the same. Then create and verify the required placements independently. If a localized page needs different copy embedded in the image, that is a different asset even when the visual layout is otherwise shared. Apple’s App Asset Library overview and its placement documentation describe the resources and relationships; use them to verify the current model rather than inventing equivalences from legacy IDs.

A library asset answers “which media file is this?” A placement answers “where should this media appear?” Keep those questions separate in your data model, deployment logs, and recovery procedure.

For a version localization, a Custom Product Page, or an experiment, preserve the destination as an explicit part of the mapping. One uploaded image does not prove that every intended destination is configured. Similarly, a successful placement operation does not establish that the correct localization or sequence was selected. Apple’s placement guide is the reference for associating assets with App Store surfaces.

How do in-app event screenshots and videos fit?

Handle event media as its own migration scenario. Identify which legacy event resources your pipeline calls, then map each event localization and media type to the new library asset and its destination relationship. Do not infer that a screenshot placement for a version localization is interchangeable with an in-app event placement.

Deletion and replacement need particular care. Before removing an asset, query or inspect your own mapping records for other destinations that use it. A shared asset may still be required by another page or localization. If the API’s current relationships do not make reuse obvious to your application, keep an explicit reference list so a cleanup job cannot delete a still-used file.

How should you handle new display categories and specifications?

Do not treat a specification discovered today as a permanent constant in your uploader. Apple provides reference data for discovering asset specifications. The API 4.5.1 release notes also add an iPhone Duo display category. Read the current returned display type, dimensions, and constraints from the relevant reference data, then validate the output against those values. See Apple’s asset specification discovery documentation and screenshot specifications.

This is a useful boundary for automation: the discovery response can guide validation, but it should not replace destination-specific checks. Store the specification response used for a release alongside the generated asset metadata. When the response changes, your validation can identify whether the source image needs regeneration rather than silently relying on an old hard-coded rule.

Operational note: Keep specification discovery and screenshot generation separate in your pipeline. If a specification changes, you want the validation stage to fail with a clear reason, not a late upload or placement step to obscure the cause.

An API migration does not automatically require a new build node. First identify which stage generates the media and which stage only calls App Store Connect. If screenshots are created by a macOS-only tool or by a simulator workflow, that generation stage needs a compatible Mac environment. If your pipeline receives already-generated media and only performs API operations, the migration itself does not prove that the API client must move to a Mac.

Keep those responsibilities observable. A CI record should connect the source build or test run to the generated files, the upload request, the returned asset identity, the processing result, and the final placement check. Apple’s uploading assets documentation describes the upload workflow; use its current instructions when implementing the request sequence.

How can you confirm upload completion and correct display?

Do not equate an accepted API response with a finished asset. Treat upload, processing, and placement as separate states in your release logic. A successful request is evidence that the request was accepted; it is not by itself proof that processing completed or that the intended store page displays the right media.

Use this sequence in an isolated release path:

• Inventory calls and persisted IDs. Record which legacy endpoints and relationships are used, and identify the associated page, localization, event, or preview.
• Build a destination map. For every media item, record its type, target surface, localization, intended order, and whether it is reused elsewhere.
• Discover current specifications. Query the applicable reference data and validate generated dimensions and constraints against the returned values.
• Generate or select the media artifact. Preserve a stable internal artifact reference so a retry can be associated with the same source file.
• Reserve or create the library asset and upload it. Follow Apple’s current upload procedure, and retain request results and returned IDs.
• Poll or inspect the processing state. Keep the asset in a non-ready state until the API reports the relevant completed state; do not advance the release based solely on upload acceptance.
• Create the destination placement. Verify that the placement references the intended asset and destination.
• Check the rendered result. Use a test application or non-production release path to confirm the correct page, localization, media, and order.
• Compare and retain evidence. Save the old-to-new mapping, response logs, processing status, placement IDs, and visual verification record before enabling production traffic.

This sequence makes a critical distinction visible: upload accepted, processing complete, and correctly displayed are different release gates. Your pipeline should fail at the gate that lacks evidence, rather than reporting a generic “screenshot upload succeeded.”

Run old and new paths in parallel only where the test environment makes the comparison safe. Use an isolated application or non-production release path. Compare the asset-to-destination relationship, localization, ordering, and rendered output. Retain enough information to retry a failed upload or remove an incorrect placement without deleting a shared library asset.

Decision branches for cutover

• If the pipeline generates screenshots or previews on macOS, keep that generation stage on a validated Mac runner. Change the API resource mapping separately, then verify that the generated artifact, upload, processing, and placement all pass.
• If the pipeline only uploads pre-generated media, migrate the API client and validation logic without replacing the build node solely because the endpoint model changed.
• If one asset serves multiple pages or localizations, preserve a distinct placement record for each destination and verify each one before cutover.
• If processing or page rendering cannot be verified, keep production on the known release path and investigate the missing evidence. An accepted upload response is not a go-live signal.
• If old and new results differ, pause rollout, retain both sets of IDs and logs, and restore the last known-good path. Do not delete legacy references until the new destination mapping is proven.
• If your team cannot isolate test destinations, postpone production writes until you can verify placement without risking a live page or event.

For a controlled rollout, start with a small, representative media path that includes the same localization and reuse patterns as production. Confirm that retries are traceable and that cleanup handles shared assets safely. Then expand the migration by destination, not by blindly replacing every legacy endpoint in one release. Keep a release owner responsible for the comparison record and the rollback decision.

A useful release record includes the API version used, the source artifact reference, the new asset and placement IDs, the processing state, the target destination, and the page verification result. Check the API version and deprecated resource list against Apple’s release notes, and confirm the relationship model against its migration guidance. Do not infer an old-resource retirement date that Apple has not published.

If the screenshot-generation stage truly requires macOS, an existing local Mac pool may be the simplest choice when it is already maintained and has spare capacity. A dedicated purchase can be a poor fit for a short migration or intermittent release work because you still own hardware provisioning, maintenance, and idle capacity. A remote Mac can avoid that purchase and give the team a real macOS environment, but it adds remote access and environment-management considerations. If you are comparing that option, review CALMVPS Mac CI pricing and the available CALMVPS Mac environments. If media is generated elsewhere and only the API integration changes, finish the migration validation first; do not rent or replace a build node just to accommodate a resource-model change.