Product photos and gallery tools

Human workflow

1. 1Open Products and edit the product. Upload images or choose Find images on a product page.
2. 2Select the original photos you want in the gallery and save. Up to ten owned PNG/JPEG/GIF/WebP images can be associated with one product.
3. 3In a campaign, select saved product images as attachments where appropriate. Gallery storage and email sending are separate actions; adding a photo never sends email.

Agent workflow

1. 1Call get_product_gallery with the product ID or exact name. It returns ordered image IDs, filenames, sizes, SHA-256 checksums and updatedAt.
2. 2For original local photos, call upload_product_image with filename and canonical base64 file bytes. Optionally provide expectedSha256 from the original file. A mismatch prevents upload.
3. 3For website photos, call discover_product_images with the public page URL, then import_product_image for each selected ticket before its 15-minute expiry. Internal/private destinations are blocked.
4. 4Call set_product_gallery with imageIds and mode APPEND (default), REMOVE or REPLACE. REPLACE requires expectedUpdatedAt from the latest gallery read. Use update_product imageIds only when intentionally replacing the full gallery.
5. 5Read get_product_gallery again to confirm the filenames, IDs and checksums. Use the returned IDs as attachmentIds if an email should contain those photos. Do not write directly to private storage or put storage keys/public URLs into imageIds.

API, security and connector refresh

The same operations are in /docs/api, /docs/api.md and /api/v1/openapi.json: GET/PUT /api/v1/products/{product}/gallery and POST /api/v1/product-images/upload, /discover and /import. Gallery reads need read scope; uploads and changes need write scope. Only owned products and images are accepted. Gallery changes verify stored file size and checksum. Files remain private.

If your agent says gallery tools are missing after a release, refresh/reconnect its ColdPegion MCP connection so it reloads tools/list. It should use the official operations rather than bypassing the product API.