Assets Endpoints

Upload, query, retrieve, and delete Apple Maps creative assets.

Overview

You use assets to build creative for your campaigns. Uploading new assets through this API is available only for Apple Maps brands, but querying and retrieving assets covers both App Store apps and Apple Maps brands. Each asset carries metadata about its type, dimensions, eligibility status, and any rejection reasons.

Use the Endpoints

The Assets API provides four endpoints for uploading, querying, retrieving, and deleting assets:

Method	Path	Description
`POST`	`/v1/assets/upload`	Upload Asset uploads a new creative asset for use in Apple Maps campaigns.
`POST`	`/v1/assets/query`	Query Assets retrieves assets matching the specified filters.
`GET`	`/v1/assets/{id}`	Get Asset By Id retrieves a single asset by its ID.
`DELETE`	`/v1/assets/{id}`	Delete Asset By Id soft-deletes an uploaded asset by its ID.

Identify the Asset Type

Every asset has an assetType field, which identifies the kind of media it contains. Currently, IMAGE is the only supported value, and it represents a static image file. See ImageType for the full list of supported formats.

Upload Assets

Assets enter the system through a single upload method. Send a multipart form to POST /v1/assets/upload (Upload Asset) containing the binary image file (file), promotedObjectId, and promotedObjectType: BUSINESS_BRAND. The endpoint accepts PNG, JPG, and HEIC formats.

This endpoint only supports asset uploads for Apple Maps (BUSINESS_BRAND) assets, and it doesn’t accept any other value for promotedObjectType. The uploaded asset belongs to the ad account identified by the X-AP-Context header and becomes part of that account’s asset library.

After upload, the asset begins processing. Poll using Get Asset until the eligibility.status indicates the asset is ready before referencing it in a creative.

Query Assets

To find assets, use POST /v1/assets/query (Query Assets) with the following filterable fields:

Filterable Field	Operators	Description
`promotedObjectId`	`EQUALS`, `IN`	Filter by the promoted object’s identifier (`adamId` for an App Store app, `brandId` for an Apple Maps brand).
`promotedObjectType`	`EQUALS`	Filter by promoted object type: `APPSTORE_APP` or `BUSINESS_BRAND`.
`providerAssetId`	`EQUALS`, `IN`	Filter by the provider-assigned asset identifier.
`assetType`	`EQUALS`, `IN`	Filter by asset type: `IMAGE`.

Review the Shared Response Fields

Every asset response includes the following fields:

Field	Description
`id`	Unique asset identifier (UUID). Read-only.
`name`	User-facing asset name or description.
`assetType`	The media type of the asset. See Assettype.
`providerAssetId`	Asset identifier assigned by the provider system.
`promotedObjectId`	Identifier of the promoted object (`adamId` for an app, `brandId` for a brand).
`promotedObjectType`	The type of the promoted object: `APPSTORE_APP` or `BUSINESS_BRAND`.
`providerAssetMetadata`	Provider-specific metadata. Structure varies by provider type.
`assetDetails`	Type-specific media metadata. For `IMAGE` assets, contains Assetimage fields, including `format` (see Imagetype) and `orientation` (see Orientation).
`parentAssetId`	Identifier of the parent asset if this asset is a variant.
`variantIds`	Identifiers for asset variants (for example, different sizes or localizations).
`eligibility`	Eligibility data. See Asseteligibility for the `status` field (see Asseteligibilitystatus) and the `blockedGroups`/`allowedGroups` constraint fields (see Assetconstraintgroup). Always returned unless excluded via a `fields` projection parameter.
`creationTime`	Timestamp when the asset was created (ISO 8601). Read-only.
`modificationTime`	Timestamp of the last modification (ISO 8601). Read-only.

Delete Assets

You can only delete assets you’ve uploaded. A call to Get Asset still returns a deleted asset and marks it with deleted: true, but Query Assets excludes deleted assets from results by default.