Images API¶

Upload, list, update, and delete images. Responses include rendition URLs for common sizes.

Endpoints¶

List images¶

GET /images/

Query parameters¶

Response¶

{
  "items": [
    {
      "id": 1,
      "title": "Hero image",
      "width": 2000,
      "height": 1500,
      "file_url": "/media/images/hero.jpg",
      "created_at": "2026-03-01T12:00:00",
      "renditions": {
        "thumbnail": "/media/images/hero.fill-100x100.jpg",
        "medium": "/media/images/hero.max-800x600.jpg",
        "large": "/media/images/hero.max-1600x1200.jpg"
      }
    }
  ],
  "meta": {
    "total_count": 15
  }
}

Get image detail¶

GET /images/{id}/

Returns the same fields as the list item, including all configured rendition URLs.

Upload an image¶

POST /images/
Content-Type: multipart/form-data

Example¶

curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -F "file=@photo.jpg" \
     -F "title=My Photo" \
     http://localhost:8000/api/write/v1/images/

Response¶

201 Created with the image detail including rendition URLs.

Update image metadata¶

PATCH /images/{id}/
Content-Type: application/json

{
  "title": "Updated title"
}

Delete an image¶

DELETE /images/{id}/

Returns 204 No Content on success.

Renditions¶

Rendition URLs are generated based on the IMAGE_RENDITIONS setting. The default configuration produces three sizes:

Customise these in your settings:

WAGTAIL_WRITE_API = {
    "IMAGE_RENDITIONS": {
        "small": "fill-200x200",
        "hero": "max-1920x1080",
    }
}

See Wagtail's image rendition docs for available filter specs.