Media

A Media is a file you upload once and then attach to catalog resources. Each media exposes a contentUrl to fetch the file, its mimeType, a derived type (image, video or file), a hash, and - for images - its dimensions.

You create a media by uploading a file, then reference the returned media IRI from a Product or Variant through their medias list.

The Media object

Property	Type	Required	Description
@context	object	-
@id	string	required
@type	string	required
id	string	-	The resource's unique identifier (UUID).
contentUrl	string | null	-	The URL to fetch the uploaded file.
mimeType	string | null	-	MIME type of the file
type	"image" | "video" | "file"	-	Media type based on MIME type (image, video, or file)
hash	string | null	-	SHA256 hash of the file
dimensions	EmbeddedImageDimensionResource | null	-
Show dimensions fields Property Type Required Description width integer required Image width in pixels height integer required Image height in pixels
createdAt	string | null	-
updatedAt	string | null	-

Common workflows

• Add a product image. Upload the file, then add the returned media IRI to a Variant’s medias (or a product’s).
• Serve the file. Use the contentUrl from the media to display it.
• Clean up. Delete a media that is no longer referenced.

Conventions

Authentication and headers

All requests require an OAuth 2.0 bearer token and the organization scope header:

Authorization: Bearer <token>
X-Flowkiwi-Organization-Id: <organization-id>

Uploading

Media are created with a multipart/form-data upload, not a JSON body. Send the binary in a file field (max 5 MB for general files, 100 MB for videos). The mimeType, type, hash and image dimensions are derived from the uploaded file - you don’t set them.