Media & uploads
Upload images, how they're served, and self-hosting rules.
Images (product photos, content images, section backgrounds) are uploaded to the platform and served from a CDN-cached path.
Uploading
- API — the media upload mutations (multipart) return a hosted URL.
- MCP —
upload_imageandupload_product_imageaccept a URL or data URI and re-host the asset, returning a durable/storage/...URL.
Serving
Uploaded media is served from <host>/storage/... with long cache lifetimes.
Reference these URLs in products, content records, and theme settings.
No hotlinking
The MCP write tools automatically re-host any third-party image URL to
/storage — a dead source URL fails the write. Always use hosted URLs so
storefronts don't show broken images.
Stock photos
For real imagery during a build, the pexels-stock-images
playbook fetches license-free photos and re-hosts them via upload_image.