API reference

Q: 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 tags.

Q: What's the difference between a browser key and a server key?

A browser key is safe to ship in frontend code and 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.

Q: 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 tag.

Q: 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.

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 at a consistent ratio on an opaque, theme-matched background (white for light, a dark neutral for dark). 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.
`frame`	`fill, original`	`fill`	`fill` fills the canvas (minus padding) with the logo's visual content, discarding source whitespace. `original` preserves the source icon's original framing and proportions, keeping app-icon-style surrounding whitespace.
`padding`	number	`10`	Margin per side around the framed content, as % of the canvas (0–20, step 5).
`shape`	`square, circle`	`square`	`square` is standard framing. `circle` sizes the logo to fit inside an inscribed circle so it won't clip in a circular avatar — the output is still a square image, with no transparency mask applied.
`part`	`full, logo, text`	`full`	Selects which piece of the logo to serve — `full` (the whole logo), `logo` (the icon/mark), or `text` (the wordmark) — for domains whose logo has been split. If the requested part isn't available, it falls back to the full logo (or a transparent image for logos managed as separate parts). Parts may be raster (PNG) and render in their real colors.
`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. Also sets the opaque background: white for `light`, a dark neutral for `dark`.
`token`	string	—	Browser key used from client code. Origin or Referer must match an allowed domain on the key.

A typical request using the canonical knobs:

GET https://api.clearlogo.dev/logo/github.com?size=128&frame=fill&padding=10&shape=square

Request just the icon/mark of a split logo with part:

GET https://api.clearlogo.dev/logo/github.com?size=128&part=logo

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 output is always an opaque, square image — there is no transparent variant. The background matches the theme: white for light and a dark neutral for dark. Within that square canvas you control the framing: frame (fill, original) chooses between filling the canvas with the logo's content or preserving the source icon's original proportions, padding (0–20, step 5) sets the margin per side, and shape (square, circle) fits the logo inside an inscribed circle when set to circle (still rendered on a square image). Use size (allowed: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024) for the exact pixel dimension. For domains whose logo has been split, part (full, logo, text) selects the whole logo (full, the default), the icon/mark (logo), or the wordmark (text), falling back to the full logo when a part isn't available (or a transparent image for logos managed as separate parts).