Product Media

Manage product media assets, ordering, and deletions.

Endpoints

Method	Path	Description
GET	/v1/products/:id/media	List media items assigned to a product.
POST	/v1/products/:id/media	Add a media item (direct URL or gallery asset).
PATCH	/v1/products/:id/media/order	Bulk update media ordering.
DELETE	/v1/products/:id/media	Delete a media item by ID, asset, or URL.

All endpoints require workspace-scoped access via resolveWorkspaceContext. Use products:read for GET and products:write for POST/PATCH/DELETE. Media creation relies on mediaCreateSchema, which enforces either a direct url or a assetId reference to a Gallery file.

Key concepts

• Media items support optional assetId references to Gallery; the service resolves public URLs when possible.
• Ordering uses integer sort values; lower numbers appear first. PATCH /media/order accepts arrays of (mediaId|assetId, sort) objects.
• Delete operations accept one identifier (mediaId, assetId, or url) via request body or query parameters.
• Validation errors throw structured responses (MediaValidationError, MediaNotFoundError, ProductOwnershipError) surfaced as HTTP 400/404.