API Overview

The Wallpaper Server API is a plain HTTP API served from the same address as the browser gallery. There is no separate API host and no versioned path prefix — all endpoints live under /api/.

Base URL

http://<host>:<port>/api

With the defaults, that is http://localhost:8519/api.

Two kinds of endpoints

The API has two distinct families:

Direct image endpoints return the raw image bytes. The Content-Type is the image’s own type (for example image/jpeg) and the body must not be parsed as JSON. These are what automation tools use.
Metadata endpoints return JSON describing wallpapers — dimensions, analysis results, URLs and pagination.

Direct image flow:   request image → save or set wallpaper
Metadata flow:       request metadata → parse JSON → request image

The direct-image flow is the reason the project exists: one URL gives you a usable wallpaper without a second round trip.

Retrieving images Random, thumbnail and by-ID image endpoints.

Querying metadata List, random and single-wallpaper JSON responses.

Filters Every query parameter and how filters combine.

Endpoint reference The canonical list of every endpoint.

Filtering

Most retrieval endpoints accept the same set of filter query parameters (brightness, dimensions, aspect ratio, orientation, dominant colour and format). Filters combine with AND. See the Filter Reference.

Resource IDs

Each wallpaper has a stable id. Use it with /api/wallpapers/{id}, /api/wallpapers/{id}/image, /api/wallpapers/{id}/thumbnail and DELETE /api/wallpapers/{id}.

Uploads and management

POST /api/upload accepts a multipart image upload.
DELETE /api/wallpapers/{id} removes a wallpaper.
POST /api/refresh rescans the configured folders.
GET / PUT /api/settings read and update configuration.

See Uploading and managing.

Authentication and exposure

Errors

Errors are returned as plain-text bodies with an appropriate HTTP status code, not JSON. There are no machine-readable error codes. See Errors.