API Documentation & Reference

Integrate NexWall Wallpapers in Your App

Use these RESTful endpoints to fetch category-wise 4K wallpaper data for Android, Flutter, iOS, React Native, or Web apps. All developer API requests require your Bearer API key.

Test in Sandbox Postman Collection Guides Changelog

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://cdn.nexwall.../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.

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, free categories only, no premium, no live wallpapers.
  • Pro: 10,000 requests/day, all categories & 4K wallpapers, no live wallpapers.
  • Ultra: 50,000 requests/day, all categories + exclusive live video wallpapers.

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-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.
403 Forbidden Feature not allowed on plan Live wallpapers require Ultra plan. Upgrade on your dashboard.
429 Too Many Requests Daily rate limit exceeded Quota resets at midnight UTC, or upgrade to Pro/Ultra for immediate limit increase.
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:
  1. Click Download Postman Collection above.
  2. Open Postman → Click Import (top left) → Drag and drop the downloaded JSON file.
  3. In Postman Collection variables, set API_KEY to your developer token.