# Recipe: upload an image and attach it to an article

> Upload a file with multipart form data, find it in the library and use it as an article cover.

## 1. Upload

Send the file in a form field named `file`. PNG, JPEG, WEBP and SVG are accepted.

```sh
curl -X POST "{{BASE_URL}}/v1/media/" \
  -H "Authorization: Bearer $RENEWCMS_API_KEY" \
  -F "file=@north-wall.png"
```

Status `201`:

```json
{"id":1,"filename":"north-wall.png","url":"/static/uploadedImages/8d9be79c-5db6-4d1d-9f06-b5d1b15cb4f0.png","size":100,"content_type":"image/png","width":32,"height":32,"sha256":"7654144c6e1ee8939fa061fa8129763869fa3c2de55954053a53a965848ef09c","uploaded_by":"florian","created_at":"2026-10-23T01:11:24.228947139+02:00","used_in":0,"duplicate":false,"variant_count":0,"variant_size":0}
```

`url` is relative to the instance: the public address is `{{BASE_URL}}` followed by `url`. `duplicate: true` means the same bytes were already in the library.

## 2. Find an image

```sh
curl "{{BASE_URL}}/v1/media/?size=5" \
  -H "Authorization: Bearer $RENEWCMS_API_KEY"
```

Status `200`:

```json
{"items":[{"id":1,"filename":"north-wall.png","url":"/static/uploadedImages/8d9be79c-5db6-4d1d-9f06-b5d1b15cb4f0.png","size":100,"content_type":"image/png","width":32,"height":32,"sha256":"7654144c6e1ee8939fa061fa8129763869fa3c2de55954053a53a965848ef09c","uploaded_by":"florian","created_at":"2026-10-23T01:11:24.228947139+02:00","used_in":0,"duplicate":false,"variant_count":0,"variant_size":0}],"total":1,"page":1,"size":5,"counts":{"all":1,"unused":1,"duplicates":0}}
```

Filter with `q`, `hash`, `filter` (`all`, `unused`, `duplicates`), `sort` and `variants`.

## 3. Attach it as the cover

An image is attached by id. `cover_image_alt` is the alternative text.

```sh
curl -X PATCH "{{BASE_URL}}/v1/article/1" \
  -H "Authorization: Bearer $RENEWCMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cover_image_id":1,"cover_image_alt":"A tiled bathroom wall"}'
```

Status `200`, the article object with `"cover_image_id":1` and `"cover_image_alt":"A tiled bathroom wall"`. Use `social_image_id` for the sharing image, and `null` to remove either image.

## 4. See where an image is used

```sh
curl "{{BASE_URL}}/v1/media/1/usage" \
  -H "Authorization: Bearer $RENEWCMS_API_KEY"
```

```json
[{"type":"article","id":1,"title":"How we price a bathroom renovation","published":true,"fields":["cover"]}]
```

Deleting or merging an image that is in use changes those articles, so read this first.