Querying Metadata

The metadata endpoints return JSON describing wallpapers, including their analysis results and the URLs you can use to fetch the actual image.

Endpoints

Method	Path	Returns
`GET`	`/api/wallpapers`	A paginated, filterable list
`GET`	`/api/wallpapers/random`	One random matching wallpaper
`GET`	`/api/wallpapers/{id}`	A single wallpaper by ID

Wallpaper object

Each wallpaper is represented as:

{
  "id": "a1b2c3d4",
  "filename": "sunset.jpg",
  "path": "/home/you/Pictures/Wallpapers/sunset.jpg",
  "url": "/api/wallpapers/a1b2c3d4/image",
  "width": 3840,
  "height": 2160,
  "size_bytes": 2451234,
  "added_at": "2024-05-01T12:34:56Z",
  "content_type": "image/jpeg",
  "thumbnail_url": "/api/wallpapers/a1b2c3d4/thumbnail",
  "brightness": "dark",
  "aspect_ratio": "16:9",
  "orientation": "landscape",
  "luminance": 0.24,
  "dominant_hue": "warm"
}

Field notes:

url and thumbnail_url are relative paths to the direct-image endpoints.
brightness is one of light, dark, medium.
aspect_ratio is one of 16:9, 4:3, ultrawide, square, portrait, custom.
orientation is one of landscape, portrait, square.
dominant_hue is one of red, green, blue, warm, cool, neutral.
luminance is a float from 0 to 1.

See Automatic image analysis for how these values are derived.

Listing wallpapers

GET /api/wallpapers returns a paginated list. It accepts all filter parameters plus page and limit.

curl "http://localhost:8519/api/wallpapers?orientation=landscape&page=1&limit=20"

The response wraps the results with pagination metadata:

{
  "wallpapers": [ /* … Wallpaper objects … */ ],
  "pagination": {
    "total": 128,
    "page": 1,
    "limit": 20,
    "total_pages": 7
  }
}

page defaults to 1.
limit defaults to 50 and is capped at 200.
When any filter is applied, the response also includes a filters object echoing the parsed filter values.

A random or single wallpaper

curl "http://localhost:8519/api/wallpapers/random?brightness=dark"
curl "http://localhost:8519/api/wallpapers/<id>"

Both return a single Wallpaper object. random returns 404 when no wallpaper matches the filters; an unknown {id} also returns 404.

Retrieving images — turn a url into an actual image.
Endpoint reference — the full endpoint list.

Querying Metadata

Endpoints

Wallpaper object

Listing wallpapers

A random or single wallpaper

Related