# Add an image

> Upload an image and attach it to a product or one of its variants.

This guide uploads an image as a [media](/api/product-management/medias/) and attaches it to a [product](/api/product-management/products/) and/or one of its [variants](/api/product-management/variants/), so it shows up wherever they are displayed.

Media are a two-step thing: you **upload the file once** to get a media IRI, then **reference that IRI** from the resources that use it. Both products and variants expose a `medias` list, so the same uploaded image can sit on the product, on specific variants, or both.

## Prerequisites

You need a **product with a variant** on an existing instance. If you don't have one, follow [Create your first product](/guides/create-your-first-product/) first - a new product comes with a single default variant.

As in that guide, the commands below use:

- the organization `id` - shown as `<org_id>`
- the instance `handle` (the tenant) - shown as `<tenant>`
- your product and variant ids - shown as `{productId}` and `{variantId}`

## Before you start

You need an OAuth 2.0 **bearer token** for a partner account. Sign in below: your token is dropped into every command on this page, and you can pick your organization and instance to fill `<org_id>` and `<tenant>` too. See [Authentication](/authentication/) for more.

## Steps

<Steps>

1. **Upload the image.**

   Media are created with a `multipart/form-data` upload, not JSON: send the binary in a `file` field. Capture the `@id` from the response - that's the media IRI you'll attach.

   ```bash
   curl -X POST 'https://<tenant>.product-management.flowkiwi.net/rest/api/medias' \
     -H 'Authorization: Bearer {token}' \
     -H 'X-Flowkiwi-Organization-Id: <org_id>' \
     -F 'file=@/path/to/tshirt-red-front.jpg'
   ```

   The response describes the stored media - its `contentUrl`, derived `type`, and (for images) its `dimensions`:

   ```json {2,5}
   {
     "@id": "/rest/api/medias/01234567-89ab-cdef-0123-456789abcdef",
     "contentUrl": "/uploads/medias/tshirt-red-front.jpg",
     "mimeType": "image/jpeg",
     "type": "image",
     "dimensions": {
       "width": 1200,
       "height": 1200
     }
   }
   ```

2. **Attach it.**

   Patch the `medias` list of the resource you want the image on. The list is ordered, so the first entry is the primary image. Attach it to a variant, to the product, or to both - the same media IRI can be reused.

   <Tabs>
   <TabItem label="To a variant">

   ```bash
   curl -X PATCH 'https://<tenant>.product-management.flowkiwi.net/rest/api/products/{productId}/variants/{variantId}' \
     -H 'Authorization: Bearer {token}' \
     -H 'X-Flowkiwi-Organization-Id: <org_id>' \
     -H 'Content-Type: application/merge-patch+json' \
     -d '{
       "medias": [
         "/rest/api/medias/01234567-89ab-cdef-0123-456789abcdef"
       ]
     }'
   ```

   </TabItem>
   <TabItem label="To a product">

   ```bash
   curl -X PATCH 'https://<tenant>.product-management.flowkiwi.net/rest/api/products/{productId}' \
     -H 'Authorization: Bearer {token}' \
     -H 'X-Flowkiwi-Organization-Id: <org_id>' \
     -H 'Content-Type: application/merge-patch+json' \
     -d '{
       "medias": [
         "/rest/api/medias/01234567-89ab-cdef-0123-456789abcdef"
       ]
     }'
   ```

   </TabItem>
   </Tabs>

> **Images only**
>
> Only media of `type` `image` can be attached to a product or a variant. Referencing a video or a document in `medias` is rejected with `422 Unprocessable Entity`.

3. **Verify.**

   Read the resource back - its `medias` now includes the image you attached. For a variant:

   ```bash
   curl 'https://<tenant>.product-management.flowkiwi.net/rest/api/products/{productId}/variants/{variantId}' \
     -H 'Authorization: Bearer {token}' \
     -H 'X-Flowkiwi-Organization-Id: <org_id>' \
     -H 'Accept: application/ld+json'
   ```

</Steps>

## Next steps

- **Order several images.** Send more than one IRI in `medias` - the array order is the display order, first is primary.
- **Reuse a media.** The same uploaded media can be referenced from the product and several variants; you don't re-upload it.
- **Product vs variant.** Put shared shots on the product and variant-specific shots (a colour, say) on each variant.