API Documentation

Updated at: November 1, 2025

Complete guide to using the Favicolor API in your projects

Introduction

The Favicolor API is available for both web applications and mobile apps. This documentation covers examples using both cURL (for testing) and fetch (for JavaScript integration).

Base URL: icon.favicolor.com

Authentication: When using the API from a web browser, authentication is automatic via the Origin header. For cURL/scripts, you need to provide the X-App-Id header (see examples below).

Quick Start

Direct Image Usage

Use directly in img tags - perfect for simple integration

<img
  src="https://icon.favicolor.com/image/github.com?size=64&theme=dark"
  alt="GitHub favicon"
/>

Fetch Favicon Colors

Get favicon metadata and extracted colors in JSON format

fetch('https://icon.favicolor.com/favicon/github.com?size=64&theme=dark')
  .then(res => res.json())
  .then(data => {
    console.log(data.colors.dominant); // "#24292e"
  });

Using React or Next.js?

We recommend using our dedicated @favicolor/react package for optimal integration with ready-to-use components and smart caching.

View React Documentation →

Authentication

Favicolor uses different authentication methods depending on your development environment.

Development (Localhost)

For local development (automatically detected via localhost:*, 127.0.0.1:*, 0.0.0.0:*), an API Key is required. Use Header (recommended) or Query Parameter (only for img tags).

curl "https://icon.favicolor.com/favicon/github.com?apiKey=sk_dev_xxx"

If you don't have an API Key yet, you can get one by creating a free account and then accessing the My Apps page.

Production

In production, web applications are automatically identified via the Origin header. No account is required to access the free tier, but it is highly recommended to create one to track your quotas and manage your applications. For mobile applications, an appId is required.

curl "https://icon.favicolor.com/favicon/github.com" \
  -H "Origin: https://mywebsite.com"

Endpoints

GET/favicon/:domain

Get favicon with extracted colors (JSON)

Parameters

domain-Domain name (e.g., github.com)

Query params (optional)

size-Image size: 32, 64, 96, 128 (default: 64)
theme-Theme: light, dark (for monochrome logos)

Response

JSON Response

{
  "domain": "github.com",
  "colors": {
    "dominant": "#24292e",
    "palette": [
      "#24292e"
    ],
    "average": "#24292e",
    "accent": "#23292e",
    "background": "#eaeef1",
    "border": "#24292e"
  },
  "cached": true,
  "shape": "custom"
}

GET/image/:domain

Get the favicon image directly (Content-Type: image/*)

Parameters

domain-Domain name (e.g., github.com)

Query params (optional)

size-Image size: 32, 64, 96, 128 (default: 64)
theme-Theme: light, dark (for monochrome logos)

Rate Limits

How does rate limiting work?

Rate limits are applied per unique domain (identified by Origin header, App ID, or API Key). Each domain/app has its own independent quota. If you have multiple websites using Favicolor, each one gets the full quota.

Concrete example:

• website-a.com calls /image/github.com → 1 request counted

• website-a.com calls /favicon/github.com → 0 request counted (github.com already counted for website-a.com)

• website-b.com calls /image/github.com → 1 request counted (separate quota for website-b.com)

How many requests can I make?

Plan	Per day	Per month	Scope
FREE Plan	100	3,000	Per domain / app (independent quotas)
STARTER Plan	5,000	150,000	Global to account
PRO Plan	30,000	900,000	Global to account

Rate limit headers: Each response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers to track your usage.