Photography — entry 024 of 25
Wallhaven
Wallhaven's v1 API exposes its wallpaper-sharing community catalog for search, browsing, and per-wallpaper metadata over plain GET requests, mirroring the site's own filters for tags, resolution, aspect ratio, purity, and sorting. Anonymous requests only return SFW results; registering a free account and passing its API key as a query parameter unlocks sketchy/NSFW purities plus access to a user's own settings, uploads, and favorites. There is no paid tier — the whole API is free, rate-limited to 45 requests per minute per the response headers.
Wallhaven's v1 API exposes its wallpaper-sharing community catalogue for search, browsing, and per-wallpaper metadata over plain GET requests, mirroring the filters (tags, resolution, aspect ratio, purity, sorting) the site itself offers. Anonymous requests reach the whole search and per-wallpaper surface and are not limited to SFW alone — an API key is only required to reach the NSFW purity tier or a user's own settings, uploads, and favorites.
GreatAPIs Score
Embed this badge
<a href="https://greatapis.com/api/wallhaven/"><img src="https://greatapis.com/badge/wallhaven.svg" alt="Scored 64 on greatapis.com"></a>Auth quickstart
- Register a free account at wallhaven.cc and copy the API key from Account → Settings → API Key.
- Pass it as the
apikeyquery parameter on any request, e.g.?apikey=<key>appended to a search or wallpaper-detail URL — there is no header-based auth. - A key is only required to unlock the NSFW purity tier or a user's own uploads/favorites/settings endpoints; SFW and sketchy search results (
purity=100orpurity=110) both work unauthenticated.
Your key is stored only in this browser (localStorage) and sent directly to the API — never to greatapis.
Search wallpapers anonymously
GEThttps://wallhaven.cc/api/v1/search?q=mountain&categories=100&purity=100&resolutions=5153x2899
{"data":[{"id":"e82xxr","url":"https:\/\/wallhaven.cc\/w\/e82xxr","short_url":"https:\/\/whvn.cc\/e82xxr","views":217,"favorites":10,"source":"https:\/\/unsplash.com\/fr\/photos\/une-lumiere-doree-illumine-les-montagnes-enneigees-et-escarpees-au-coucher-du-soleil-mac7AaETQX0","purity":"sfw","category":"general","dimension_x":5153,"dimension_y":2899,"resolution":"5153x2899","ratio":"1.78","file_size":2107070,"file_type":"image\/jpeg","created_at":"2026-08-04 04:30:07","colors":["#424153","#e7d8b1","#000000","#999999","#996633"],"path":"https:\/\/w.wallhaven.cc\/full\/e8\/wallhaven-e82xxr.jpg","thumbs":{"large":"https:\/\/th.wallhaven.cc\/lg\/e8\/e82xxr.jpg","original":"https:\/\/th.wallhaven.cc\/orig\/e8\/e82xxr.jpg","small":"https:\/\/th.wallhaven.cc\/small\/e8\/e82xxr.jpg"}}],"meta":{"current_page":1,"last_page":1,"per_page":24,"total":1,"query":"mountain","seed":null}}resolutions=5153x2899 was added to this run's live probe specifically to narrow the plain q=mountain search (20,741 total matches, unfiltered) down to a single result, keeping the captured body small — not a fabricated shape. meta.total of 1 reflects that narrowed filter, not the full unfiltered match count; a bare q=mountain&categories=100&purity=100 search returns a 24-item data page and the same meta shape with total in the thousands.
Developer reference
45 requests per minute
Gotchas & limits
- Anonymous access is not SFW-only, contrary to the intuitive assumption: a live unauthenticated probe with
purity=111(all three tiers requested) formountainreturned a mix ofsfwandsketchyentries (23 and 1 respectively in a 24-item page) and zeronsfwones — sketchy content is reachable with no key at all, only the NSFW tier is actually gated. A follow-up probe withpurity=001(NSFW only) confirmed the gate directly: it returnedtotal: 0with noapikeypresent. - The response carries
x-ratelimit-limit: 45andx-ratelimit-remainingheaders (confirmed live: 45 and 44 respectively on a fresh probe) — the 45-per-minute cap applies per the API's own docs whether or not a key is present, so throttling is required even for anonymous use. categoriesandpurityare each a 3-digit bitmask string (general/anime/people, and sfw/sketchy/nsfw respectively), not named enum values —100means "first position only", not the number one hundred. A live probe swapping tocategories=010(anime only) for the samemountainquery returnedtotal: 835, a completely different count fromcategories=100's 20,741, confirming each digit gates a distinct, independent bucket rather than acting as a numeric range.GET /w/{id}(the single-wallpaper endpoint, e.g./w/e82xxr) returns the same wallpaper object nested one level deeper under a top-leveldatakey, plus anuploaderand fulltagsarray that the search endpoint's list items omit — the two endpoints are not the same shape despite sharing most fields.- There is no CORS header on search responses — a live probe found no
access-control-allow-originon this endpoint, so it cannot be called directly from browser JS on another origin without a proxy.