Endpoint Reference

This is the canonical list of every public endpoint. Filter parameters are documented once in the Filter Reference.

All endpoints are served from the base URL http://<host>:<port> (default http://localhost:8519).

Image endpoints

These return raw image bytes.

Method	Path	Response	Success	Notes
`GET`	`/api/wallpapers/random/image`	image	`200`	Accepts filters. `404` if none match
`GET`	`/api/wallpapers/random/thumbnail`	`image/jpeg`	`200`	Accepts filters. `404` if none match
`GET`	`/api/wallpapers/{id}/image`	image	`200`	`404` if the ID is unknown
`GET`	`/api/wallpapers/{id}/thumbnail`	`image/jpeg`	`200`	`404` if the ID is unknown

Image responses set Content-Type to the image type, Content-Disposition: inline, and Cache-Control: public, max-age=3600.

These return JSON.

Method	Path	Response	Success	Notes
`GET`	`/api/wallpapers`	list + pagination	`200`	Accepts filters, `page`, `limit`
`GET`	`/api/wallpapers/random`	wallpaper	`200`	Accepts filters. `404` if none match
`GET`	`/api/wallpapers/{id}`	wallpaper	`200`	`404` if the ID is unknown

Method	Path	Request	Response	Success	Notes
`POST`	`/api/upload`	multipart (`file`)	wallpaper	`201`	`400` on missing field or unsupported extension
`DELETE`	`/api/wallpapers/{id}`	—	empty	`204`	Deletes the original file from disk. `404` if unknown
`POST`	`/api/refresh`	—	`{"status":"success"}`	`200`	Rescans all folders
`GET`	`/api/settings`	—	config JSON	`200`	Returns the current configuration
`PUT`	`/api/settings`	config JSON	config JSON	`200`	Updates host, port, uploads dir and folders
`GET`	`/api/info`	—	JSON	`200`	Describes endpoints, filters and examples

Method	Path	Purpose
`GET`	`/`	The browser gallery
`GET`	`/settings`	The browser settings page
`GET`	`/fragments/gallery`	Gallery HTML fragment (used by the UI)
`GET`	`/static/…`	Bundled UI assets
`GET`	`/wallpapers/…`	Cached image and thumbnail files