πŸš€ New! ArtPexels Studio is now available on Microsoft Store. Get it Free

ArtPexels API

A powerful, developer-friendly JSON API to integrate high-resolution wallpapers directly into your digital products.

REST Architecture JSON Standard Public Access
Base URL
https://artpexels.com/api
Quick Links
Demo
β€”
$
▍
Response
{}
Preview

Authentication

To access the ArtPexels API, you must authenticate your requests using an API Key. Please contact our administrator team at admin@artpexels.com to request, manage, or renew your API Keys.

Authentication Methods

We support two standard methods to authenticate your requests:

Method A: HTTP Header (Recommended)

Include the key as X-API-Key in your request headers.

X-API-Key: apx_your_api_key_here
Method B: Query Parameter

Alternatively, pass the key as a query parameter named api_key in your URL query string.

https://artpexels.com/api/wallpapers?api_key=apx_your_api_key_here

Endpoints

All responses are returned as standard JSON.

Method Path Use
GET /wallpapers List + search + filters (category/orientation)
GET /categories All categories

GET /wallpapers

List wallpapers with pagination, sorting, and custom filters.

200 OK
Example Request (Recent)
GET https://artpexels.com/api/wallpapers?page=1&limit=20&api_key=apx_your_api_key_here
Query Params
  • api_key β€” *Required Your active API key
  • page β€” default: 1
  • limit β€” number, or all/-1 for no limit
  • sort β€” popular, featured, random
  • search β€” search by title/tags/category
  • category β€” filter by category name
  • subCategory β€” optional sub-category filter
Response Properties
  • success β€” true/false
  • data β€” wallpapers array
  • pagination β€” pages + count
  • thumbnailUrl/fullImageUrl β€” full image URL
Example Request (cURL with Header)
curl -H "X-API-Key: apx_your_api_key_here" "https://artpexels.com/api/wallpapers?sort=popular&page=1&limit=20"
Example Request (No Limit)
GET https://artpexels.com/api/wallpapers?limit=all&api_key=apx_your_api_key_here
Tip: Use with careβ€”fetching everything can be slow on large datasets.

Orientation (Horizontal / Portrait)

Filter wallpapers based on their layout using the orientation query parameter.

Horizontal
Use: orientation=landscape
https://artpexels.com/api/wallpapers?orientation=landscape&api_key=apx_your_api_key_here
Portrait
Use: orientation=portrait
https://artpexels.com/api/wallpapers?orientation=portrait&api_key=apx_your_api_key_here
Square
Use: orientation=square
https://artpexels.com/api/wallpapers?orientation=square&api_key=apx_your_api_key_here

Category / SubCategory

Filter wallpapers by category and optional subCategory.

Example (Category Filter)
https://artpexels.com/api/wallpapers?category=Nature&page=1&limit=20&api_key=apx_your_api_key_here
Example (Category + Orientation)
https://artpexels.com/api/wallpapers?category=Nature&orientation=landscape&api_key=apx_your_api_key_here

GET /categories

Retrieve list of all active categories.

200 OK
Example Request
https://artpexels.com/api/categories?api_key=apx_your_api_key_here

App ID & Origin Security

If the administrator has configured "Allowed Origins / Domains / App IDs" for your API Key, you MUST pass your package ID or domain name using the x-app-package or x-api-origin header. Otherwise, requests will return a 403 Forbidden error.

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

Future<void> fetchWallpapers() async {
  final url = Uri.parse('https://artpexels.com/api/wallpapers?orientation=portrait&limit=20');
  
  final response = await http.get(
    url,
    headers: {
      'Accept': 'application/json',
      'X-API-Key': 'apx_your_api_key_here',
      'x-app-package': 'com.artpexels', // Send your App ID if Allowed Origins is set
    },
  );

  if (response.statusCode == 200) {
    final Map<String, dynamic> data = jsonDecode(response.body);
    print("Fetched wallpapers successfully!");
    print(data['data']);
  } else {
    print('Failed with status code: ${response.statusCode}');
  }
}

Errors

On failure, the response will contain success: false and an error message.

Status Code Meaning
200 Success
401 / 403 Authentication Failed (Missing or Invalid API Key)
429 Rate Limit Exceeded (Too many requests in a minute)
500 Internal Server Error