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

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

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 complete multipart request is bounded to approximately 50 MiB plus 2 MiB multipart overhead, with a 100-megapixel decoded-image budget.
• A missing file field returns 400 with Missing 'file' field.

Uploads and deletes require a loopback connection or, for remote clients, an admin bearer token. See Security.

The configured uploads directory is automatically included in subsequent rescans and after restart, even if it is not explicitly in wallpaper_folders.

The browser gallery can queue several files, validates format and size before upload, and shows aggregate progress while sending each file through the same API endpoint.

Rescanning folders

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

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

curl -X DELETE "http://localhost:8519/api/wallpapers/<id>"

A successful delete returns 204 No Content.

Source folders versus managed uploads

For images in your configured source folders, deletion hides the image from the public gallery, image URLs and rotation without deleting the source file. You can inspect hidden images via GET /api/hidden and unhide them with PATCH /api/wallpapers/{id}/metadata using {"hidden":false}.

For images imported into the managed uploads_dir, deletion moves the file to recoverable private trash and removes it from the public index. Manage it with:

wallpaper-server trash list
wallpaper-server trash restore ID
# Explicitly irreversible: permanently remove an already trashed upload
wallpaper-server trash purge --confirm ID

The API equivalents are GET /api/trash, POST /api/trash/{id}/restore and DELETE /api/trash/{id}. Metadata and trash calls require administrative access.

Deleting an unknown id returns 404.

Related

• Supported formats
• Caching and storage
• Endpoint reference