api.unfolded.tools

REST API for accessing app icons, TV app icons, community icons, and TV channel logos.

GET Status Page GET Health Check KEY Get an API Key

Authentication

All icon endpoints require an API key. Get one at unfolded.tools/settings.

Pass your key via any of these methods:

X-API-Key: uk_your_key_here          # Header (recommended)
Authorization: Bearer uk_your_key_here  # Bearer token
?api_key=uk_your_key_here             # Query parameter

Endpoints

GET/v1/icons/appsApp Store & Play Store icons

GET/v1/icons/tv-appstvOS app icons

GET/v1/icons/communityCommunity-uploaded icons

GET/v1/icons/tv-logos/countriesList countries with TV logos

GET/v1/icons/tv-logos/:countryTV logos for a country

GET/v1/icons/{category}/metaMetadata only (no base64)

GET/v1/icons/{category}/countJust the icon count

GET/v1/icons/{category}/{id}Single icon by ID

GET/v1/icons/tv-logos/{country}/{name}Single TV logo by name

GET/v1/icons/changesChangelog of added/removed icons

GET/v1/healthHealth check (no auth)

GET/v1/icons/statusPublic status page (no auth)

Response Format

Icons (apps, tv-apps, community)

{
  "category": "apps",
  "total": 189,
  "refreshedAt": "2026-05-03T12:13:17.746Z",
  "icons": [
    {
      "id": "abc-123",
      "name": "Spotify",
      "url": "https://unfolded.tools/image/app/abc-123",
      "category": "apps",
      "base64": "UklGRl4MAABXRUJQVlA4...",
      "download_url": "https://unfolded.tools/download/app/abc-123"
    }
  ]
}

TV Logos (per country)

{
  "category": "tv-logos",
  "country": "germany",
  "total": 365,
  "refreshedAt": "2026-05-03T12:13:17.746Z",
  "icons": [
    {
      "id": "germany__ARD",
      "name": "ARD",
      "url": "https://unfolded.tools/image/tvlogo/germany/ARD.png",
      "category": "tv-logos",
      "base64": "UklGRl4MAABXRUJQVlA4...",
      "download_url": "https://unfolded.tools/download/tvlogo/germany__ARD"
    }
  ]
}

Countries List

{
  "total_countries": 56,
  "total_icons": 7639,
  "countries": [
    { "country": "germany", "icon_count": 365 },
    { "country": "united-states", "icon_count": 784 }
  ]
}

Icon Fields

url — optimized WebP image (even if the URL ends in .png)

base64 — same WebP image as a base64 string, use as data:image/webp;base64,...

download_url — streams the full-quality original PNG (lossless)

Note: TV logo URLs end in .png but the server responds with an optimized WebP image. Use download_url to get the actual PNG.

Error Codes

200Success 401Missing API key 403Invalid API key 404Unknown endpoint or country 500Internal server error

{
  "error": "FORBIDDEN",
  "message": "Invalid API key"
}

Field Filtering

Add ?fields= to any icon endpoint to control which fields are returned. This can dramatically reduce response sizes by excluding base64 data.

curl -H "X-API-Key: uk_..." "https://api.unfolded.tools/v1/icons/apps?fields=id,name,url"

Returns only the specified fields per icon. Omitting base64 from the fields list can reduce the community endpoint from ~2.6 MB to ~60 KB.

Single Icon

Fetch a single icon by its ID without downloading the entire category.

curl -H "X-API-Key: uk_..." https://api.unfolded.tools/v1/icons/apps/abc-123

{
  "category": "apps",
  "icon": {
    "id": "abc-123",
    "name": "Spotify",
    "url": "https://unfolded.tools/image/app/abc-123",
    "category": "apps",
    "base64": "UklGRl4MAABXRUJQVlA4...",
    "download_url": "https://unfolded.tools/download/app/abc-123"
  }
}

For TV logos, use the country and logo name:

curl -H "X-API-Key: uk_..." https://api.unfolded.tools/v1/icons/tv-logos/germany/ARD

Count

The lightest possible check — returns just the total count for a category.

curl -H "X-API-Key: uk_..." https://api.unfolded.tools/v1/icons/community/count

{
  "category": "community",
  "total": 942
}

Examples

cURL

curl -H "X-API-Key: uk_..." https://api.unfolded.tools/v1/icons/apps

Category Metadata (without icons/base64)

curl -H "X-API-Key: uk_..." https://api.unfolded.tools/v1/icons/apps/meta

Returns icon IDs and names without base64 data — useful for checking what's available before fetching the full payload.

{
  "category": "apps",
  "total": 189,
  "refreshedAt": "2026-05-03T12:13:17.746Z",
  "icons": [
    { "id": "abc-123", "name": "Spotify", "category": "apps" },
    { "id": "def-456", "name": "Netflix", "category": "apps" }
  ]
}

Changelog

curl -H "X-API-Key: uk_..." "https://api.unfolded.tools/v1/icons/changes?since=2026-05-01&category=apps"

Returns icons added or removed since a given date. Filter by category and limit.

{
  "total": 2,
  "added": 2,
  "removed": 0,
  "since": "2026-05-01",
  "category": "apps",
  "changes": [
    { "type": "added", "category": "apps", "id": "xyz-789", "name": "NewApp", "timestamp": "2026-05-03T03:00:12Z" }
  ]
}

JavaScript

const res = await fetch('https://api.unfolded.tools/v1/icons/apps', {
  headers: { 'X-API-Key': 'uk_your_key_here' }
});
const data = await res.json();
console.log(data.total + ' icons');

Python

import requests
resp = requests.get(
    "https://api.unfolded.tools/v1/icons/apps",
    headers={"X-API-Key": "uk_your_key_here"}
)
data = resp.json()
print(f"{data['total']} icons")

Rate & caching: Data is refreshed every 24 hours. You can have up to 3 active API keys. All endpoints return JSON with CORS enabled.