Try It Without an API Key

Open this URL in your browser or call it from code. It returns up to 10 free wallpapers as JSON, with no signup. The demo is limited to 10 requests per minute and 30 per day per IP. For pagination and all endpoints, get a free API key.

curl "https://nexwall.kodnextech.com/api/developer/v1/demo/wallpapers?sort=random&per_page=5"

Authentication & Headers

Required Header: You must always send Accept: application/json in your requests, otherwise Laravel might return HTML errors instead of JSON data.

Copy your API key from the developer dashboard and send it in the Authorization header.

Authorization: Bearer YOUR_API_KEY
Accept: application/json

Endpoints

Method	Path	Use
GET	https://nexwall.kodnextech.com/api/developer/v1/categories	List active categories available for your plan.
GET	https://nexwall.kodnextech.com/api/developer/v1/wallpapers	Paginated wallpapers. Supports page, per_page, category_id, search, sort, and type.
GET	https://nexwall.kodnextech.com/api/developer/v1/categories/1/wallpapers	Fetch wallpapers from one category.
GET	https://nexwall.kodnextech.com/api/developer/v1/wallpapers/1	Fetch one wallpaper by ID.

Get All Categories

Fetch all active wallpaper categories. The response format provides the id which you can use to filter wallpapers.

GET https://nexwall.kodnextech.com/api/developer/v1/categories

Response Structure (Example):

{
  "data": [
    {
      "id": 21,
      "name": "Devotional & Spiritual",
      "slug": "devotional-spiritual",
      "cover_image_url": "https://img.kodnextech.../cover.webp",
      "wallpaper_count": 431,
      "is_premium": false
    }
  ]
}

Filter Wallpapers by Category

You can pass category_id as a query parameter to get wallpapers for a specific category.

GET https://nexwall.kodnextech.com/api/developer/v1/wallpapers?category_id=32&per_page=50

Search Wallpapers

You can use the search query parameter to find wallpapers by their tags or keywords. The search requires a minimum of 2 characters.

GET https://nexwall.kodnextech.com/api/developer/v1/wallpapers?search=dark&per_page=50

Sorting

By default, wallpapers are sorted by newest. You can change this using the sort parameter. Accepted values are: newest, popular (most downloaded), oldest, or random.

GET https://nexwall.kodnextech.com/api/developer/v1/wallpapers?sort=popular&per_page=50

Pagination

To load the next set of wallpapers (e.g. for Infinite Scroll or "Load More" buttons), pass the page parameter. The default per_page limit is 50, but you can request up to 100 at a time.

GET https://nexwall.kodnextech.com/api/developer/v1/wallpapers?per_page=50&page=2

The API response includes current_page and last_page fields to help you build pagination flows.

Official SDKs & Starter Apps

Install a client library or clone an MIT-licensed starter app from GitHub.

npm install nexwall
pip install nexwall

Integration Examples

cURL

curl -X GET "https://nexwall.kodnextech.com/api/developer/v1/wallpapers?per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Flutter / Dart

import 'package:http/http.dart' as http;
import 'dart:convert';

Future<Map<String, dynamic>> fetchWallpapers() async {
  final response = await http.get(
    Uri.parse('https://nexwall.kodnextech.com/api/developer/v1/wallpapers?per_page=20'),
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Accept': 'application/json',
    },
  );

  if (response.statusCode == 200) {
    return jsonDecode(response.body);
  } else {
    throw Exception('API request failed with status: ${response.statusCode}');
  }
}

Android Kotlin (OkHttp / Retrofit)

val request = Request.Builder()
    .url("https://nexwall.kodnextech.com/api/developer/v1/wallpapers?per_page=20")
    .addHeader("Authorization", "Bearer YOUR_API_KEY")
    .addHeader("Accept", "application/json")
    .build()

OkHttpClient().newCall(request).enqueue(object : Callback {
    override fun onFailure(call: Call, e: IOException) {
        e.printStackTrace()
    }

    override fun onResponse(call: Call, response: Response) {
        val json = response.body?.string()
        println("NexWall Wallpapers: $json")
    }
})

JavaScript / React Native / Node.js

async function fetchWallpapers() {
  const res = await fetch('https://nexwall.kodnextech.com/api/developer/v1/wallpapers?per_page=20', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Accept': 'application/json'
    }
  });

  if (!res.ok) throw new Error(`NexWall API Error: ${res.status}`);
  const data = await res.json();
  return data;
}

Python (requests)

import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json"
}

response = requests.get("https://nexwall.kodnextech.com/api/developer/v1/wallpapers?per_page=20", headers=headers)
if response.status_code == 200:
    wallpapers = response.json()
    print("Fetched", len(wallpapers["data"]), "wallpapers")
else:
    print("Error:", response.status_code, response.text)

PHP / Laravel (Http Client)

use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_KEY')
    ->acceptJson()
    ->get('https://nexwall.kodnextech.com/api/developer/v1/wallpapers', [
        'per_page' => 20,
        'category_id' => 12,
    ]);

if ($response->successful()) {
    $wallpapers = $response->json('data');
}

Plan Limits & Response Headers

Free: 100 requests/day, 60 requests/min, free categories only, no premium, no live wallpapers.
Pro: 10,000 requests/day, 180 requests/min, free and premium static-image categories, no live wallpapers.
Ultra: 50,000 requests/day, 300 requests/min, Pro access plus live wallpaper entries.

Commercial integration is governed by the Developer API License. Plan access does not transfer content ownership.

HTTP Rate Limiting Headers

Header	Description
X-RateLimit-Limit	The total daily request limit for your current plan (e.g. 100, 10000, 50000).
X-RateLimit-Remaining	Remaining requests allowed today before rate limiting kicks in.
X-RateLimit-Reset	Unix timestamp for the next daily quota reset.
X-Developer-Api-Plan	Your active subscription plan (free, premium, ultra).

HTTP Status Codes & Error Handling

Status	Reason	How to Resolve
200 OK	Success	Request processed successfully.
401 Unauthorized	Invalid or missing API key	Ensure `Authorization: Bearer YOUR_API_KEY` header is present.
404 Not Found	Record missing or unavailable to the plan	Confirm the numeric ID and your plan's category or content access.
429 Too Many Requests	Per-minute or daily rate limit exceeded	Honor Retry-After. Daily quota resets at midnight UTC; higher plans provide larger limits.
422 Unprocessable	Validation error	Check query parameters (e.g. search query must be at least 2 chars).

Instant API Testing

Postman Collection

Download Postman Collection (.json)

Import our ready-to-use Postman Collection to test all endpoints (/categories, /wallpapers, filters, search, and details) in seconds.

Quick Import Steps:

Click Download Postman Collection above.
Open Postman → Click Import (top left) → Drag and drop the downloaded JSON file.
In Postman Collection variables, set API_KEY to your developer token.

Integrate NexWall Wallpapers in Your App