Documentation

Complete guide to fetching, resizing, and converting website favicons.

Endpoint

GET /<domain>[?size=<number>&format=<png|jpg|webp>&response=<json|image>&default=<url>]

Parameters

Parameter	Type	Required	Description
`domain`	string	Yes	The website domain
`size`	number	No	Image size in pixels (16–512)
`format`	string	No	Output format: png, jpg, webp
`response`	string	No	Response format: image (default) or json
`default`	string	No	Custom fallback image URL

Examples

Get favicon as image:

curl "http://favicon.btoven.net/codeberg.org"

Get metadata as JSON:

curl "http://favicon.btoven.net/codeberg.org&response=json"

Resize to 64×64:

curl "http://favicon.btoven.net/icann.org&size=64"

Convert to PNG at 128px:

curl "http://favicon.btoven.net/icann.org&format=png&size=128"

With custom fallback:

curl "http://favicon.btoven.net/example.com&default=https://mysite.com/fallback.png"

JSON Response

{
  "url": "http://favicon.btoven.net/codeberg.org&size=128",
  "sourceUrl": "https://codeberg.org/Codeberg-Design/Codeberg-Icons/favicon.svg",
  "width": 128,
  "height": 128,
  "format": "png",
  "bytes": 4521,
  "source": "html"
}

HTTP Headers

Header	Description
`Content-Type`	Image format (image/png, image/jpeg, etc.)
`Cache-Control`	7-day cache for successful requests
`Access-Control-Allow-Origin`	CORS support (configurable)

Use Cases

HTML

<img src="http://favicon.btoven.net/example.com&size=32" alt="Favicon">

JavaScript

const url = `http://favicon.btoven.net/${domain}&size=64`;

Note: For deployment instructions and troubleshooting, refer to the docs/ folder in the repository.