Wallhaven API Guide

Overview

The Wallhaven API (v1) is a public REST API that allows developers to search wallpapers, retrieve wallpaper metadata and direct download URLs, access user collections, and query tag information. All responses are JSON.

Base URL:

https://wallhaven.cc/api/v1/

The API requires no authentication for SFW search results. An API key is required to access Sketchy/NSFW content and personal collection endpoints.

Authentication

Authentication uses an API key passed as a query parameter or request header. To generate an API key, log in to Wallhaven and go to Account Settings → API.

Using an API Key

Pass the key as a URL parameter:

https://wallhaven.cc/api/v1/search?q=anime&apikey=YOUR_API_KEY

Or as a request header:

X-API-Key: YOUR_API_KEY

With a valid API key, purity can include Sketchy (110) and NSFW (111) tiers — if enabled in your account settings.

Search Endpoint

GET https://wallhaven.cc/api/v1/search

Returns a paginated list of wallpapers matching the specified parameters. Each page returns up to 24 results.

Minimal Example

GET /api/v1/search?q=nature&purity=100&categories=100&sorting=toplist

All Search Parameters

Wallpaper Endpoint

GET https://wallhaven.cc/api/v1/w/{id}

Returns full metadata for a single wallpaper by ID. The id field is the alphanumeric wallpaper identifier visible in the URL (e.g., abc123).

Response includes:

• Full-resolution image URL (path)
• Thumbnail URLs (small, original)
• Resolution, file size, file type
• Category, purity, colors array
• Tag list with IDs and names
• Uploader, upload date, views, favorites

Tag Endpoint

GET https://wallhaven.cc/api/v1/tag/{id}

Returns information about a specific tag by its numeric ID. Response includes the tag name, alias, category, and purity level.

Collections Endpoints

All collection endpoints require a valid API key.

GET /api/v1/collections                  # List your collections
GET /api/v1/collections/{username}       # List a user's public collections
GET /api/v1/collections/{username}/{id}  # Get wallpapers in a collection

Collection listing returns the collection name, label, count, and ID. The wallpaper listing endpoint accepts the same purity and page parameters as the search endpoint.

Response Format

All API responses return JSON with a data field containing the results and a meta field with pagination info.

{{
  "data": [
    {{
      "id": "abc123",
      "url": "https://wallhaven.cc/w/abc123",
      "short_url": "https://whvn.cc/abc123",
      "views": 12400,
      "favorites": 870,
      "source": "",
      "purity": "sfw",
      "category": "general",
      "dimension_x": 3840,
      "dimension_y": 2160,
      "resolution": "3840x2160",
      "ratio": "16x9",
      "file_size": 4200000,
      "file_type": "image/jpeg",
      "created_at": "2024-03-15 10:22:00",
      "colors": ["#1a1a2e", "#16213e", "#0f3460"],
      "path": "https://w.wallhaven.cc/full/ab/wallhaven-abc123.jpg",
      "thumbs": {{
        "large": "https://th.wallhaven.cc/lg/ab/abc123.jpg",
        "original": "https://th.wallhaven.cc/orig/ab/abc123.jpg",
        "small": "https://th.wallhaven.cc/small/ab/abc123.jpg"
      }}
    }}
  ],
  "meta": {{
    "current_page": 1,
    "last_page": 100,
    "per_page": 24,
    "total": 2400,
    "query": "nature",
    "seed": null
  }}
}}

Code Examples

JavaScript (fetch)

// Search for 4K nature wallpapers, sorted by top rating
const response = await fetch(
  'https://wallhaven.cc/api/v1/search' +
  '?q=nature&categories=100&purity=100' +
  '&sorting=toplist&resolutions=3840x2160'
);
const data = await response.json();
const wallpapers = data.data;

wallpapers.forEach(wp => {{
  console.log(wp.id, wp.resolution, wp.path);
}});

Python (requests)

import requests

params = {{
    'q': 'anime',
    'categories': '010',
    'purity': '100',
    'sorting': 'date_added',
    'order': 'desc',
    'resolutions': '3840x2160',
    'page': 1,
}}
r = requests.get('https://wallhaven.cc/api/v1/search', params=params)
data = r.json()
for wp in data['data']:
    print(wp['id'], wp['path'])

Paginating Results

async function fetchAllPages(query, maxPages = 5) {{
  const results = [];
  for (let page = 1; page <= maxPages; page++) {{
    const r = await fetch(
      `https://wallhaven.cc/api/v1/search?q=${{query}}&purity=100&page=${{page}}`
    );
    const d = await r.json();
    results.push(...d.data);
    if (page >= d.meta.last_page) break;
    await new Promise(res => setTimeout(res, 500)); // rate limit delay
  }}
  return results;
}}

Rate Limits

The Wallhaven API enforces rate limits to ensure service availability. Specific limits are not officially published, but the following practices keep requests within acceptable bounds:

• Add a delay of at least 200–500ms between sequential API calls in automated scripts.
• Use an API key — authenticated requests have a higher rate allowance.
• Cache responses where possible rather than re-fetching the same query.
• Avoid concurrent batch requests; serialize requests with a queue.

If you receive a 429 Too Many Requests response, implement exponential backoff before retrying. The full official API documentation is at wallhaven.pics/help/api.