Filter Reference

This is the canonical reference for every filter. Guides such as Filtering wallpapers link here rather than repeating the tables.

Applicable endpoints

Filters apply to the retrieval endpoints:

• GET /api/wallpapers
• GET /api/wallpapers/random
• GET /api/wallpapers/random/image
• GET /api/wallpapers/random/thumbnail

Parameters

Parameter	Type	Accepted values	Notes
brightness	string	light, dark, medium	Matches the analysed brightness category
aspect_ratio	string	16:9, 4:3, ultrawide, square, portrait, custom	Matches the analysed aspect-ratio category
orientation	string	landscape, portrait, square	Matches the analysed orientation
dominant_hue	string	red, green, blue, warm, cool, neutral	Matches the analysed dominant colour
format	string	jpg, jpeg, png, webp	Matched case-insensitively against the file extension
min_width	integer	pixels	Keeps images at least this wide (inclusive)
min_height	integer	pixels	Keeps images at least this tall (inclusive)
max_width	integer	pixels	Keeps images at most this wide (inclusive)
max_height	integer	pixels	Keeps images at most this tall (inclusive)
page	integer	≥ 1	List pagination; defaults to 1
limit	integer	1–200	List page size; defaults to 50, capped at 200

Behaviour

• Combination: multiple filters combine with AND — a wallpaper must satisfy all of them.
• Empty or any: an omitted parameter, an empty value, or the literal value any disables that filter.
• Case sensitivity: brightness, aspect_ratio, orientation and dominant_hue are matched against the stored lowercase categories. format is compared case-insensitively.
• Numeric bounds: min_* and max_* bounds are inclusive. A wallpaper narrower than min_width or wider than max_width is excluded.
• No matches: if no wallpaper matches, the list endpoint returns an empty list, and the random endpoints return 404.
• URL encoding: when combining filters in a shell, quote the whole URL so & is not interpreted by the shell.

Examples

# Dark phone wallpaper
curl "http://localhost:8519/api/wallpapers/random/image?brightness=dark&orientation=portrait" -o out.jpg

# Light desktop wallpaper
curl "http://localhost:8519/api/wallpapers/random/image?brightness=light&orientation=landscape" -o out.jpg

# 4K landscape wallpaper
curl "http://localhost:8519/api/wallpapers/random/image?min_width=3840&min_height=2160&orientation=landscape" -o out.jpg

# Cool-toned ultrawide wallpaper
curl "http://localhost:8519/api/wallpapers/random/image?dominant_hue=cool&aspect_ratio=ultrawide" -o out.jpg

# Square PNG wallpaper
curl "http://localhost:8519/api/wallpapers/random/image?aspect_ratio=square&format=png" -o out.jpg