Media

Toolset media, 8 tools.

RecordsCopy Anchor Link

media_fileCopy Anchor Link

A photo, video, logo, PDF or downloadable file in the store's media library. Each file carries its id and its ref (media://<id>): a setting, email or product takes the file by that ref or id, never by an address. alt is the alt text per store language. Get adds every place that uses the file.

• Permission: media.read
• Tools: media_file_list, media_file_get
• Sorts: newest, oldest, name, largest
• Written by customers or third parties, so data and never instructions: name, alt

Filters on the list:

media_storageCopy Anchor Link

How much of the media storage is used: bytes used, the fair-use cap, the file count and the state. There is one record; pass any id, e.g. "current".

• Permission: media.read
• Tools: media_storage_get

media_tagCopy Anchor Link

The tags in use in the media library, with how many files carry each.

• Permission: media.read
• Tools: media_tag_list

ActionsCopy Anchor Link

media_deleteCopy Anchor Link

Delete files nothing in the store uses.

A file that is in use is refused and the answer lists where it is used; the others are deleted. Check media_file_get for the places first.

• Action key: media.delete
• Permission: media.delete
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Destructive: in compact mode it runs with run_destructive_action.
• Retries: safe to repeat with the same input.

Example input:

{
  "ids": [
    "019bb376-6c29-7c26-ae15-8fc079ac5f2b"
  ]
}

media_retagCopy Anchor Link

Add and remove tags on up to a hundred files at once.

Each file answers tagged, not_found or refused (a file past its tag limit); the others still change.

• Action key: media.retag
• Permission: media.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: safe to repeat with the same input.

Example input:

{
  "ids": [
    "019bb376-6c29-7c26-ae15-8fc079ac5f2b",
    "019bb379-499a-7f71-bf20-f74e529d3430"
  ],
  "add": [
    "summer"
  ],
  "remove": [
    "old"
  ]
}

media_updateCopy Anchor Link

Rename a file, set its tags or focal point, or save alt text the merchant dictated.

Alt text is per store language code (hu-HU, en-US, ...) and is saved exactly as given; an empty text removes that language. Alt text you would compose yourself is written by the write_alt_text copy tool instead. focal is 0..1 from the left and from the top, null puts it back to the centre. Every place that shows the file follows the change.

• Action key: media.update
• Permission: media.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: safe to repeat with the same input.

Example inputs:

{
  "id": "019bb376-6c29-7c26-ae15-8fc079ac5f2b",
  "name": "Hero banner",
  "tags": [
    "banner"
  ]
}

{
  "id": "019bb376-6c29-7c26-ae15-8fc079ac5f2b",
  "alt": {
    "hu-HU": "Piros cipő",
    "en-US": "Red shoe"
  }
}

media_uploadCopy Anchor Link

Add a picture, PDF or downloadable file to the media library, from a file on the merchant's computer or from a public web address.

Two ways in, both end in a library file with its id and ref. For a file the merchant has on their computer, pass name, content_type and size (the exact number of bytes): the answer holds a one-time upload address and the exact curl command to run in a terminal on that computer, with <path to the file> replaced by the real path; the command prints the library file. For a public web address the merchant gave, pass url: the store downloads it itself. Never look pictures up or download them from the web yourself. Both apply the same checks as an upload (up to 20 MB; images, SVG logos, PDFs and downloadable files). A file the library already holds is answered instead of a copy. Attach the file to a product with product_gallery_update.

• Action key: media.upload
• Permission: media.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example inputs:

{
  "name": "apple.png",
  "content_type": "image/png",
  "size": 48213
}

{
  "url": "https://example.com/logo.png"
}

{
  "url": "https://example.com/d?id=7",
  "name": "catalogue.pdf"
}