Get a key
Sign in with Discord. You’ll get a key on this page.
Auth
Send Authorization: Bearer YOUR_API_KEY on every request except GET /api/v1.
Limits
60/min · 2,000/day per key. Over the cap: 429 with retry_after in seconds.
Endpoints
GET /api/v1
Name, docs URL, endpoint list. No key.
GET /api/v1/wallpapers
format=phone|desktop|ultrawide|superwide · sort=newest|oldest|hue|likes|downloads
Returns { "count", "wallpapers" }. Skip format for all. ultrawide includes superwide. superwide is only ≥3:1. sort=hue walks the wheel from red (hues near 360 sit next to 0); missing hue last.
GET /api/v1/wallpapers/{id}
One wallpaper. Id is the filename without extension, e.g. aug142026-2. Unknown id: 404.
GET /api/v1/latest
format=phone|desktop|ultrawide|superwide · default desktop
One wallpaper, plus requested (the format you asked for) and fallback. fallback is true only if nothing existed in that format, so this is the newest of any shape. Superwide when you asked for ultrawide is not a fallback.
GET /api/v1/works
color · tag · format=phone|desktop|ultrawide|superwide
Returns { "count", "works" }. Newest first. A work is one titled piece that has a public page. color and tag are slugs (purple, abstract). A basic color matches every shade under it; a shade like violet matches only that shade. format keeps works that have an image in that shape and drops the other sizes, including video. ultrawide includes superwide.
GET /api/v1/works/{id}
One work. Id is the slug, e.g. aurora-reprise, or a hue number, e.g. HUE-0001. Unknown id: 404.
GET /api/v1/collections
Returns { "count", "collections" }. Public collections only. Drafts are omitted, and a draft id is 404.
GET /api/v1/collections/{id}
One public collection. works is the curated order: { id, title, url, thumb }.
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://perfecthue.com/api/v1/works/aurora-reprise
Each wallpaper
| id | filename without extension |
| filename | original file |
| url | full image, or the video file when media is video |
| thumb | 640px JPEG |
| thumb_mid | 1280px JPEG |
| width / height | pixels; either may be null |
| format | phone (portrait), desktop (landscape under 2:1), ultrawide (2:1–3:1), superwide (≥3:1), or null |
| media | image on /wallpapers. video only inside a work |
| hue | 0–360, or null |
| hex | from hue, or null |
| likes | |
| downloads | |
| hue_no | HUE-0001, or null |
| work | { id, title, url } for the catalog work, or null |
| date | YYYY-MM-DD |
| created | ISO 8601, Mountain Time |
| requested | /latest only — format you asked for |
| fallback | /latest only — true if nothing in that format existed |
Each work
| id | slug, e.g. aurora-reprise |
| title | |
| catalog_no | HUE-0001, or a range when the sizes are numbered in a row |
| date | YYYY-MM-DD |
| description | or null |
| url | work page |
| thumb / thumb_mid | cover image. Same pick as the work page: closest to 16:9, phone last |
| colors | basic colors: red, orange, yellow, green, blue, purple, pink |
| shades | the finer palette slugs those roll up from, e.g. violet, cyan |
| tags | slugs, e.g. abstract, landscape |
| variant_of | parent work slug, or null |
| variants | other pieces in that family: { id, title, url, thumb } |
| stream_url | list of livestream URLs, or null |
| likes / downloads | sum of this work’s files |
| files | wallpaper objects, plus a video when the work has one |
Errors
| 401 | Unauthorized |
| 404 | Not found |
| 405 | Method not allowed |
| 429 | Rate limit exceeded · retry_after |