Skip to content
Wallpaper Server Wallpaper Server Docs

Uploading and Managing

You can add and remove wallpapers through the API or the browser gallery. This page covers uploads, rescanning and deletion, including the important detail of what deletion actually removes.

Uploading

Section titled “Uploading”

Upload an image with a multipart POST to /api/upload. The form field must be named file:

Terminal window
curl -X POST "http://localhost:8519/api/upload" \
  -F "file=@/path/to/image.jpg"

On success the server responds with 201 Created and the new wallpaper’s JSON (including its id).

What happens on upload:

  • The file extension must be one of the supported formats; otherwise the request fails with 400 and unsupported file extension.
  • The image is saved into uploads_dir under a generated unique filename.
  • It is immediately analysed, cached, thumbnailed and added to the index — no rescan needed.
  • The request body may be up to 50 MB.
  • A missing file field returns 400 with Missing 'file' field.

The browser gallery provides the same upload capability.

Rescanning folders

Section titled “Rescanning folders”

If you add or remove image files directly on disk, tell the server to rebuild its index:

Terminal window
curl -X POST "http://localhost:8519/api/refresh"

The response is {"status":"success"}. The rescan rebuilds the index atomically, so the gallery and API keep serving the old index until the new one is ready. Unsupported files are skipped, and unreadable sub-folders are logged and skipped rather than aborting the scan.

Deleting

Section titled “Deleting”
Terminal window
curl -X DELETE "http://localhost:8519/api/wallpapers/<id>"

A successful delete returns 204 No Content.

Deleting an unknown id returns 404.

Section titled “Related”