Skip to main content

​
GET /api/colors

Retrieve a complete list of all available colors extracted from the wallpaper collection. Use this endpoint to discover which colors you can filter by when requesting wallpapers.
This endpoint fetches color data from a GitHub repository file (tags.json) and extracts all unique colors from the wallpaper metadata. Colors are returned with their names and corresponding hex values.

​
Query parameters

This endpoint does not accept any query parameters.

​
Response

Returns an array of color objects.
​
[].name
string
Name of the color (e.g., darkslategray, black, blue)
​
[].hex
string
Hexadecimal color code (e.g., #2F4F4F, #000000)

​
Error responses

​
error
string
Error message describing what went wrong
500 Internal Server Error - Returned when:
  • GitHub configuration is missing (GITHUB_REPO_OWNER or GITHUB_REPO_NAME)
  • Failed to fetch the tags.json file from GitHub
  • Invalid response format from GitHub API
  • Any other server error occurs

​
Examples

# Get all available colors
curl https://wallwidgy.com/api/colors

​
Example response

[
  {
    "name": "darkslategray",
    "hex": "#2F4F4F"
  },
  {
    "name": "black",
    "hex": "#000000"
  },
  {
    "name": "blue",
    "hex": "#0000FF"
  },
  {
    "name": "red",
    "hex": "#FF0000"
  },
  {
    "name": "green",
    "hex": "#00FF00"
  }
]

​
Example error response

{
  "error": "GitHub configuration missing"
}

​
How colors are extracted

The endpoint retrieves colors through the following process:
  1. Fetches tags.json from the configured GitHub repository
  2. Decodes the base64-encoded file content
  3. Parses the JSON data
  4. Iterates through all wallpaper entries
  5. Collects colors from the colors array of each entry
  6. Removes duplicates using a Set
  7. Maps color names to hex values using a predefined color map
  8. Returns an array of unique colors with their hex codes

​
Color mapping

The endpoint includes a color mapping function that converts color names to hex codes. Currently supported colors include:
  • darkslategray: #2F4F4F
  • black: #000000
For colors not in the predefined map, the endpoint defaults to #000000 (black). The color map can be extended by updating the getColorHex function in the source code.

​
Using colors with other endpoints

Once you retrieve the available colors, you can use them to filter wallpapers: 
// Get available colors
const colorsResponse = await fetch('https://wallwidgy.com/api/colors');
const colors = await colorsResponse.json();

// Use a color to filter wallpapers
const colorName = colors[0].name;
const wallpapersResponse = await fetch(
  `https://wallwidgy.com/api/wallpapers?color=${colorName}&count=10`
);
const wallpapers = await wallpapersResponse.json();

​
Requirements

This endpoint requires the following environment variables to be configured:
  • NEXT_PUBLIC_GITHUB_ACCESS_TOKEN - GitHub personal access token
  • NEXT_PUBLIC_GITHUB_REPO_OWNER - GitHub repository owner
  • NEXT_PUBLIC_GITHUB_REPO_NAME - GitHub repository name
The repository must contain a tags.json file at the root level with wallpaper metadata including color information.

Build docs developers (and LLMs) love

Get started for freeTalk to us