API

Image routes, JSON discovery, and the v1 JSON API. A live playground with code samples is at /api on a running instance.

URL schemes

Domain providers

/{provider}/{size}/{ext}/{domain}

Examples:

/google/128/png/github.com
/duckduckgo/32/png/github.com
/brandfetch/0/svg/github.com
/vemetric/64/webp/github.com

Legacy three-segment routes (/{provider}/{size}/{domain}) and short aliases (/g/, /d/, …) remain valid. When ext is omitted, PNG is assumed.

Catalog providers

/{provider}/{size}/{format}/{service}

• Raster: png with sizes 64, 128, 256 (catalog-dependent)
• SVG: svg with size 0 in the path (e.g. /selfhst/0/svg/github)

Legacy routes without format default to PNG.

logo.dev

Unchanged: /logodev/{size}/{domain} (alias /l/). No ext segment.

Endpoints

Examples

https://your-host/github.com
https://your-host/jellyfin
https://your-host/scraper/github.com
https://your-host/google/64/png/github.com
https://your-host/selfhst/128/png/jellyfin
https://your-host/selfhst/0/svg/jellyfin
https://your-host/svgl/0/svg/github
https://your-host/thesvg/0/svg/github
https://your-host/brandfetch/128/png/github.com
https://your-host/github.com/json
https://your-host/jellyfin/json
https://your-host/search?q=%s

Scraper cache bypass

Append ?refresh=1 to /scraper/{domain} (or sized variant) to clear cached scraper entries before fetching again.

Use when a site changed its favicon, after scraper fixes, or when debugging stale results. ?nocache=1 is an alias.

JSON discovery

Returns proxy and upstream source URLs for every applicable provider.

Service-icon blocks

Each block is empty (service: null, …) when that catalog has no matching slug.

Variants list only assets confirmed to exist:

• selfh.st and dashboardicons — color / light / dark after CDN probe (24 h cache)
• lobehub — light/dark probed against @lobehub/icons-static-png theme assets
• svgl — SVG listed as primary; top-level png entry for raster URLs
• thesvg — SVG listed as primary (default → API color); light/dark when the icon ships those variants; top-level png entry for raster URLs

Domain JSON derives catalog slugs via resolveServiceMatches() using the label from the domain (e.g. reddit.com → reddit).

When BESTICON_URL is set, domain JSON includes icons from besticon under endpoints.scraper.icons.

Responses use Cache-Control: no-cache.

Asset proxy (/s-asset)

/providers response

{
  "logoDev": false,
  "brandfetch": false,
  "defaultProvider": "scraper",
  "includeAppIcons": true,
  "faviconProviders": ["scraper", "google", "ddg", "yandex", "faviconso", "vemetric", "favicondev", "faviconkit", "faviconrun", "twentyicons", "ryanjc", "logodev", "brandfetch"],
  "appIconProviders": ["selfhst", "dashboardicons", "lobehub", "svgl", "thesvg"],
  "urlMode": "proxy",
  "sizeFilterMin": 16,
  "sizeFilterMax": 512,
  "upstreamIpv4": true,
  "api": {
    "requireKey": false,
    "cacheTtl": 604800,
    "plans": { "free": 25, "pro": 2500, "enterprise": 0 }
  }
}

• urlMode — mirrors UI_CARD_URL (proxy or source)
• includeAppIcons — mirrors UI_INCLUDE_APP_ICONS (default “Also include CDN icon lookups” checkbox)
• faviconProviders — mirrors UI_FAVICON_PROVIDERS (homepage favicon cards; empty env = all)
• appIconProviders — mirrors UI_APP_ICON_PROVIDERS (homepage CDN icon cards; empty env = all)
• sizeFilterMin / sizeFilterMax — mirrors UI_SIZE_FILTER_MIN / UI_SIZE_FILTER_MAX (homepage Size slider defaults; steps 0|16|32|64|128|180|256|512, max may be -1 for “Max”)

Response behavior

JSON v1 errors use a different set of status codes — see Error responses.

HTTP caching

Provider image routes use memory LRU + disk cache. TTLs: Getting Started — Configuration.

JSON discovery routes send Cache-Control: no-cache.

The v1 CDN route is documented under CDN route.

API v1

GET /api/v1/favicon?url=<website> returns JSON (not image bytes) with a CDN URL to a normalized 128×128 PNG, a sourceType, and cache metadata. Clients fetch the image from the returned url via /cdn/favicons/{domain}.png.

