Skip to content
Wallpaper Server Wallpaper Server Docs

Searching and Filtering Wallpapers

Every retrieval endpoint that returns a random or listed wallpaper accepts metadata search and the same filter query parameters. This guide shows how to combine them; the Filter Reference is the exhaustive table.

How filters combine

Section titled “How filters combine”

Search terms and filters are ANDed together: a wallpaper must satisfy all the terms and filters you supply. An omitted parameter — or a filter set to any — imposes no constraint.

Terminal window
# Filename/metadata contains "mountain" AND dark AND ultrawide AND cool-toned
curl "http://localhost:8519/api/wallpapers/random/image?search=mountain&brightness=dark&aspect_ratio=ultrawide&dominant_hue=cool" \
  --output wallpaper.jpg

What you can search and filter by

Section titled “What you can search and filter by”
  • Search — case-insensitive filename, format, dimensions, brightness, orientation, aspect ratio and dominant-colour metadata. Every space-separated term must match.
  • Brightness — light, dark, medium.
  • Orientation — landscape, portrait, square.
  • Aspect ratio — 16:9, 4:3, ultrawide, square, portrait, custom.
  • Dominant colour — red, green, blue, warm, cool, neutral.
  • Format — jpg, jpeg, png, webp.
  • Dimensions — min_width, min_height, max_width, max_height in pixels (inclusive bounds).

These categories come from automatic image analysis, which runs when images are scanned or uploaded.

Recipes

Section titled “Recipes”
Terminal window
# A dark wallpaper for a phone
curl "http://localhost:8519/api/wallpapers/random/image?brightness=dark&orientation=portrait" -o phone.jpg


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


# Only true 4K (or larger) landscapes
curl "http://localhost:8519/api/wallpapers/random/image?min_width=3840&min_height=2160" -o uhd.jpg


# A warm-toned square PNG
curl "http://localhost:8519/api/wallpapers/random/image?dominant_hue=warm&aspect_ratio=square&format=png" -o warm.jpg


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

When nothing matches

Section titled “When nothing matches”

If your filters exclude every wallpaper:

  • The list endpoint (/api/wallpapers) returns an empty wallpapers array.
  • The random endpoints return 404 Not Found.

Remove a search term, loosen a filter, or set the filter to any to widen the results.

Section titled “Related”