Skip to main content
There are two ways to get a logo:

Logos in your pages

https://img.hydrafetch.com/logo/{domain} returns the company’s logo as an image, not as JSON. It comes from the same work behind brand data, cut down to the one thing most people want.
Two things about it are different from every other endpoint, on purpose.

Logo images never use credits

They count against a separate allowance in your plan. A page showing forty logos uses forty logo serves and zero credits.

The key goes in your page

An <img> tag cannot send a header, so this endpoint takes a publishable key in the URL. Publishable keys are meant to be public, and they work here and nowhere else.

Publishable keys

Create one in the dashboard next to your secret keys. They start with hf_pk_, and it is safe to commit them and put them in browser HTML. A publishable key cannot call /v1/web/scrape, /v1/web/crawl or any other endpoint; those answer 401. It only serves logos, which is why it is safe to publish. You can lock a key to a list of domains. Requests are then checked against their Referer or Origin header, and anything else is refused.
Domain locking is not access control. The browser sets Referer, so anyone can send any value. Locking stops someone casually reusing a key copied from your page, which is useful, but it will not stop someone determined.It also does not apply to images already cached at the edge. Once a URL has been served to an allowed domain, that exact URL is served from cache without the check, for up to 24 hours. For the same reason, revoking a key does not instantly stop URLs that are already cached.Your allowance and our abuse detection are what really limit misuse.
If you lock a key, make sure your pages send a referrer. A Referrer-Policy of no-referrer, or <img referrerpolicy="no-referrer">, gets every request refused.

Options

string
required
Your publishable key. From a server, you can send it in the X-API-Key header instead.
number
default:"128"
The longest side in pixels, from 16 to 512. Rounded up to the nearest size we store.
string
default:"light"
The background you are drawing on: light, dark or auto. light and dark fix the logo to one colour. auto follows the viewer’s operating system setting. Read Getting the theme right before using auto.
string
default:"icon"
icon for the square mark, wordmark for the full logo with the name. If the company has only one, you get that one.
string
default:"monogram"
What to serve when we have no logo: monogram (the first letter in the brand’s colour), transparent (a 1 by 1 clear pixel) or 404.

Examples

Dark background
The full wordmark
Remove the image when there is no logo

Getting the theme right

Most logos are one colour, and the wrong one is invisible, not just wrong. A white logo on a white card looks to your users as if there is no logo at all. Pass the theme your page is actually showing, not the operating system’s:
Use theme=auto only in one case. An adaptive logo decides its colour inside the image, and an image in an <img> tag cannot see your page, only the viewer’s operating system setting. If your site always follows the operating system, auto is right. If your site has its own light and dark switch, auto is wrong whenever a visitor sets your switch differently from their system, which is exactly when a missing logo is most noticeable. So with a theme switch, pass light or dark yourself. The React package takes the theme once on its provider and every <Logo> inside follows it:
See SDKs for the browser packages.

A domain we have never seen

The first request for a new domain looks it up there and then and waits, instead of answering with a placeholder. A placeholder on the first view would look like “they have no logo” when we are seconds away from having one. The wait has a limit. Past it, the lookup finishes in the background, that one request gets the fallback, and the next request is served from storage. Expect a new domain to take a few seconds the first time and every request after to be instant.

Caching

A logo is served with Cache-Control: public, max-age=86400, so browsers and CDNs keep it for a day. Fallbacks are cached for much less time, so a domain we resolve later starts showing its real logo on its own. Because logos are cached at the edge, most requests never reach us, and anything served from cache uses none of your allowance.

A logo as data

From your server, GET /v1/web/brand/logo returns the logo’s details as JSON, including a public image URL you can store and show anywhere. It costs 1 credit, compared with 5 for the full brand record.
It takes domain (a URL works too), theme and type, with the same meanings as above.

Billing

Logo images count against your plan’s logo allowance for each billing cycle, separately from credits. A logo image never uses a credit, and credits never buy logo images. Only a delivered logo counts. If we have no logo, or are still looking it up, you get a placeholder and your allowance is not touched. Neither is anything served from the edge cache. Going over your allowance does not break your pages straight away. For 7 days we keep answering with monogram placeholders instead of errors, so nothing on your site turns into a broken image while you notice and upgrade. After that the endpoint returns an error. See Plans and billing.

Brand data

The full record: logos, colours, fonts and socials.

API keys

Creating publishable and secret keys, and what to do if one leaks.

SDKs

Including the browser and React logo packages.

Errors

What a 401, 403 or 429 means.