API reference
One endpoint, a few knobs, two auth modes.
Need a migration path before the raw reference?
Start with the Clearbit replacement guide or the logo API buyer's guide.
ClearLogo exposes a single HTTP endpoint,
GET /logo/{domain}, that returns a PNG (or WebP/JPEG) of the domain's logo with consistent ratio and transparent background. Anonymous use works for low-volume testing; production traffic uses a browser key (client) or server key (backend).
Endpoint
GET https://api.clearlogo.dev/logo/:domain
:domain is a bare hostname with no scheme or path, for example github.com. The API returns image/png by default.
Query parameters
| Name | Type | Default | Notes |
|---|---|---|---|
size | number | 128 | Output dimension in px. Square only. Allowed values: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024. |
content | number | 80 | Logo footprint as % of the canvas (50–100, step 5). 50 = padded with visible margin; 100 = fills edge to edge. |
format | png | webp | jpeg | png | Output format. Auto-negotiated from the Accept header when omitted — modern browsers receive WebP automatically via <img>. |
theme | light | dark | light | Returns the dark variant when available, otherwise falls back to light. |
token | string | — | Browser key used from client code. Origin or Referer must match an allowed domain on the key. |
Authentication
Anonymous requests work for low-volume testing. For production traffic, use a browser key (client) or a server key (backend):
Browser
<img
src="https://api.clearlogo.dev/logo/example.com?token=YOUR_BROWSER_KEY"
alt="" />
Server
curl \
-H "Authorization: Bearer YOUR_SERVER_KEY" \
"https://api.clearlogo.dev/logo/example.com"
Rate limits
Per-key limits are returned in X-RateLimit-* headers. When you exceed them the API responds with 429 and includes a Retry-After hint.
FAQ
How do I get a logo for a domain?
Send a GET request to https://api.clearlogo.dev/logo/{domain} where {domain} is a bare hostname like github.com. No login is required for low-volume testing. The response is a PNG by default and works directly in <img> tags.
What's the difference between a browser key and a server key?
A browser key is safe to ship in frontend code and <img> tags; requests are validated against the allowed domains you configure on the key. A server key authenticates via the Authorization: Bearer header from your backend and must never reach the browser.
What output formats are supported?
png (default), webp, and jpeg. When the format parameter is omitted, ClearLogo content-negotiates from the Accept request header — modern browsers receive WebP automatically when the API is loaded via an <img> tag.
What are the rate limits?
Per-key limits are returned in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers. Exceeding the limit returns HTTP 429 with a Retry-After hint indicating how many seconds to wait before retrying.
Can I get a transparent background or a square crop?
The API returns a transparent background by default and always crops to a square canvas. Use the size parameter (allowed: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024) for the exact pixel dimension and content (50–100, step 5) to control how much of the canvas the logo occupies.