Skip to main content

​
Overview

The Images API endpoint provides access to all images uploaded to the Wagtail CMS. You can retrieve image metadata, original files, and generate custom renditions.

​
Endpoint

GET /api/v2/images/

​
List All Images

Retrieve a list of all images: 
curl http://localhost:8000/api/v2/images/

​
Response

{
  "meta": {
    "total_count": 42
  },
  "items": [
    {
      "id": 1,
      "meta": {
        "type": "wagtailimages.Image",
        "detail_url": "http://localhost:8000/api/v2/images/1/"
      },
      "title": "Sourdough Bread"
    }
  ]
}

​
Get Single Image

Retrieve a specific image by ID: 
curl http://localhost:8000/api/v2/images/1/

​
Response

{
  "id": 1,
  "meta": {
    "type": "wagtailimages.Image",
    "detail_url": "http://localhost:8000/api/v2/images/1/"
  },
  "title": "Sourdough Bread",
  "width": 2400,
  "height": 1600
}

​
Query Parameters

​
fields
string
Comma-separated list of fields to include. Use * for all fields.
​
limit
integer
default:"20"
Number of results per page (max 100)
​
offset
integer
default:"0"
Number of results to skip
​
order
string
Field to order by. Prefix with - for descending (e.g., -created_at)
​
search
string
Search query to filter images by title and tags

​
Response Fields

​
Default Fields

​
id
integer
Unique identifier for the image
​
title
string
The image title
​
width
integer
Original image width in pixels
​
height
integer
Original image height in pixels
​
meta
object
Metadata about the image
​
type
string
The image model type (typically wagtailimages.Image)
​
detail_url
string
API URL for the full image details

​
All Fields

Request all fields using ?fields=*: 
curl "http://localhost:8000/api/v2/images/1/?fields=*"

​
Additional Fields with *

{
  "id": 1,
  "meta": {
    "type": "wagtailimages.Image",
    "detail_url": "http://localhost:8000/api/v2/images/1/",
    "download_url": "http://localhost:8000/media/original_images/sourdough.jpg"
  },
  "title": "Sourdough Bread",
  "width": 2400,
  "height": 1600,
  "created_at": "2024-01-15T10:30:00Z",
  "file": "/media/original_images/sourdough.jpg",
  "file_size": 524288,
  "file_hash": "abc123def456"
}
​
created_at
string
ISO 8601 timestamp when the image was uploaded
​
file
string
Relative path to the original image file
​
file_size
integer
File size in bytes
​
file_hash
string
Hash of the image file for duplicate detection
​
meta.download_url
string
Full URL to download the original image

​
Image Renditions

Wagtail can generate custom image renditions (resized/cropped versions) on the fly. Request renditions using the filter specification.

​
Rendition Filter Syntax

Rendition filters use Wagtail’s image filter syntax:
FilterDescriptionExample
width-<n>Resize to widthwidth-400
height-<n>Resize to heightheight-300
max-<w>x<h>Fit within dimensionsmax-800x600
min-<w>x<h>Cover dimensionsmin-800x600
fill-<w>x<h>Crop to exact sizefill-400x300
originalOriginal imageoriginal

​
Request Renditions

Include the rendition filter in the fields parameter: 
curl "http://localhost:8000/api/v2/images/1/?fields=width-400"

​
Response with Rendition

{
  "id": 1,
  "meta": {
    "type": "wagtailimages.Image",
    "detail_url": "http://localhost:8000/api/v2/images/1/"
  },
  "title": "Sourdough Bread",
  "width": 2400,
  "height": 1600,
  "width-400": {
    "url": "http://localhost:8000/media/images/sourdough.width-400.jpg",
    "width": 400,
    "height": 267
  }
}

​
Multiple Renditions

Request multiple renditions in a single call: 
curl "http://localhost:8000/api/v2/images/1/?fields=width-400,width-800,fill-200x200"

​
Response

{
  "id": 1,
  "meta": {
    "type": "wagtailimages.Image",
    "detail_url": "http://localhost:8000/api/v2/images/1/"
  },
  "title": "Sourdough Bread",
  "width": 2400,
  "height": 1600,
  "width-400": {
    "url": "http://localhost:8000/media/images/sourdough.width-400.jpg",
    "width": 400,
    "height": 267
  },
  "width-800": {
    "url": "http://localhost:8000/media/images/sourdough.width-800.jpg",
    "width": 800,
    "height": 533
  },
  "fill-200x200": {
    "url": "http://localhost:8000/media/images/sourdough.fill-200x200.jpg",
    "width": 200,
    "height": 200
  }
}

​
Common Use Cases

​
Responsive Images

Generate multiple sizes for responsive images: 
curl "http://localhost:8000/api/v2/images/?fields=width-320,width-640,width-1024,width-1920"

​
Thumbnail Grid

Generate square thumbnails for a grid layout: 
curl "http://localhost:8000/api/v2/images/?fields=fill-300x300&limit=12"

​
Hero Images

Get large, optimized hero images: 
curl "http://localhost:8000/api/v2/images/?fields=max-1920x1080,fill-1920x600"

​
Search and Filter

​
Search by Title

Find images by title: 
curl "http://localhost:8000/api/v2/images/?search=bread"

​
Order by Date

Get most recent images: 
curl "http://localhost:8000/api/v2/images/?fields=*&order=-created_at&limit=10"

​
Best Practices

Renditions are generated on first request and cached. The first request for a new rendition may be slower than subsequent requests.

​
Request Only Needed Renditions

Only request the renditions you’ll actually use: 
# Good: Request specific renditions
curl "http://localhost:8000/api/v2/images/?fields=width-400,width-800"

# Avoid: Requesting all fields when you only need renditions
curl "http://localhost:8000/api/v2/images/?fields=*"

​
Use Appropriate Formats

Choose the right rendition filter for your use case:
  • max-: Maintain aspect ratio, fit within bounds
  • fill-: Exact dimensions, cropped to fit
  • width-/height-: Scale to one dimension

​
Cache Rendition URLs

Rendition URLs are stable and can be cached client-side.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us