RenewCMS/docs/llm/recipe-media.md

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.

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

Status 201:

{"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

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

Status 200:

{"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.

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

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

[{"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.