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

# Brand API

> The brand layer for modern products

[Brand API](https://brandfetch.com/developers/brand-api) provides programmatic access to any company's brand assets through a single API call. This includes their latest logos, color schemes, fonts, images, and other firmographic information.

Brand API works in real-time, if a brand is not part of our dataset, it will index the information live ensuring **global coverage** for businesses of all sizes, geography and industries.

## Implementation guide

<Steps>
  <Step title="Get your API key">
    You’ll need to create an account on our [Developer Portal](https://developers.brandfetch.com/register). Creating an account is quick and easy, and will give you access to your dashboard where you’ll find your API key.

    <Tip>
      Building an agent that runs without a human in the loop? Skip the account: [pay per request with x402 or MPP](/agents/pay-per-request), or [buy standing access](/agents/overview#standing-access) with prepaid credits.
    </Tip>
  </Step>

  <Step title="Make your first API call">
    The Brand API supports multiple identifier types (domain, website URL, email address, Stock or ETF ticker, ISIN, Crypto symbol). Authentication is done by passing your API key as a [Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/).

    <CodeGroup>
      ```curl Domain theme={null}
      curl --request GET \
      --url https://api.brandfetch.io/v2/brands/domain/nike.com \
      --header 'Authorization: Bearer <token>'
      ```

      ```curl Ticker theme={null}
      curl --request GET \
      --url https://api.brandfetch.io/v2/brands/ticker/NKE \
      --header 'Authorization: Bearer <token>'
      ```

      ```curl ISIN theme={null}
      curl --request GET \
      --url https://api.brandfetch.io/v2/brands/isin/US6541061031 \
      --header 'Authorization: Bearer <token>'
      ```

      ```curl Crypto theme={null}
      curl --request GET \
      --url https://api.brandfetch.io/v2/brands/crypto/BTC \
      --header 'Authorization: Bearer <token>'
      ```

      ```curl Email theme={null}
      curl --request GET \
      --url https://api.brandfetch.io/v2/brands/john@example.brandfetch.com \
      --header 'Authorization: Bearer <token>'
      ```

      ```curl Website URL theme={null}
      curl --request GET \
      --url https://api.brandfetch.io/v2/brands/https://www.brandfetch.com/developers/pricing \
      --header 'Authorization: Bearer <token>'
      ```

      ```curl Auto-detection (legacy) theme={null}
      curl --request GET \
      --url https://api.brandfetch.io/v2/brands/nike.com \
      --header 'Authorization: Bearer <token>'
      ```
    </CodeGroup>

    <Note>
      The shorthand route `/v2/brands/{identifier}` (without a type prefix) is still supported and auto-detects the identifier type (in the order: domain → ticker → ISIN → crypto), but explicit type routes are recommended to avoid naming collisions.

      The API reads an identifier that contains `@` as an email address and resolves it to its registrable domain. `john@example.brandfetch.com` returns the same response as `brandfetch.com`. The API does not store the address. Your request logs show only the resolved domain. Email addresses work on the shorthand route only.

      The API reads an identifier that starts with `http://` or `https://` (or the percent-encoded `https%3A%2F%2F`) as a website URL. The API also reads a domain with a path (`brandfetch.com/developers/pricing`) as a website URL. The API resolves the URL to the registrable domain of its host, so `https://www.brandfetch.com/developers/pricing` returns the same response as `brandfetch.com`. The API does not store the URL. Your request logs show only the resolved domain. Website URLs work on the shorthand route only.
    </Note>

    If you only have company names, use the [Brand Search API](/brand-search-api/overview) to match brand names to the most likely URLs.
  </Step>

  <Step title="Test and deploy">
    All requests for the domain <b>brandfetch.com</b> are free and will not count towards your usage/quotas. You can make as many requests to the Brandfetch’s brand as you need while you iterate on and test your integration.

    Once you are ready to go live, replace <b>brandfetch.com</b> with the identifier you want to look up: a domain name, website URL, email address, Stock/ETF ticker, ISIN, or Crypto symbol.

    <Tip>
      If you have custom requirements, or any questions [contact
      us](https://brandfetch.com/developers/contact/sales).
    </Tip>
  </Step>
</Steps>

## Prefetching brands

Brand API works in real time: the first request for a brand nobody has asked for before crawls it live, which may take a moment. When you know ahead of time which brand you will need — a user has just signed up, and their brand screen is a few steps away — ask for it in advance with a `HEAD` request on the same route:

```curl Prefetch at signup theme={null}
curl --head \
--url https://api.brandfetch.io/v2/brands/jane@example.brandfetch.com \
--header 'Authorization: Bearer <token>'
```

The response carries no body. The status code is the answer:

| Status | Meaning |
| - | - |
| `200` | We hold the brand. A `GET` is answered from our store. |
| `202` | We do not hold it yet, and a crawl has been queued. Make the `GET` when you need the data. |
| `404` | Nothing can be fetched for the identifier: an unknown ticker or ISIN, or a brand that has been removed. |
| `403` | Prefetching is available on paid plans. The `x-bf-error` header reads `paid_plan_required`. |
| `503` | The crawl could not be queued. Retry later; the `x-bf-error` header reads `temporarily_unavailable`. |

`HEAD` accepts every identifier the `GET` does — a domain, an email address, a brand ID, a ticker, an ISIN or a crypto symbol. Prefetch requests never count towards your quota. Prefetch requests may be throttled to prevent abuse and ensure quality of service. See the [reference](/reference/brand-api-prefetch) for the full contract.

## Skip crawling (cached only)

By default, a brand that is not yet part of the dataset is indexed live. This guarantees global coverage, but a live crawl can take several seconds. A crawl still running when the request has to be answered carries on in the background, and the request is answered `404` with the header `x-bf-error: crawl_queued`: retry in a minute or two; if the brand could be collected, it is served.

When latency matters more than coverage, such as enriching records in bulk or rendering a screen that cannot wait, set the `cachedOnly` query parameter to `true`. The API then answers from its store alone, instantly and **without crawling**:

* A brand that is already indexed is returned immediately (`200`), exactly as a normal request would return it.
* A brand that is not yet indexed is answered with `204 No Content` instead of being crawled live.

<CodeGroup>
  ```curl Cached only theme={null}
  curl --request GET \
  --url 'https://api.brandfetch.io/v2/brands/domain/nike.com?cachedOnly=true' \
  --header 'Authorization: Bearer <token>'
  ```
</CodeGroup>

`cachedOnly` works on every `GET /v2/brands` route and with every identifier type. On a ticker, ISIN, or crypto symbol that is not yet indexed, the API skips the identifier resolution too and answers `204`. A `204` has no body, so check the status code before parsing the response. A `204` does not count towards your quota.

To index a brand ahead of time, make a standard request without `cachedOnly`, or [prefetch it](#prefetching-brands) with a `HEAD` request. Once the brand is indexed, `cachedOnly=true` requests return it instantly.

## Quotas and usage

When you sign up for a free developer account, you get 100 free requests.

`HEAD` requests (see [Prefetching brands](#prefetching-brands)) and `204` responses to `cachedOnly` requests (see [Skip crawling](#skip-crawling-cached-only)) are not counted. If you need to make more requests, please upgrade to a paid plan. When upgrading, you can confirm your quota by looking at the `x-api-key-quota` response header. To see your current month's usage, look for the `x-api-key-approximate-usage` response header.

We will also send you an email warning you upon reaching 80% of your quota. The API will return an HTTP status code 429 when the quota has been reached.

In addition to a usage quota we also apply a request throughput limit to protect our service from abuse. By default, throughput is limited to a sustained 100 requests/second with some flexibility to accommodate bursts (30,000 requests / rolling 5 minute hard limit). You'll receive an HTTP status code 429 when you exceed this limit.

If your use-case requires higher throughput limits, [contact us](https://brandfetch.com/developers/contact/sales).

## Overage billing

When you purchase a subscription plan, you are allotted a quota depending on the payment plan. When you make more API requests than your quota allows, rather than blocking requests which are over your quota, we apply overage billing. This means that you'll never have any unexpected downtime. Requests over your quota are charged at an overage-fee rate.

To set a spending limit, head to the [Developer Dashboard](https://developers.brandfetch.com/dashboard/billing) and set a hard spending limit. Set this to \$0 if you want to disable overage.

Overage billing is not available on the free plan. To start using overage, please upgrade first to one of the paid plans.

## API Reference

For more details, refer to our [API Reference](/reference/brand-api).


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