# Wallhaven API
> Live wallpaper-community data from Wallhaven as an API — search the large community wallpaper collection by keyword and category (general, anime, people), sorted by favourites, views or freshness, and read any wallpaper's community engagement (favourites and views) along with its resolution, aspect ratio, file type, dominant colours and tags. The visual-community engagement layer for wallpaper, design and dashboard apps. SFW-only by design — every request is forced to safe content. Live, no key, no cache. Distinct from generic image and stock-photo APIs — this is Wallhaven's own community wallpapers, their favourites/views engagement and tags.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/wallhaven-api/..."
```

## Pricing
- **Free** (Free) — 10,000 calls/Mo, 5 req/s
- **Starter** ($8/Mo) — 120,000 calls/Mo, 15 req/s
- **Pro** ($22/Mo) — 630,000 calls/Mo, 40 req/s
- **Scale** ($49/Mo) — 3,200,000 calls/Mo, 100 req/s

## Endpoints

### Search

#### `GET /v1/search` — Search SFW wallpapers by keyword and category

**Parameters:**
- `q` (query, optional, string) — Keyword / tag Example: `mountains`
- `category` (query, optional, string) — general|anime|people|all Example: `anime`
- `sort` (query, optional, string) — favorites|views|date_added|relevance Example: `favorites`
- `page` (query, optional, string) — Page (1-50) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/wallhaven-api/v1/search?q=mountains&category=anime&sort=favorites&page=1"
```

**Response:**
```json
{
    "data": {
        "page": 1,
        "sort": "favorites",
        "count": 24,
        "query": "mountains",
        "total": 721,
        "category": "anime",
        "wallpapers": [
            {
                "id": "9mjoy1",
                "url": "https://wallhaven.cc/w/9mjoy1",
                "image": "https://w.wallhaven.cc/full/9m/wallhaven-9mjoy1.png",
                "ratio": "1.78",
                "thumb": "https://th.wallhaven.cc/small/9m/9mjoy1.jpg",
                "views": 842422,
                "colors": [
                    "#424153",
                    "#999999",
                    "#cccccc",
                    "#ffffff",
                    "#fdadc7"
                ],
                "purity": "sfw",
                "category": "anime",
                "favorites": 5671,
                "file_size": 15842713,
                "file_type": "image/png",
                "resolution": "3840x2160"
            },
            {
                "id": "72yzje",
                "url": "https://wallhaven.cc/w/72yzje",
                "image": "https://w.wallhaven.cc/full/72/wallhaven-72yzje.jpg",
                "ratio": "1.78",
                "thumb": "https://th.wallhaven.cc/small/72/72yzje.jpg",
                "views": 169559,
                "colors": [
                    "#424153",
                    "#000000",
                    "#333399",
                    "#0066cc",
                    "#66cccc"
                ],
                "purity":
…(truncated, see openapi.json for full schema)
```

### Wallpaper

#### `GET /v1/wallpaper` — A wallpaper detail, engagement and tags

**Parameters:**
- `id` (query, required, string) — Wallhaven wallpaper id Example: `9mjoy1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/wallhaven-api/v1/wallpaper?id=9mjoy1"
```

**Response:**
```json
{
    "data": {
        "id": "9mjoy1",
        "url": "https://wallhaven.cc/w/9mjoy1",
        "tags": [
            {
                "id": 2692,
                "name": "samurai",
                "purity": "sfw",
                "category": "Miscellaneous"
            },
            {
                "id": 479,
                "name": "digital art",
                "purity": "sfw",
                "category": "Digital"
            },
            {
                "id": 10743,
                "name": "Mount Fuji",
                "purity": "sfw",
                "category": "Landscapes"
            },
            {
                "id": 7,
                "name": "Japan",
                "purity": "sfw",
                "category": "Countries"
            },
            {
                "id": 2612,
                "name": "cherry blossom",
                "purity": "sfw",
                "category": "Plants"
            },
            {
                "id": 115,
                "name": "trees",
                "purity": "sfw",
                "category": "Landscapes"
            },
            {
                "id": 1265,
                "name": "forest",
                "purity": "sfw",
                "category": "Nature"
            },
            {
                "id": 190,
                "name": "clouds",
                "purity": "sfw",
                "category": "Miscellaneous"
            },
            {
                "id": 17182,
                "name": "p
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/wallhaven-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "sorts": [
            "favorites",
            "views",
            "date_added",
            "relevance",
            "toplist"
        ],
        "source": "Wallhaven public API (live, SFW-only)",
        "service": "wallhaven-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/search": "Search wallpapers (q=, category=general|anime|people|all, sort=favorites|views|date_added|relevance, page).",
            "GET /v1/wallpaper": "A wallpaper's detail + engagement + tags (id=9mjoy1)."
        },
        "categories": [
            "all",
            "general",
            "anime",
            "people"
        ],
        "description": "Live Wallhaven community wallpaper data: search the SFW collection by keyword and category (general/anime/people) sorted by favourites, views or freshness, and read any wallpaper's engagement (favourites, views) with resolution, ratio, file type, colours and tags. SFW-only by design. Live, no key. Distinct from generic image/photo APIs — this is Wallhaven's own community wallpapers and engagement.",
        "upstream_status": "ok"
    },
    "meta": {
        "timestamp": "2026-06-09T03:02:06.018Z",
        "request_id": "e0ab041e-f095-4c7b-bfdc-ba6cdddba229"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/wallhaven-api
OpenAPI spec: https://www.oanor.com/api/wallhaven-api/openapi.json