API Overview

The Wallpaper Server API is a plain HTTP API served from the same address as the embedded browser interface. 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 metadata search plus the same set of filter query parameters (brightness, dimensions, aspect ratio, orientation, dominant colour and format). Search terms and filters combine with AND. The list endpoint also supports deterministic sorting and pagination. See the Filter Reference.

Resource IDs

Each wallpaper currently has a path-derived id; moving a source image may change its ID until the planned content-aware identity migration is implemented. 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

The server binds to 127.0.0.1 by default. Public image retrieval and metadata queries remain accessible to ordinary HTTP clients. Administrative actions (uploading, deleting, tagging, managing collections, changing settings and advancing a rotation) require authentication from remote clients.

Provide a high-entropy WALLPAPER_SERVER_ADMIN_TOKEN environment variable and send Authorization: Bearer <token> for remote management. The browser can sign in at /login; the token is exchanged for an HttpOnly, SameSite session cookie. Direct loopback requests work without credentials only when no admin token is configured. A configured token protects local callers too.

Caution

Never send admin credentials over unencrypted public HTTP. Use HTTPS with proper certificates, or reach the server through a private VPN/tunnel. An admin token is a secret: exclude it from repositories, logs and screenshots.

Deletion is now recoverable by default: source-folder images are hidden rather than removed from disk, and uploaded images are moved to trash, where they may be restored or permanently purged through explicit admin calls. The source file path is no longer part of ordinary wallpaper JSON responses.

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.