> ## 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.

# Real-time indexing

> What happens when you ask for a brand Brandfetch has never seen, and how to control the latency

Finding Nike is easy. Finding the company your user typed into a sign-up form five seconds ago is harder. Brandfetch does not work from a fixed list: when you ask for a domain that is not in the dataset yet, Brandfetch reads the company's website live and returns the brand in the same request.

This applies to the Brand API, Brand Context API, and Transaction API.

## The three outcomes

A request for a brand ends in one of three ways:

| Brand state | What you get | Latency |
| - | - | - |
| Already indexed | `200` with the brand, answered from our store | Fast |
| New, crawl finishes in time | `200` with the freshly indexed brand | Several seconds |
| New, crawl still running | `404` with `x-bf-error: crawl_queued` | Retry in a minute or two |

A `crawl_queued` response means the crawl keeps going in the background. Retry in a minute or two, and if the brand could be collected, the retry returns it.

The Brand Context API reports the same situation differently. While a context is still being generated, it answers `503` with `x-bf-error: generation_in_progress` and a `Retry-After` header that says how many seconds to wait. That response is not charged.

## Prefetch with `HEAD`

When you know which brand you will need a few steps from now, such as right after a user signs up, ask for it in advance with a `HEAD` request on the Brand API route:

```bash theme={null}
curl --head https://api.brandfetch.io/v2/brands/jane@example.brandfetch.com \
  --header "Authorization: Bearer $BRANDFETCH_API_KEY"
```

The response has no body, and prefetch requests do not count towards your quota. `200` means the brand is ready, and `202` means a crawl has been queued so the `GET` you make later is fast. Prefetching needs a paid plan. See the [prefetch reference](https://docs.brandfetch.com/reference/brand-api-prefetch.md) for every status code.

## Skip the crawl with `cachedOnly`

When latency matters more than coverage, add `cachedOnly=true`. The API then answers from its store and never crawls:

```bash theme={null}
curl "https://api.brandfetch.io/v2/brands/domain/nike.com?cachedOnly=true" \
  --header "Authorization: Bearer $BRANDFETCH_API_KEY"
```

An indexed brand returns `200` as usual. A brand that is not indexed returns `204 No Content`, which has no body and does not count towards your quota. Check the status before you parse the response.

`cachedOnly` works on every Brand API `GET` route and on the Brand Context API.

## Which to use

| You are building | Use |
| - | - |
| An onboarding flow that shows the brand a few screens after sign-up | `HEAD` at sign-up, `GET` later |
| A UI that cannot wait, such as a list rendering many brands | `cachedOnly=true`, with a placeholder on `204` |
| A bulk enrichment job | [Batch lookups](https://docs.brandfetch.com/brand-api/batch.md), which never crawl while you wait |
| A one-off lookup where completeness matters | A plain `GET`, retried on `crawl_queued` |


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