Read an app asset library ref data

GET/asset-reference-data/{assetReferenceDataId}

Proposed · Extended read design · Adapter not implemented

Request

Routes are relative to your connection. Use a facade API key; the service manages Apple authentication.

BASE='https://asc.example.com/v1/connections/conn_example'

curl --fail-with-body "$BASE/asset-reference-data/asset_reference_data_123" \
  -H "Authorization: Bearer $ASC_FACADE_KEY"

const base = "https://asc.example.com/v1/connections/conn_example";
const response = await fetch(`${base}/asset-reference-data/asset_reference_data_123`, {
  headers: { Authorization: `Bearer ${process.env.ASC_FACADE_KEY}` }
});

const body = await response.json();
if (!response.ok) {
  throw new Error(body.error?.message ?? `HTTP ${response.status}`);
}
console.log(body);

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

base = "https://asc.example.com/v1/connections/conn_example"
request = Request(
    f"{base}/asset-reference-data/asset_reference_data_123",
    headers={"Authorization": f"Bearer {os.environ['ASC_FACADE_KEY']}"},
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    detail = json.load(error)
    raise RuntimeError(detail["error"]["message"]) from error

asc.example.com is a placeholder for your deployment. Examples use fictional IDs.

Path parameters

Name	Type	Description
assetReferenceDataIdRequired	`string`	The selected resource’s ID.

Response

One flat object for the selected resource.

{
  "id": "app_asset_library_ref_datum_123",
  "features": [
    {
      "featureId": "APP_STORE_VERSIONS",
      "placementPolicies": [
        {
          "placementType": "APP_SCREENSHOT",
          "groupLimits": []
        }
      ]
    }
  ],
  "placementProfileGroups": [
    {
      "placementProfileGroupId": "placement_profile_group_123",
      "platform": "IPHONE_APP_STORE",
      "displayClassId": "DEFAULT"
    }
  ],
  "imageSpecs": [
    {
      "specId": "spec_123",
      "shortName": "short_name_example",
      "dimensions": {
        "minWidth": 1,
        "maxWidth": 1,
        "minHeight": 1,
        "maxHeight": 1
      },
      "aspectRatio": "aspect_ratio_example",
      "compatiblePlacementTypes": [
        "APP_SCREENSHOT"
      ],
      "alphaAllowed": false
    }
  ],
  "videoSpecs": [
    {
      "specId": "spec_123",
      "shortName": "short_name_example",
      "dimensions": {
        "minWidth": 1,
        "maxWidth": 1,
        "minHeight": 1,
        "maxHeight": 1
      },
      "aspectRatio": "aspect_ratio_example",
      "compatiblePlacementTypes": [
        "APP_SCREENSHOT"
      ],
      "frameRates": [
        {
          "minFps": 1,
          "maxFps": 1
        }
      ]
    }
  ],
  "placementTypes": [
    {
      "placementTypeId": "APP_SCREENSHOT",
      "acceptsAssetCategories": [
        "CREATIVE_ASSETS"
      ],
      "specMappings": [
        {
          "placementGroupId": "placement_group_123",
          "specs": []
        }
      ]
    }
  ]
}

Illustrative response. Optional read fields may be absent or null; unknown enum values are preserved.

Response fields

Name	Type	Description
id	`string`	Apple’s resource ID. Keep this string unchanged when addressing a resource.
features	`object[]`	The features value reported by Apple for this resource.
placementProfileGroups	`object[]`	The placement profile groups value reported by Apple for this resource.
imageSpecs	`object[]`	The image specs value reported by Apple for this resource.
videoSpecs	`object[]`	The video specs value reported by Apple for this resource.
placementTypes	`object[]`	The placement types value reported by Apple for this resource.
displayClasses	`object[]`	The display classes value reported by Apple for this resource.

features fields

Name	Type	Description
featureIdOptional	`string`	The ID of the selected feature. Values `APP_STORE_VERSIONS`, `CUSTOM_PRODUCT_PAGES`, `PRODUCT_PAGE_OPTIMIZATIONS`, `IN_APP_EVENTS`, `IN_APP_PURCHASES`, `SUBSCRIPTIONS`, `RETENTION_MESSAGING`, `GAME_CENTER`, `APP_CLIPS`, `APPLE_ADS`
placementPoliciesOptional	`object[]`	The placement policies value reported by Apple for this resource.

features.placementPolicies fields

Name	Type	Description
placementTypeOptional	`string`	The placement type value reported by Apple for this resource. Values `APP_SCREENSHOT`, `IMESSAGE_APP_SCREENSHOT`, `APP_PREVIEW`, `PRODUCT_PAGE_HEADER_ASSET`, `APP_STORE_SEARCH_RESULTS_ASSET`, `SEARCH_RESULTS_ADS_ASSET`, `TODAY_TAB_ADS_ASSET`, `EVENT_CARD_ASSET`, `EVENT_DETAILS_PAGE_ASSET`, `RETENTION_MESSAGE_ASSET`
groupLimitsOptional	`object[]`	The group limits value reported by Apple for this resource.

features.placementPolicies.groupLimits fields

Name	Type	Description
groupIdsOptional	`string[]`	The group ids value reported by Apple for this resource.
maxCountOptional	`integer`	The max count value reported by Apple for this resource.

placementProfileGroups fields

Name	Type	Description
placementProfileGroupIdOptional	`string`	The ID of the selected placement profile group.
platformOptional	`string`	Apple’s platform value, preserved without renaming. Values `IPHONE_APP_STORE`, `IPAD_APP_STORE`, `WATCH_APP_STORE`, `IMESSAGE_APP_STORE`, `VISION_PRO_APP_STORE`, `MAC_APP_STORE`, `TV_APP_STORE`, `ANY`
displayClassIdOptional	`string`	The ID of the selected display class. Values `DEFAULT`, `WATCH_ULTRA`, `WATCH_SERIES_10`, `WATCH_SERIES_7`, `WATCH_SERIES_4`, `WATCH_SERIES_3`, `IPHONE_DUO`, `IPHONE_DYNAMIC_ISLAND_LARGE_DISPLAY`, `IPHONE_DYNAMIC_ISLAND_MEDIUM_DISPLAY`, `IPHONE_FACE_ID_LARGE_DISPLAY`, `IPHONE_FACE_ID_MEDIUM_DISPLAY`, `IPHONE_HOME_BUTTON_LARGE_DISPLAY`, `IPHONE_HOME_BUTTON_MEDIUM_DISPLAY`, `IPHONE_HOME_BUTTON_40_DISPLAY`, `IPHONE_HOME_BUTTON_35_DISPLAY`, `IPAD_13_DISPLAY`, `IPAD_11_DISPLAY`, `IPAD_129_DISPLAY`, `IPAD_105_DISPLAY`, `IPAD_97_DISPLAY`

imageSpecs fields

Name	Type	Description
specIdOptional	`string`	The ID of the selected spec.
shortNameOptional	`string`	The short name value reported by Apple for this resource.
dimensionsOptional	`object`	Plain identifiers for the entities represented by these measurements.
aspectRatioOptional	`string`	The aspect ratio value reported by Apple for this resource.
compatiblePlacementTypesOptional	`string[]`	The compatible placement types value reported by Apple for this resource. Values `APP_SCREENSHOT`, `IMESSAGE_APP_SCREENSHOT`, `APP_PREVIEW`, `PRODUCT_PAGE_HEADER_ASSET`, `APP_STORE_SEARCH_RESULTS_ASSET`, `SEARCH_RESULTS_ADS_ASSET`, `TODAY_TAB_ADS_ASSET`, `EVENT_CARD_ASSET`, `EVENT_DETAILS_PAGE_ASSET`, `RETENTION_MESSAGE_ASSET`
alphaAllowedOptional	`boolean`	Whether Apple marks this resource as alpha allowed.
fileExtensionsOptional	`string[]`	The file extensions value reported by Apple for this resource.
maxFileSizeOptional	`integer · int64`	The max file size value reported by Apple for this resource.
mimeTypesOptional	`string[]`	The mime types value reported by Apple for this resource.
universalAssetOptional	`boolean`	Whether Apple marks this resource as universal asset.

imageSpecs.dimensions fields

Name	Type	Description
minWidthOptional	`integer`	The min width value reported by Apple for this resource.
maxWidthOptional	`integer`	The max width value reported by Apple for this resource.
minHeightOptional	`integer`	The min height value reported by Apple for this resource.
maxHeightOptional	`integer`	The max height value reported by Apple for this resource.

videoSpecs fields

Name	Type	Description
specIdOptional	`string`	The ID of the selected spec.
shortNameOptional	`string`	The short name value reported by Apple for this resource.
dimensionsOptional	`object`	Plain identifiers for the entities represented by these measurements.
aspectRatioOptional	`string`	The aspect ratio value reported by Apple for this resource.
compatiblePlacementTypesOptional	`string[]`	The compatible placement types value reported by Apple for this resource. Values `APP_SCREENSHOT`, `IMESSAGE_APP_SCREENSHOT`, `APP_PREVIEW`, `PRODUCT_PAGE_HEADER_ASSET`, `APP_STORE_SEARCH_RESULTS_ASSET`, `SEARCH_RESULTS_ADS_ASSET`, `TODAY_TAB_ADS_ASSET`, `EVENT_CARD_ASSET`, `EVENT_DETAILS_PAGE_ASSET`, `RETENTION_MESSAGE_ASSET`
frameRatesOptional	`object[]`	The frame rates value reported by Apple for this resource.
durationOptional	`object`	The duration value reported by Apple for this resource.
audioRequiredOptional	`boolean`	Whether Apple marks this resource as audio required.
fileExtensionsOptional	`string[]`	The file extensions value reported by Apple for this resource.
maxFileSizeOptional	`integer · int64`	The max file size value reported by Apple for this resource.
mimeTypesOptional	`string[]`	The mime types value reported by Apple for this resource.
universalAssetOptional	`boolean`	Whether Apple marks this resource as universal asset.

videoSpecs.dimensions fields

Name	Type	Description
minWidthOptional	`integer`	The min width value reported by Apple for this resource.
maxWidthOptional	`integer`	The max width value reported by Apple for this resource.
minHeightOptional	`integer`	The min height value reported by Apple for this resource.
maxHeightOptional	`integer`	The max height value reported by Apple for this resource.

videoSpecs.frameRates fields

Name	Type	Description
minFpsOptional	`integer`	The min fps value reported by Apple for this resource.
maxFpsOptional	`integer`	The max fps value reported by Apple for this resource.

videoSpecs.duration fields

Name	Type	Description
minOptional	`string · duration`	The min value reported by Apple for this resource.
maxOptional	`string · duration`	The max value reported by Apple for this resource.

placementTypes fields

Name	Type	Description
placementTypeIdOptional	`string`	The ID of the selected placement type. Values `APP_SCREENSHOT`, `IMESSAGE_APP_SCREENSHOT`, `APP_PREVIEW`, `PRODUCT_PAGE_HEADER_ASSET`, `APP_STORE_SEARCH_RESULTS_ASSET`, `SEARCH_RESULTS_ADS_ASSET`, `TODAY_TAB_ADS_ASSET`, `EVENT_CARD_ASSET`, `EVENT_DETAILS_PAGE_ASSET`, `RETENTION_MESSAGE_ASSET`
acceptsAssetCategoriesOptional	`string[]`	The accepts asset categories value reported by Apple for this resource. Values `CREATIVE_ASSETS`, `APP_SCREENSHOTS_AND_PREVIEWS`
specMappingsOptional	`object[]`	The spec mappings value reported by Apple for this resource.

placementTypes.specMappings fields

Name	Type	Description
placementGroupIdOptional	`string`	The ID of the selected placement group.
specsOptional	`string[]`	The specs value reported by Apple for this resource.

displayClasses fields

Name	Type	Description
displayClassIdOptional	`string`	The ID of the selected display class. Values `DEFAULT`, `WATCH_ULTRA`, `WATCH_SERIES_10`, `WATCH_SERIES_7`, `WATCH_SERIES_4`, `WATCH_SERIES_3`, `IPHONE_DUO`, `IPHONE_DYNAMIC_ISLAND_LARGE_DISPLAY`, `IPHONE_DYNAMIC_ISLAND_MEDIUM_DISPLAY`, `IPHONE_FACE_ID_LARGE_DISPLAY`, `IPHONE_FACE_ID_MEDIUM_DISPLAY`, `IPHONE_HOME_BUTTON_LARGE_DISPLAY`, `IPHONE_HOME_BUTTON_MEDIUM_DISPLAY`, `IPHONE_HOME_BUTTON_40_DISPLAY`, `IPHONE_HOME_BUTTON_35_DISPLAY`, `IPAD_13_DISPLAY`, `IPAD_11_DISPLAY`, `IPAD_129_DISPLAY`, `IPAD_105_DISPLAY`, `IPAD_97_DISPLAY`
deviceFamilyOptional	`string`	The device family value reported by Apple for this resource. Values `IPHONE`, `IPAD`, `APPLE_TV`, `APPLE_WATCH`, `MAC`, `VISION`
screenDimensionsOptional	`string[]`	The screen dimensions value reported by Apple for this resource.

Behavior

A nested resource must belong to the selected parent and the configured connection. The adapter validates ownership before returning data.

Errors

HTTP	Type	Description
400	`invalid_query`	Unsupported filter, sort, limit, or cursor.
401	`unauthorized`	Missing or invalid facade API key.
403	`forbidden / upstream_forbidden`	The caller or configured Apple key cannot read this resource.
404	`resource_not_found`	The requested resource, parent, or exact locale is absent or outside the caller’s scope.
429	`rate_limited`	A facade or Apple rate limit was reached. Respect Retry-After when returned.
502–504	`upstream error`	Apple authentication, response parsing, availability, or timeout failure; this is not an empty result.

Apple mapping

Upstream route and translation

The adapter calls GET /v1/appAssetLibraryRefData/{id}. Read Apple’s original endpoint ↗

Flatten Apple’s attributes into each resource object. Expose supplied singleton linkage as IDs, with no automatic relationship traversal. Read access does not make these fields writable.

Reviewed 2026-10-14 · OpenAPI 4.5.1