Skip to main content

​
What the API provides

The WallWidgy REST API gives you programmatic access to our curated wallpaper collection. You can retrieve random wallpapers, filter by device type (desktop or mobile), search by category, and filter by color—all through simple HTTP requests. The API is designed for developers building wallpaper apps, browser extensions, desktop widgets, or any application that needs high-quality wallpapers.

​
Base URL

All API requests are made to your deployed WallWidgy site: 
https://your-site.vercel.app/api
Replace your-site.vercel.app with your actual deployment URL.

​
Response format

All API responses are returned as JSON. Successful responses include the requested data, while errors include an error field with a description. Successful response example: 
{
  "wallpapers": [
    "https://your-site.vercel.app/wallpapers/nature_001.jpg",
    "https://your-site.vercel.app/wallpapers/abstract_042.jpg"
  ],
  "count": 2,
  "category": "all",
  "type": "all",
  "color": "all"
}
Error response example: 
{
  "error": "Category 'nonexistent' not found"
}

​
Quick example

Here’s how to fetch a random wallpaper: 
curl https://your-site.vercel.app/api/wallpapers

​
Available endpoints

The API provides several endpoints for different use cases:

Get wallpapers

Retrieve one or more wallpapers with optional filters

Search wallpapers

Search wallpapers by keyword (when available)

Random wallpaper

Get a single random wallpaper

Get colors

Retrieve available color filters
No authentication required—the API is fully public and CORS-enabled. See Authentication for details.

​
Next steps

Authentication

Learn about API access and CORS support

Rate limits

Understand fair usage guidelines

Filtering

Learn how to filter wallpapers

Examples

See complete implementation examples

Build docs developers (and LLMs) love

Get started for freeTalk to us