Endpoint

GET /api/v1/favicon?url={website}

Authentication

By default, API keys are required (API_REQUIRE_KEY=true).

For self-hosted setups that want a fully public endpoint, set API_REQUIRE_KEY=false (the bundled .env.example does this). In that mode:

• No Authorization header or ?key= is required
• Per-key plans and quotas are not enforced
• A provided key is silently ignored — not validated, usage counter not incremented

When keys are required, pass the key in one of two ways:

curl "https://your-host/api/v1/favicon?url=https://github.com" \
  -H "Authorization: Bearer fa_your_key_here"

curl "https://your-host/api/v1/favicon?url=https://github.com&key=fa_your_key_here"

Only the SHA-256 hash of each key is stored. The raw key is shown exactly once at creation time.

curl is an alias for Invoke-WebRequest on Windows PowerShell and will not accept -H "Authorization: ...". Use curl.exe or:

Invoke-RestMethod "https://your-host/api/v1/favicon?url=https://github.com" `
  -Headers @{ Authorization = "Bearer fa_your_key_here" }

Successful response

{
  "url":        "https://your-host/cdn/favicons/github.com.png",
  "domain":     "github.com",
  "width":      128,
  "height":     128,
  "format":     "png",
  "sourceType": "svg",
  "cached":     true,
  "cachedAt":   "2026-06-20T08:00:00.000Z"
}

Source priority

The first tier to produce a usable icon ≥ 128px wins. ICO files are excluded (frames are typically too small).

1. svg
2. manifest
3. apple-touch-icon
4. png
5. og-image (og:image / twitter:image / msapplication-TileImage; near-square only for the chosen favicon — widescreen share cards are listed in scraper discovery / /{domain}/json but not selected as the default)
6. selfhst / dashboardicons / lobehub / svgl / thesvg (catalog fallbacks when a slug matches)
7. external (Google faviconV2 as last resort)

Within each tier, larger declared sizes are preferred.

Error responses

All errors return JSON with error, code, and extra context where useful.

Plans and quotas

Quotas apply only when API_REQUIRE_KEY=true.

0 means no limit. The plan assigned at key creation determines the monthly cap.

Quota rules (matching FaviconAPIs behaviour):

• A request counts toward the monthly quota only when the API returns 200
• 4xx and 5xx responses do not consume quota
• cached: true responses do count — the API authenticated you and returned a valid result
• Quotas reset each calendar month (UTC, YYYY-MM)

To disable plans entirely, set API_REQUIRE_KEY=false.

CDN route

GET /cdn/favicons/{domain}.png

Public read-only mirror of API_CACHE_DIR (default /cache/api/).

HTTP intermediaries (or a CDN in front of this service) can cache the PNG for the full 7 days.

Returns 404 when no PNG has been generated for that domain yet — safe to expose publicly. Callers must hit /api/v1/favicon first to populate the cache (with a valid key when API_REQUIRE_KEY=true, or without when public mode is enabled).

To warm the v1 cache for hundreds of popular domains in one run, use the preload CLI described in Performance — Preload popular sites (scripts/preload-top-sites.js).

Managing API keys

Keys are stored in SQLite at API_KEYS_DB (default /cache/api-keys.sqlite on the cache volume). Only the SHA-256 hash is persisted; the raw key is shown once at creation. The CLI is scripts/manage-keys.js.

Run the commands inside the running container so the CLI uses the same database as the server:

# Create a key (raw key printed once)
docker compose exec favicon-api npm run keys:create -- --label "customer A" --plan pro

# List active keys with this month's usage
docker compose exec favicon-api npm run keys:list

# Include revoked keys
docker compose exec favicon-api npm run keys:list -- --all

# Revoke (stops validating immediately; row kept for audit)
docker compose exec favicon-api npm run keys:revoke -- --prefix fa_abcdefgh

# Permanently delete key and usage history
docker compose exec favicon-api npm run keys:delete -- --prefix fa_abcdefgh

Plans: free, pro, enterprise. Monthly limits are set via PLAN_*_LIMIT env vars. Outside Docker, the same commands work via npm run keys:create, keys:list, keys:revoke, and keys:delete.

Prefix fa_ + 24 characters from a base32-style alphabet (no 0/O/1/I), ~120 bits of entropy. The visible prefix in keys:list is the first 11 characters — enough to revoke unambiguously without leaking the secret.