API reference

Logo API and CDN

Put /logo/{domain} in an img tag: type, size, format, theme, background and fallback parameters, keys and caching.

The URL

GEThttps://brandidentityapi.com/logo/{domain}

One URL per company, returning an image. Put it in an img tag, a CSS background or a server-side fetch. The logo CDN never spends a credit and needs no attribution link. Requests sent with your key count toward your plan's monthly logo renders; past them, logos keep loading.

The type can also go in the path, which some image pipelines prefer: /logo/{domain}/icon, /logo/{domain}/symbol or /logo/{domain}/logo.

Parameters

Parameter	Values	Description
type	icon \| symbol \| logo	`icon` (the default) is a square mark, good for lists and avatars. `symbol` is the mark without words. `logo` is the wordmark or full lockup.
size	16 to 1024	The longest side in pixels. The default is `128`. Ask for twice the size you display. `w` and `width` are accepted as aliases.
format	webp \| png \| svg \| jpeg	The file type. Without it you get `webp` when the request's `Accept` header lists `image/webp` (every current browser does for images) and `png` otherwise, with `Vary: Accept`. Email clients such as Outlook for Windows cannot show WebP, so ask for `png` in email templates. `svg` returns the vector original when the brand has one and a PNG when it does not. JPEG (`jpg` works too) has no transparency, so it suits light, opaque tiles only.
theme	light \| dark	The color of the logo's ink: dark ink for light backgrounds, light ink for dark ones. With neither theme nor background set, a logo for a light background is preferred.
background	light \| dark	The color you will place the logo on. The same choice as `theme`, said the other way round. Ignored when `theme` is set.
fallback	monogram \| 404 \| transparent	What to return when there is no logo. `monogram` (the default) draws the brand's initial on a tile; `404` answers with a 404 so an `onerror` handler can take over; `transparent` returns an empty image.
key	lh_pk_...	Optional. With a key, a domain we have not indexed is crawled on the spot.

Theme or background?

Both say which variant you want, from opposite sides. A logo's theme describes the artwork, as in the Brand API's logos[].theme: a dark logo is drawn in dark ink. background describes your page. Most people find background harder to get backwards:

You draw it on	Ask for	Or, the same thing
A white or light page	background=light	theme=dark
A black or dark page	background=dark	theme=light

Many brands publish only one version of their logo. When the original is a single color, we generate the variant for the other background (the Brand API tags it generated), so background=dark finds a readable logo far more often than a plain logo directory would.

Examples

An icon in a list

html

<img src="https://brandidentityapi.com/logo/stripe.com?size=64" alt="Stripe logo" width="32" height="32" loading="lazy" />

A wordmark that follows dark mode

html

<picture>
  <source
    media="(prefers-color-scheme: dark)"
    srcset="https://brandidentityapi.com/logo/stripe.com?type=logo&background=dark&size=320"
  />
  <img
    src="https://brandidentityapi.com/logo/stripe.com?type=logo&background=light&size=320"
    alt="Stripe logo"
    width="160"
    height="64"
  />
</picture>

An SVG for print or a PDF

text

https://brandidentityapi.com/logo/stripe.com?type=logo&format=svg

A logo in an email

Email clients are the one place WebP still fails, so set the format to PNG and give the image fixed dimensions:

html

<img src="https://brandidentityapi.com/logo/stripe.com?format=png&size=96" alt="Stripe logo" width="48" height="48" />

Your own placeholder

html

<img
  src="https://brandidentityapi.com/logo/stripe.com?fallback=404&size=64"
  alt="Stripe logo"
  onerror="this.onerror = null; this.src = '/placeholder-logo.svg';"
/>

On your server

javascript

import { writeFile } from "node:fs/promises";

const res = await fetch("https://brandidentityapi.com/logo/stripe.com?type=logo&format=png&size=512");
if (!res.ok) throw new Error(`Logo request failed with ${res.status}`);
await writeFile("stripe.png", Buffer.from(await res.arrayBuffer()));

Keys and unknown domains

No key: brands already in the index load normally. A domain we have not indexed gets the fallback. Requests that miss our CDN's cache are limited to 300 a minute per visitor address.
With a key: an unknown domain is crawled on the spot, so the first request may take a few seconds and every later one is instant. Keyed requests are limited to 3,000 a minute per account, apart from your API limit, and count toward your plan's monthly logo renders.
Use a publishable key in HTML. A secret key works too, but anything in an img tag is public.
A revoked or mistyped key never breaks an image: the request is served as if it had no key, with an X-Api-Key-Status: invalid header to tell you.
Neither does a limit. Past the per-minute limit, or once this month's logo renders are used, requests with your key are served as if they had none, with X-Api-Key-Status: rate-limited or quota-exceeded. Indexed brands keep loading; a domain we have not indexed gets the fallback until the minute or the month ends.

Caching and server-side use

Logo responses are cached by browsers for a day and by our CDN for longer, carry an ETag for cheap revalidation, and may be served stale for a week while they refresh. A fallback image is cached for at most a day, so the real logo replaces it soon after the brand is indexed.

You may fetch logos from your server, cache them, resize them and store copies, on every plan. There is no referrer check and no rule that logos must be hotlinked.

Trademarks

Logos belong to their owners. Use them to identify the company, not to suggest it endorses you.

Asset URLs

Every formats[].src in a Brand API response points at https://brandidentityapi.com/cdn/ plus the asset's id and extension. Those files never change once written, so they are cached for a year and are safe to store as they are. Use /logo/{domain} when you want the current logo resized for you, and an asset URL when you want one exact file. See the Format fields.