Media

Media are files (images, video, PDFs, design and CAD files, 3D models) attached to products, variants and content pages. minipim stores originals only. Resizing and format conversion are left to whatever displays the file.

Each file is a media record. Attaching it to something creates an association, which holds the role, position and alt text for that one placement. One file can be attached to several products or variants without being uploaded again.

In the admin

There’s no separate media library. You manage media from the record it belongs to:

1. Open a product (the Media section), a variant, or a content page (the Media section).
2. Drag files onto Drop files here or click to upload, or click it to pick files.
3. Drag thumbnails to reorder the gallery.
4. Click the star (Set as hero) to make an image the main one.
5. Type in the Alt text field under a thumbnail. It saves when you leave the field.
6. The trash icon deletes the file.

The admin file picker shows images, video and PDFs. Use the API for other supported types.

With the API

Method	Path	What it does
POST	/v1/media	Upload a file (multipart), optionally attaching it
GET	/v1/products/{id}/media	A product’s media, in order
GET	/v1/variants/{id}/media	A variant’s media
GET	/v1/content/{id}/media	A content page’s media
POST	/v1/media/associations	Attach an existing file to another record
PATCH	/v1/media/associations/{id}	Change role, position or alt text
PUT	/v1/media/associations/reorder	Reorder all of a record’s media at once
POST	/v1/media/associations/{id}/hero	Make one association the hero
DELETE	/v1/media/associations/{id}	Detach (the file stays)
DELETE	/v1/media/{id}	Delete the file and every association

curl -X POST https://api.minipim.com/v1/media \
  -H 'Authorization: Bearer pim_…' \
  -F [email protected] \
  -F entityType=product -F entityId=PRODUCT_ID \
  -F role=gallery -F position=1 \
  -F 'altText={"en_US":"Canvas tote, front view"}'

The response includes the media row, its association and a public url. Images also get width and height. Full reference: api.minipim.com/docs.

Rules and limits

• Size: up to 100 MB per file, one file per upload request.
• Accepted types: JPEG, PNG, GIF, WebP, SVG, TIFF, MP4, WebM, PDF, PSD, AI/EPS, DWG, DXF, ZIP, DOCX, XLSX, PPTX, CSV, plain text, and glTF/GLB. Executable and script extensions (.exe, .js, .php, .html and similar) are always refused.
• minipim checks the file’s contents. If the declared type doesn’t match the bytes, it uses the type the bytes show.
• SVGs are served as downloads, never displayed inline.
• Roles: hero, gallery (the default), thumbnail, technical, lifestyle, swatch.
• One hero per record. Setting a hero demotes the previous one to gallery and pins the new one to position 0. A reorder always keeps the hero first.
• A reorder must list exactly the record’s association ids, no more and no fewer.
• Product list thumbnails use the thumbnail role first, then hero, then gallery.
• altText is an object keyed by locale, such as {"en_US":"…"}. If it’s malformed on upload, the file is still stored without alt text and the response carries a warnings array. The admin writes alt text for the default locale only.
• Detaching vs deleting: DELETE /v1/media/associations/{id} removes one placement. DELETE /v1/media/{id}, which is what the admin trash icon does, deletes the stored file and removes it from every record it’s attached to.
• Deleting a product or variant removes its associations but not the files.
• There’s no endpoint that lists every file in the organization.
• Changes emit media.uploaded, media.attached, media.association_updated, media.detached and media.deleted for webhooks.