API v1 Documentation

Wallpaper info can be accessed via URL
https://wallhaven.cc/api/v1/w/<ID here>

NSFW wallpapers are blocked to guests. Users can access them by providing their API key:
https://wallhaven.cc/api/v1/w/<ID>?apikey=<API KEY>

GET https://wallhaven.cc/api/v1/w/94x38z
{
  "data": {
    "id": "94x38z",
    "url": "https://wallhaven.cc/w/94x38z",
    "short_url": "http://whvn.cc/94x38z",
    "uploader": {
      "username": "test-user",
      "group": "User",
      "avatar": {
        "200px": "https://wallhaven.cc/images/user/avatar/200/11_3339efb2a813.png",
        "128px": "https://wallhaven.cc/images/user/avatar/128/11_3339efb2a813.png",
        "32px": "https://wallhaven.cc/images/user/avatar/32/11_3339efb2a813.png",
        "20px": "https://wallhaven.cc/images/user/avatar/20/11_3339efb2a813.png"
      }
    },
    "views": 12,
    "favorites": 0,
    "source": "",
    "purity": "sfw",
    "category": "anime",
    "dimension_x": 6742,
    "dimension_y": 3534,
    "resolution": "6742x3534",
    "ratio": "1.91",
    "file_size": 5070446,
    "file_type": "image/jpeg",
    "created_at": "2018-10-31 01:23:10",
    "colors": [
      "#000000",
      "#abbcda",
      "#424153",
      "#66cccc",
      "#333399"
    ],
    "path": "https://w.wallhaven.cc/full/94/wallhaven-94x38z.jpg",
    "thumbs": {
      "large": "https://th.wallhaven.cc/lg/94/94x38z.jpg",
      "original": "https://th.wallhaven.cc/orig/94/94x38z.jpg",
      "small": "https://th.wallhaven.cc/small/94/94x38z.jpg"
    },
    "tags": [
      {
        "id": 1,
        "name": "anime",
        "alias": "Chinese cartoons",
        "category_id": 1,
        "category": "Anime & Manga",
        "purity": "sfw",
        "created_at": "2015-01-16 02:06:45"
      }
    ]
  }
}

Search listings are accessed via URL:
https://wallhaven.cc/api/v1/search

If an API key is provided, searches will be preformed with that user's browsing settings and default filters:
https://wallhaven.cc/api/v1/search?apikey=<API KEY>

With no additional parameters the search will display the latest SFW wallpapers. See the parameter list above to access other listings (random/toplist/etc.).

Listings are limited to 24 results per page. Meta information is available with each response for pagination.

When searching for an exact tag (id:##), providing the tag exists, the resolved tag name will be provided in the meta data.

Sorting by 'random' will produce a seed that can be passed between pages to ensure there are no repeats when getting a new page.

GET https://wallhaven.cc/api/v1/search
{
  "data": [
    {
      "id": "94x38z",
      "url": "https://wallhaven.cc/w/94x38z",
      "short_url": "http://whvn.cc/94x38z",
      "views": 6,
      "favorites": 0,
      "source": "",
      "purity": "sfw",
      "category": "anime",
      "dimension_x": 6742,
      "dimension_y": 3534,
      "resolution": "6742x3534",
      "ratio": "1.91",
      "file_size": 5070446,
      "file_type": "image/jpeg",
      "created_at": "2018-10-31 01:23:10",
      "colors": [
        "#000000",
        "#abbcda",
        "#424153",
        "#66cccc",
        "#333399"
      ],
      "path": "https://w.wallhaven.cc/94/wallhaven-94x38z.jpg",
      "thumbs": {
        "large": "https://th.wallhaven.cc/lg/94/94x38z.jpg",
        "original": "https://th.wallhaven.cc/orig/94/94x38z.jpg",
        "small": "https://th.wallhaven.cc/small/94/94x38z.jpg"
      }
    },
    {
      "id": "ze1p56",
      "url": "https://wallhaven.cc/w/ze1p56",
      "short_url": "http://whvn.cc/ze1p56",
      "views": 11,
      "favorites": 0,
      "source": "",
      "purity": "sfw",
      "category": "anime",
      "dimension_x": 3779,
      "dimension_y": 2480,
      "resolution": "3779x2480",
      "ratio": "1.52",
      "file_size": 1011043,
      "file_type": "image/jpeg",
      "created_at": "2018-10-07 17:05:28",
      "colors": [
        "#424153",
        "#e7d8b1",
        "#cc3333",
        "#ffffff",
        "#cccccc"
      ],
      "path": "https://w.wallhaven.cc/ze/wallhaven-ze1p56.jpg",
      "thumbs": {
        "large": "https://th.wallhaven.cc/lg/ze/ze1p56.jpg",
        "original": "https://th.wallhaven.cc/orig/ze/ze1p56.jpg",
        "small": "https://th.wallhaven.cc/small/ze/ze1p56.jpg"
      }
    }, 
✂ --- snip ---
  ],
  "meta": {
    "current_page": 1,
    "last_page": 36,
    "per_page": 24,
    "total": 848
    "query": "test" or null
## --- for exact tag searches ---
    "query": {
      "id": 1,
      "tag": "anime"
    }
    "seed": "abc123" or null
  }
}

Tag info can be queried via
https://wallhaven.cc/api/v1/tag/<ID>

GET https://wallhaven.cc/api/v1/tag/1
{
  "data": {
    "id": 1,
    "name": "anime",
    "alias": "Chinese cartoons",
    "category_id": 1,
    "category": "Anime & Manga",
    "purity": "sfw",
    "created_at": "2015-01-16 02:06:45"
  }
}

Authenticated users can read their user settings via
https://wallhaven.cc/api/v1/settings?apikey=<API KEY>

GET https://wallhaven.cc/api/v1/settings?apikey=****
{
  "data": {
    "thumb_size": "orig",
    "per_page": "24",
    "purity": [
      "sfw",
      "sketchy",
      "nsfw"
    ],
    "categories": [
      "general",
      "anime",
      "people"
    ],
    "resolutions": [
      "1920x1080",
      "2560x1440"
    ],
    "aspect_ratios": [
      "16x9"
    ],
    "toplist_range": "6M",
    "tag_blacklist": [
      "blacklist tag",
      "another"
    ],
    "user_blacklist": [
      ""
    ]
  }
}

An authenticated user collections can be accessed via:
https://wallhaven.cc/api/v1/collections?apikey=<API KEY>
Or another user's collections can be listed via:
https://wallhaven.cc/api/v1/collections/USERNAME
Only collections that are public will be accessible to other users. When authenticated, you are able to view all of your own collections.

Viewing the listing of wallpapers in a collection can be accessed via:
https://wallhaven.cc/api/v1/collections/USERNAME/ID
The result will be a similar listing as the search results above. However only the 'purity' filter will be available.
Authenticated users can access their own private collections by using their API key.

GET https://wallhaven.cc/api/v1/collections?apikey=****
{
  "data": [
    {
      "id": 15,
      "label": "Default",
      "views": 38,
      "public": 1,
      "count": 10
    },
    {
      "id": 17,
      "label": "This is another collection",
      "views": 6,
      "public": 1,
      "count": 7
    },
    {
  }
}