Peak PIMDevelopers

Catalog

Media

Media files are first-class catalog entities: the same canonical-plus-store-version model and the same four reads as products. Products, variants, and collections reference them by id through their media_ids, in gallery order.

List media files

GET/api/v1/mediapim:read

One cursor page of the account's media files, ordered oldest change first. Media files are named by their filename, so title carries the filename.

Query parameters

ParameterTypeDescription
limitintegerRows per page. Default 50, maximum 250; a value above the maximum is clamped and a non-numeric value falls back to the default.
cursorstringThe next_cursor of the previous page. Opaque — do not build or parse one. A cursor from a different list is rejected with validation_failed.
updated_sinceRFC3339 date-timeOnly media files whose own canonical record changed at or after this time. Store-version edits do not widen it. A non-RFC3339 value is rejected with validation_failed.
statusenumPublish-state filter: never_published, pending, published, failed.
searchstringFree-text match on the media file's filename, tags, or alt text.

Response

The uniform list-item shape: id, type (here media), title (the filename), draft_revision, pending_publish, last_publish_status, and store_ids, with next_cursor as the paging handle. 

# Find files by name or alt text
curl -s "https://api.peak-pim.com/api/v1/media?search=trail-runner&limit=250" \
  -H "Authorization: Bearer pk_live_..."
{
  "data": [
    {
      "id": "1f2e3d4c-5b6a-4798-8172-635a4b3c2d1e",
      "type": "media",
      "title": "trail-runner-2-hero.jpg",
      "draft_revision": 2,
      "pending_publish": false,
      "last_publish_status": "published",
      "store_ids": ["9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30"]
    }
  ],
  "next_cursor": null
}

Get a media file

GET/api/v1/media/{id}pim:read

One media file's canonical values and its per-store publish state. An unknown id — including another account's — answers 404 not_found.

FieldTypeDescription
id, type, title—type is media; title carries the filename.
attributesarrayThe canonical values every store inherits, as {key, value, type} triples (all strings).
draft_revisionintegerThe optimistic-concurrency handle a later write sends back to prove it read the current state.
pending_publish, last_publish_status—As on the list row.
stores[]arrayPublish state per store: store_id, store_domain, pending_publish, last_publish_status. Publish state only — the store's values live on the store subresources below.
 
{
  "id": "1f2e3d4c-5b6a-4798-8172-635a4b3c2d1e",
  "type": "media",
  "title": "trail-runner-2-hero.jpg",
  "attributes": [
    { "key": "alt", "value": "Trail Runner 2 in black, side view", "type": "single_line_text_field" }
  ],
  "draft_revision": 2,
  "pending_publish": false,
  "last_publish_status": "published",
  "stores": [
    {
      "store_id": "9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30",
      "store_domain": "acme.myshopify.com",
      "pending_publish": false,
      "last_publish_status": "published"
    }
  ]
}
Media files carry no media_ids.

media_ids is how other entities reference their media, in gallery order — it is absent on media files themselves. To find where a file is used, walk products, variants, and collections and match their media_ids.

List a media file's store versions

GET/api/v1/media/{id}/storespim:read

Every store version of the media file. Bounded by the account's stores, so the whole list is returned and next_cursor is always null. Each item carries store_id, store_domain, attributes, pending_publish, and last_publish_status. 

{
  "data": [
    {
      "store_id": "9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30",
      "store_domain": "acme.myshopify.com",
      "attributes": [
        { "key": "alt", "value": "Trail Runner 2 en noir, vue de profil", "type": "single_line_text_field" }
      ],
      "pending_publish": false,
      "last_publish_status": "published"
    }
  ],
  "next_cursor": null
}

Get one store's version

GET/api/v1/media/{id}/stores/{store_id}pim:read

One store's version of the media file: the values that store publishes, which may differ from every other store's — a localized alt text, for instance. store_id comes from GET /api/v1/stores. A media file with no version on the requested store answers 404 not_found. 

curl -s "https://api.peak-pim.com/api/v1/media/1f2e3d4c-5b6a-4798-8172-635a4b3c2d1e/stores/9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30" \
  -H "Authorization: Bearer pk_live_..."

Media has no further subresources — no translations, sales-channels, or drops endpoints of its own. Where media meets the rest of the catalog: