> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brandfetch.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Brandfetch returns real company logos, brand data, and brand context. It does not design, generate, or edit logos.
> To show a logo in a user interface, use the Logo API as an image URL in an <img> tag, such as https://cdn.brandfetch.io/domain/{domain}?c={CLIENT_ID}. The client ID is public and belongs in frontend code. Never download, proxy, re-host, or optimize these images on a server, because requests that look programmatic are redirected with automated_traffic. In Next.js, this means next/image needs a custom loader or the unoptimized prop.
> To turn a company name that a user types into a domain, use the Brand Search API with the same client ID, and keep only the domain the user picks.
> For colors, fonts, downloadable logo files, and company data as JSON, call the Brand API from a server with the header Authorization: Bearer {API_KEY}, reading the key from an environment variable and never exposing it to the browser. Prefer typed routes such as /v2/brands/domain/{domain} and /v2/brands/ticker/{ticker} over the auto-detect route /v2/brands/{identifier}.
> Use the Brand Context API for a written summary of what a company does, who it sells to, and how it sounds, and the Transaction API to identify the merchant behind a card or bank transaction label.
> When a request fails, branch on the x-bf-error header code rather than on the status code or the message text. Every code, and what to do about it, is listed at https://docs.brandfetch.com/concepts/errors.
> Requests for brandfetch.com are free on the Brand API and Brand Context API, so use that domain in tests and examples.
> Brand API responses can be cached for up to 30 days, while Logo API images must be hotlinked rather than stored and Brand Search results must not be stored at all. See https://docs.brandfetch.com/concepts/caching.
> If the user has no credentials yet, https://brandfetch.com/auth.md explains how they get a client ID and an API key. An agent without an account can pay $0.10 per Brand API, Brand Context API, or Transaction API request with x402 or MPP, as described at https://docs.brandfetch.com/agents/pay-per-request.

# Caching logos and brand data

> What you can cache from Brandfetch and for how long: hotlink Logo API images, and store Brand API data for up to 30 days before you refresh it.

What you can store depends on which API the data came from. Logo API images are meant to be hotlinked, never stored. Brand API responses and their images can be kept for up to 30 days before you refresh them.

| API | Can you cache it? | For how long | How it stays current |
| - | - | - | - |
| [Logo API](https://docs.brandfetch.com/logo-api/overview.md) | No, embed the URL in an `<img>` tag | Not stored | The same URL returns the new logo when a brand changes it |
| [Brand Search API](https://docs.brandfetch.com/brand-search-api/overview.md) | No, hotlink the icons and keep only the domain the user picks | Icon URLs expire after 24 hours | Every search is live |
| [Brand API](https://docs.brandfetch.com/brand-api/overview.md) | Yes, the JSON response and the images it links to | Up to 30 days from the day you fetched it | A new Brand API call, or [webhooks](https://docs.brandfetch.com/delivery-methods/webhooks/overview.md) when a brand changes |

These rules come from the [Brandfetch terms of service](https://brandfetch.com/terms). If you need to keep data longer or host logo files yourself, [talk to sales](https://brandfetch.com/developers/contact/sales) about a custom agreement.

## Logo API: hotlink, don't cache

A Logo API URL is meant to sit in an `<img>` tag, with the image served straight from Brandfetch's CDN. When a brand updates its logo, the same URL returns the new one, so there's no copy for you to keep in sync.

For the same reason, you can't download, proxy, or re-host Logo API images. A request that looks programmatic, like a fetch from your server or a script, is redirected with `automated_traffic`, even when it carries a valid client ID. The [usage guidelines](https://docs.brandfetch.com/logo-api/overview.md#usage-guidelines) have the details.

If your product can't hotlink, whether for privacy or compliance reasons or because it works offline, the Enterprise plan includes [self-hosted logos](https://docs.brandfetch.com/logo-api/self-hosted.md) with custom licensing terms, delivered as a bulk file and kept current with webhooks.

## Brand API: cache for up to 30 days

You can store a Brand API response, along with the logos and images it links to, for up to 30 days from the day you fetched it. Before the 30 days are up, call the Brand API again for that brand to refresh your copy. Anything older than 30 days that you haven't refreshed has to be deleted.

Caching also saves credits. A brand served from your own cache doesn't use one, and only the refresh counts, as a normal Brand API call.

```js theme={null}
const MAX_AGE = 30 * 24 * 60 * 60 * 1000; // 30 days

async function getBrand(domain) {
  const cached = await db.brands.get(domain);
  if (cached && Date.now() - cached.fetchedAt < MAX_AGE) return cached.data;
  if (cached) await db.brands.delete(domain); // expired, so it can't be served again

  const res = await fetch(`https://api.brandfetch.io/v2/brands/domain/${domain}`, {
    headers: { Authorization: `Bearer ${process.env.BRANDFETCH_API_KEY}` },
  });
  if (!res.ok) return null;

  const data = await res.json();
  await db.brands.put(domain, { data, fetchedAt: Date.now() });
  return data;
}
```

This check only removes a brand when someone asks for it again, so a brand that is never requested after its first fetch would stay in your database. Set an expiry on each record or run a scheduled cleanup that deletes anything fetched more than 30 days ago.

### Keep the cache fresh

* **Key the cache by domain.** One call then covers every user who signs up from the same company.
* **Record when you fetched each brand.** Refetch a brand before you use it once it's older than 30 days, or refresh old entries on a schedule.
* **Refresh when a brand changes.** Subscribe to [webhooks](https://docs.brandfetch.com/delivery-methods/webhooks/overview.md) for the brands you store. `brand.updated` fires when a brand's data changes, and `brand.rebranded` fires when it gets a new logo. Webhooks are available on every paid plan.
* **Use image URLs exactly as returned.** Their `t` parameter changes whenever the image does, so a new URL always means a new image. See [shortcut fields](https://docs.brandfetch.com/brand-api/logos-and-images.md#shortcut-fields).

### What cached data can be used for

Cached data is for use inside your own product, within your plan. You need an agreement to resell, sublicense, or redistribute it, including in your own API responses, and to use it to train AI or machine learning models. When your subscription ends, delete everything you cached.

The terms license Brandfetch's data, not the logos themselves, which belong to their owners. See [logo fair use](https://docs.brandfetch.com/guides/logo-fair-use.md).

## A user's own logo at onboarding

There's one exception to the 30-day rule. When a user signs up and you fetch their own company with the Brand API, you can save that logo to their account. It becomes their asset, just like a file they uploaded themselves. See [populate onboarding](https://docs.brandfetch.com/use-cases/populate-onboarding.md).

This covers only the user's own brand. Other companies' brands, like those in a customer list or a directory, still follow the 30-day rule.

## Brand Search API: don't store results

The Brand Search API is built for autocomplete. Show its results while the user types, but don't store them. Hotlink the icon URLs, which expire after 24 hours.

Once the user picks a brand, keep its `domain`. Use it with the Logo API to show the logo, or with the Brand API to get the full brand.

## Pick by use case

| You're building | Use | Caching |
| - | - | - |
| Logos in lists, tables, or portfolios | Logo API | Hotlink the URL |
| A company field with suggestions | Brand Search API | Hotlink icons, store the selected domain |
| Onboarding from a work email | Brand API | Save the user's own logo to their account |
| Enrichment of a CRM or customer list | Brand API | Up to 30 days, refreshed with calls or webhooks |
| A brand directory, or brand data in your own API | Brand API with a custom agreement | [Contact sales](https://brandfetch.com/developers/contact/sales) |
| A full copy of the dataset | [Data ingestion](https://docs.brandfetch.com/delivery-methods/data-ingestion.md) | Bulk file, kept current with webhooks |

## FAQ

> [accordion] Can I download logos from the Logo API?
>
> No. Logo API images have to be hotlinked from the CDN, and server-side or scripted requests are redirected with `automated_traffic`. If you need logo files, get them through the Brand API and follow the 30-day rule, or ask sales about self-hosted assets.

> [accordion] How long can I cache Brand API data?
>
> Up to 30 days from the day you fetched it. Refresh it with a new Brand API call before then, or delete it.

> [accordion] Does serving a brand from my cache use a credit?
>
> No. Only calls to the Brand API use credits, so each refresh uses one.

> [accordion] Can I keep logos permanently?
>
> Only with a custom agreement. Enterprise plans include self-hosted assets and custom licensing terms, so [talk to sales](https://brandfetch.com/developers/contact/sales) if you need them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.