Media library

The media library holds your app's images, videos and documents, each at a public URL. Products, variants, store locations and pages point at those URLs. Use these endpoints to find files, keep them organised, swap a file for a new version without breaking the places that use it, and clean up.

How the library works#

• A file has a key and a URL. The key is the file's path in your app's storage, such as 12-34/products/dog-food.jpg; the URL is where anyone can fetch it. Both stay the same for the life of the file.
• Folders are for you. A file's folder is where it is filed in the library. Moving or renaming a file changes only that, never its key or URL, so nothing that uses it breaks.
• Images are processed after upload. According to your app's upload preset, images are compressed, often converted to WebP, and resized into smaller copies called renditions, each with its own URL. This runs in the background shortly after the upload, so width, height, size and renditions fill in later. A converted file keeps its original extension in the key.
• Hidden files are kept out of the library's normal view, for example scans customers upload from the app. Lists leave them out unless you ask for them.
• Deleting is two steps. A deleted file goes to Trash and its URL keeps working. Purging removes it for good. Files left in Trash are purged automatically after 30 days, unless your app is set otherwise.
• Usage is tracked. Wherever a file's URL is stored, on a product, a variant, a store location or a page, we record it, so you can see what a change would affect.

The file object#

What the list endpoints return for each file.

Browse files#

curl -G "https://api.morffeus.com/api/v2/cdn/files" \
  -H "Authorization: Bearer $MORFFEUS_TOKEN" \
  -d "folder=products" -d "kind=image" \
  -d "noalt=true" -d "pageSize=50"

{
  "data": {
    "files": [
      {
        "id": 7731,
        "filename": "dog-food.jpg",
        "key": "12-34/products/dog-food.jpg",
        "url": "https://cdn.example.com/12-34/products/dog-food.jpg",
        "folder": "products",
        "size": 84210,
        "mime": "image/webp",
        "width": 1600,
        "height": 1600,
        "alt": null,
        "tags": [],
        "version": 1,
        "usage_count": 2,
        "hidden": false,
        "renditions": [
          {
            "label": "w800",
            "width": 800,
            "height": 800,
            "url": "https://cdn.example.com/12-34/products/[email protected]",
            …
          }
        ],
        …
      }
    ],
    "total_count": 138,
    "hidden_count": 0
  }
}

Edit, move and file#

curl -X PATCH "https://api.morffeus.com/api/v2/cdn/file" \
  -H "Authorization: Bearer $MORFFEUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 7731,
    "alt": "Dog food, 2 kg bag",
    "tags": ["dog", "food"]
  }'

{
  "errors": {
    "CdnFiles": ["API.CdnFiles.FileNotFound"]
  }
}

Replace a file#

curl -X POST "https://api.morffeus.com/api/v2/cdn/files/7731/replace" \
  -H "Authorization: Bearer $MORFFEUS_TOKEN" \
  -F "file=@dog-food_new.jpg" \
  -F "cache_strategy=version"

{
  "data": {
    "id": 7731,
    "key": "12-34/products/dog-food.jpg",
    "version": 2,
    …
  },
  "cache": {
    "strategy": "version",
    "url": "https://cdn.example.com/12-34/products/dog-food.jpg?v=2"
  }
}

Where a file is used#

{
  "data": [
    {
      "entity_type": "product",
      "entity_id": 48377,
      "field": "images",
      "label": "Dog food",
      "url": "https://cdn.example.com/12-34/products/dog-food.jpg",
      "total_count": 2
    },
    {
      "entity_type": "product_variant",
      "entity_id": 91120,
      "field": "image_url",
      …
    }
  ]
}

Delete, restore and purge#

curl -X DELETE -G "https://api.morffeus.com/api/v2/cdn" \
  -H "Authorization: Bearer $MORFFEUS_TOKEN" \
  --data-urlencode "file=12-34/products/dog_food_old.jpg"

{
  "data": { "message": "File deleted", "success": true }
}

{
  "errors": {
    "CdnFiles": ["API.CdnFiles.FileNotInTrash"]
  }
}

Images on products and locations#

Products, variants and store locations store image URLs. To use a library file, send its url as image_url in the product's or variant's images with POST /int/products. We store the URL as you send it and do not download it, so a URL from outside the library works too, but it is not tracked. A library URL counts as a usage of the file straight away.

Two more reads help here. GET /cdn_upload_presets lists your app's upload presets, with the output format, maximum width, quality and rendition widths each applies; the default one has is_default: true. GET /cdn/files/pdf-renders?name= finds PDFs whose pages were rendered as images, with the URL of each page.

Related#

• Products: where product and variant images are set.
• Locations: store locations and their images.
• Errors: the error envelope.