Skip to content
Wallpaper Server Wallpaper Server Docs

Filter Reference

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

Applicable endpoints

Section titled “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

Section titled “Parameters”
Parameter Type Accepted values Notes
search string free text Case-insensitive filename and metadata search; space-separated terms use AND semantics
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)
sort string id, date_added, filename, size, dimensions, brightness plus :asc or :desc List ordering; API default id:asc, WebUI default date_added:desc
page integer ≥ 1 List pagination; defaults to 1
limit integer 1–200 List page size; defaults to 50, capped at 200

Behaviour

Section titled “Behaviour”
  • Combination: search terms and explicit 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: search and enum query values are normalised to lowercase. format treats jpg and jpeg as equivalent, while dominant_hue=blue aliases the stored cool category.
  • 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

Section titled “Examples”
Terminal window
# 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


# Search and paginate the metadata list alphabetically
curl "http://localhost:8519/api/wallpapers?search=dark%20landscape&sort=filename:asc&page=1&limit=24"