Querying Metadata

The metadata endpoints return JSON describing wallpapers, including their analysis results and the URLs you can use to fetch the actual image. Examples below are illustrative rather than live API responses.

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",
  "url": "/wallpapers/a1b2c3d4.jpg",
  "width": 3840,
  "height": 2160,
  "size_bytes": 2451234,
  "added_at": "2024-05-01T12:34:56Z",
  "content_type": "image/jpeg",
  "thumbnail_url": "/wallpapers/thumbnails/a1b2c3d4.jpg",
  "brightness": "dark",
  "aspect_ratio": "16:9",
  "orientation": "landscape",
  "luminance": 0.24,
  "dominant_hue": "warm"
}

Field notes:

url and thumbnail_url are relative paths to cached files. API handlers are also available at /api/wallpapers/{id}/image and /api/wallpapers/{id}/thumbnail.
path is deliberately omitted from JSON in 2.0.0; this no longer exposes the filesystem location of the original source.
id is derived from the source path rather than content. Moving a source file changes its ID.
added_at on scanned files reflects the source modification time, not a persistent library import timestamp. Uploaded files initially use their upload time; scans use the file modification time.
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, warm, cool, neutral. Querying or searching for blue aliases cool.
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 searchable, deterministically sorted, paginated list. It accepts the filter parameters plus search, sort, page and limit.

curl "http://localhost:8519/api/wallpapers?search=mountain&orientation=landscape&sort=filename:asc&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
  }
}

search is case-insensitive and requires every space-separated term to match the filename or indexed metadata.
sort defaults to id:asc for API compatibility and accepts id, date_added, filename, size, dimensions or brightness with :asc or :desc. The WebUI independently defaults to date_added:desc.
page defaults to 1.
limit defaults to 50 and is capped at 200.
When search or 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