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
Section titled “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 provide an appropriate image Content-Type and inline
Content-Disposition. Random-selection endpoints use
Cache-Control: no-store so intermediaries cannot repeat a previous choice.
Specific-image, derivative and raw cache URLs use private, no-store so
hidden or deleted images are not unintentionally replayed by shared caches.
Metadata endpoints
Section titled “Metadata endpoints”These return JSON.
| Method | Path | Response | Success | Notes |
|---|---|---|---|---|
GET |
/api/wallpapers |
list + pagination | 200 |
Accepts search, filters, deterministic sort, 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 |
Management endpoints
Section titled “Management endpoints”| 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 |
Hides sources or trashes managed uploads; X-Wallpaper-Removal describes recovery |
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 |
Browser and static routes
Section titled “Browser and static routes”| Method | Path | Purpose |
|---|---|---|
GET |
/ |
Searchable, filterable, paginated browser gallery |
GET |
/server |
Authenticated runtime, library, storage and configuration overview |
GET |
/login |
Browser admin sign-in form |
GET |
/manage |
Authenticated library management and hidden/trash tools |
GET |
/rotation |
Authenticated rotation profile manager |
GET |
/collections |
Collection gallery |
GET |
/duplicates |
Admin-only duplicate discovery 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 |
New library and rotation endpoints
Section titled “New library and rotation endpoints”| Method | Path | Purpose |
|---|---|---|
GET |
/api/health |
Read-only service health |
PATCH |
/api/wallpapers/bulk/metadata |
Authenticated atomic metadata patch for 1–200 IDs |
GET |
/api/wallpapers/{id}/compatibility?width=W&height=H&fit=cover |
Device fit score, explanations and rendered-variant URL |
GET |
/api/device/recommendations?width=W&height=H&limit=12 |
Geometry-ranked recommendations (supports ordinary filters) |
GET |
/api/events |
Server-sent event stream; bounded subscriptions, heartbeat and update notifications |
GET |
/api/wallpapers/duplicates |
Admin-only exact SHA-256 duplicate groups |
GET |
/api/wallpapers/{id}/similar |
Similar-image search by average-hash distance |
GET |
/api/wallpapers/{id}/variant?width=1920&height=1080&fit=cover |
Bounded, cached JPG/PNG resize/crop output |
GET |
/api/hidden |
Admin-only hidden source-image listing |
GET / POST |
/api/rotation/profiles |
Admin-only saved rotation profiles |
GET / PUT / DELETE |
/api/rotation/profiles/{id} |
Inspect, update or remove a profile |
GET |
/api/rotation/profiles/{id}/preview |
Preview eligible images without mutating history |
POST |
/api/rotation/profiles/{id}/next |
Select and advance profile history |
| PATCH | /api/wallpapers/{id}/metadata | Update favourite, hidden, rating and tags |
| GET / POST | /api/collections | List or create collections |
| PUT / DELETE | /api/collections/{id} | Update or remove a collection |
| POST | /api/rotation/next | Advance per-client non-repeat rotation; ?image=true returns an image |
| GET | /api/rotation/state?client=… | Read recent selections and current client state |
| GET | /api/trash | List recoverable managed uploads |
| POST | /api/trash/{id}/restore | Restore a managed upload |
| DELETE | /api/trash/{id} | Explicitly permanently purge a trashed upload |
| POST / DELETE | /api/session | Create or clear a browser admin session |
All mutations and sensitive reads (settings, trash, hidden sources, rotation
profiles/state and duplicate fingerprints) are protected by the administrative
access policy. Cached image routes require a currently visible indexed image. See API overview for security
guidance. DELETE /api/wallpapers/{id} no longer deletes source-folder files;
managed uploads go into recoverable trash.