---
name: Brandfetch
description: Use when retrieving brand data (logos, colors, fonts, company details), searching for brands by name, enriching transactions with merchant data, grounding AI agents with brand context, or setting up real-time brand updates via webhooks. Agents should reach for this skill when building applications that need verified brand assets, company information, or merchant identification.
metadata:
    mintlify-proj: brandfetch
    version: "1.0"
---

# Brandfetch Skill

## Product summary

Brandfetch provides APIs to retrieve brand assets, company data, and merchant information in real-time. The primary products are: **Logo API** (free CDN for logos), **Brand API** (logos, colors, fonts, firmographics), **Brand Context API** (LLM-ready brand narratives), **Brand Search API** (brand name autocomplete), **Transaction API** (merchant identification from payment text), and **Brandfetch MCP** (AI assistant integration). All APIs authenticate via API key (Bearer token) or client ID. The REST endpoint is `https://api.brandfetch.io/v2/`. Free tier includes 100 requests/month; paid plans offer higher quotas with overage billing. Reference the full API at https://docs.brandfetch.com.

## When to use

Reach for Brandfetch when:
- Displaying company logos or brand assets in a product (use Logo API for free CDN, Brand API for full data)
- Building brand search or autocomplete (Brand Search API)
- Enriching CRM records, leads, or transaction data with logos and company details
- Grounding LLMs or AI agents with brand context (Brand Context API or MCP)
- Identifying merchants from raw payment text (Transaction API)
- Setting up real-time notifications when brand data changes (webhooks on paid plans)
- Querying by domain, stock ticker, ISIN, or crypto symbol
- Migrating from Clearbit's deprecated Logo API

Do not use Brandfetch for: caching logos locally (violates hotlinking policy), replicating the Brandfetch UI, or scraping brand data programmatically.

## Quick reference

### Authentication

| Method | Use case | Example |
|--------|----------|---------|
| **API Key (Bearer)** | Brand API, Brand Context API, Transaction API | `Authorization: Bearer YOUR_API_KEY` |
| **Client ID (query param)** | Logo API, Brand Search API | `?c=YOUR_CLIENT_ID` |

### Identifier types (all APIs support these)

| Type | Format | Example |
|------|--------|---------|
| Domain | `domain/example.com` | `domain/nike.com` |
| Stock/ETF ticker | `ticker/SYMBOL` | `ticker/NKE` |
| ISIN | `isin/CODE` | `isin/US6541061031` |
| Crypto | `crypto/SYMBOL` | `crypto/BTC` |
| Auto-detect | `example.com` (legacy) | `nike.com` (order: domain → ticker → ISIN → crypto) |

**Always use explicit type routes** to avoid naming collisions.

### API endpoints

| API | Method | Endpoint | Free quota |
|-----|--------|----------|-----------|
| Logo API | GET | `https://cdn.brandfetch.io/{type}/{id}?c=CLIENT_ID` | 500k/month |
| Brand API | GET | `https://api.brandfetch.io/v2/brands/{type}/{id}` | 100/month (free) |
| Brand Search API | GET | `https://api.brandfetch.io/v2/search/{name}?c=CLIENT_ID` | 500k/month |
| Brand Context API | GET | `https://api.brandfetch.io/v2/context/{domain}` | 100/month (free) |
| Transaction API | POST | `https://api.brandfetch.io/v2/brands/transaction` | 100/month (free) |

### Logo API parameters

| Parameter | Type | Example | Notes |
|-----------|------|---------|-------|
| `w` | number | `w/400` | Width in pixels; ratio preserved |
| `h` | number | `h/400` | Height in pixels; ratio preserved |
| `type` | enum | `type/icon` | `icon`, `logo`, `symbol` |
| `theme` | enum | `theme/dark` | `dark` or `light` |
| `fallback` | enum | `fallback/lettermark` | `brandfetch`, `transparent`, `lettermark`, `404` |
| `c` | string | `?c=CLIENT_ID` | **Required** client ID |

Example: `https://cdn.brandfetch.io/domain/nike.com/w/128/h/128/theme/dark/type/icon?c=CLIENT_ID`

### Response headers (Brand API, Brand Context API)

| Header | Purpose |
|--------|---------|
| `x-api-key-quota` | Total monthly quota |
| `x-api-key-approximate-usage` | Current month's usage |

Monitor these to avoid hitting quota limits.

## Decision guidance

### When to use Logo API vs Brand API

| Scenario | Use Logo API | Use Brand API |
|----------|-------------|--------------|
| Just need a logo image | ✅ Free, CDN-hosted | ❌ Overkill |
| Need logos + colors + fonts + company data | ❌ Not available | ✅ Single call |
| Building autocomplete | ❌ Not for search | ✅ Use Brand Search API |
| Embedding in HTML `<img>` tag | ✅ Direct hotlink | ❌ Requires server call |
| Need real-time updates | ❌ Static CDN | ✅ Use webhooks |

### When to use Brand Context API vs Brand API

| Need | Use Brand Context API | Use Brand API |
|------|----------------------|--------------|
| LLM prompt context | ✅ Markdown/JSON narrative | ❌ Structured data only |
| Brand voice & positioning | ✅ Narrative summary | ❌ Not included |
| Logo files & colors | ❌ Not included | ✅ Full asset data |
| Fast response (cached only) | ✅ `cachedOnly=true` | ❌ Always crawls |

### When to use REST vs GraphQL

| Scenario | REST | GraphQL |
|----------|------|---------|
| Simple single-field queries | ✅ Simpler | ❌ Overkill |
| Complex multi-field requests | ❌ Over-fetching | ✅ Exact fields |
| Exploring schema interactively | ❌ Manual | ✅ Apollo Studio |

## Workflow

### 1. Retrieve brand data by domain

```bash
curl --request GET \
  --url https://api.brandfetch.io/v2/brands/domain/nike.com \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

Response includes: `logos`, `colors`, `fonts`, `images`, `company` (employees, industries, location, founded year), `qualityScore`, `description`.

### 2. Search for a brand by name

```bash
curl --request GET \
  --url "https://api.brandfetch.io/v2/search/nike?c=YOUR_CLIENT_ID"
```

Returns array of matching brands with `domain`, `name`, `icon`, `brandId`. Use `brandId` or `domain` for subsequent Brand API calls.

### 3. Get brand context for LLM

```bash
curl --request GET \
  --url https://api.brandfetch.io/v2/context/nike.com \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: text/markdown'
```

Returns Markdown (or JSON) with `identity`, `positioning`, `brand` (voice & style). Perfect for AI prompts.

### 4. Identify merchant from transaction

```bash
curl --request POST \
  --url https://api.brandfetch.io/v2/brands/transaction \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "transactionLabel": "STARBUCKS 1523 OMAHA NE",
    "countryCode": "US"
  }'
```

Returns matched brand domain and full brand data.

### 5. Embed logo in HTML

```html
<img
  src="https://cdn.brandfetch.io/domain/nike.com/w/128/h/128/theme/dark/type/icon?c=YOUR_CLIENT_ID"
  alt="Nike logo"
/>
```

Must be embedded in `<img>` tag (not fetched programmatically). Requires `Referer` header and `Referrer-Policy` set to `origin`, `origin-when-cross-origin`, `strict-origin`, `strict-origin-when-cross-origin`, or `unsafe-url`.

### 6. Set up webhooks for real-time updates (paid plans only)

Register endpoint via GraphQL mutation, subscribe to brands. Receive `brand.updated`, `brand.company.updated` events with `delta` showing what changed. Implement async queue to handle spikes. Retry logic: up to 15 retries over ~8 days.

## Common gotchas

- **Auto-detection collisions**: `BTC` could match a domain before a crypto symbol. Always use explicit type routes (`crypto/BTC`, `domain/example.com`).
- **Logo API hotlinking policy**: URLs must be embedded in `<img>` tags with proper `Referer` header. Programmatic fetches return `302` redirect. For server-side caching, contact sales.
- **Quota exhaustion**: Free tier is 100 requests/month for Brand/Context APIs, 500k/month for Logo/Search APIs. Monitor `x-api-key-approximate-usage` header. Hitting quota returns `429`.
- **Brand Search API caching**: Logo URLs expire after 24 hours; refetch them. Other data should not be cached.
- **Webhook subscriptions cost credits**: Each brand subscription costs 1 credit on creation + 1 credit/month renewal. Subscriptions to `brandfetch.com` are free.
- **Webhook auto-disable**: If endpoint fails for 14 consecutive days, webhook is disabled. Fix endpoint and re-enable with `updateWebhook`.
- **Overage billing**: Requests over quota are charged at overage rate (not blocked). Set spending limit to `$0` to disable overage.
- **Brand Context API live crawling**: By default, unknown domains are crawled (slow). Use `cachedOnly=true` for instant response if not cached.
- **NSFW filtering**: By default, some NSFW brands return `404`, others return with `isNsfw: true`. Use `allowNsfw=true` or `allowNsfw=false` to control.
- **Transaction API country code**: Always provide `countryCode` to narrow merchant locale (e.g., `"US"` for US merchants).

## Verification checklist

Before submitting work with Brandfetch:

- [ ] API key or client ID is valid and not expired (test with `brandfetch.com`)
- [ ] Identifier type is explicit (e.g., `domain/`, `ticker/`, not auto-detect) to avoid collisions
- [ ] Logo API URLs are embedded in `<img>` tags, not fetched programmatically
- [ ] `Referrer-Policy` header is set correctly for Logo API hotlinking
- [ ] Quota usage is monitored; no 429 errors in logs
- [ ] Webhook endpoints return 2xx status within 16 seconds (if using webhooks)
- [ ] Brand Search API logo URLs are refetched every 24 hours (not cached)
- [ ] Error handling covers 400 (bad request), 401 (auth), 404 (not found), 429 (quota)
- [ ] For LLM workflows, Brand Context API is used with `Accept: text/markdown` for prompts
- [ ] Transaction API includes `countryCode` for merchant identification
- [ ] Webhook subscriptions are removed when no longer needed (to avoid monthly charges)

## Resources

- **Full API navigation**: https://docs.brandfetch.com/llms.txt
- **Brand API reference**: https://docs.brandfetch.com/reference/brand-api-domain
- **Logo API parameters**: https://docs.brandfetch.com/logo-api/parameters
- **Brand Context API**: https://docs.brandfetch.com/brand-context-api/overview
- **Webhook setup**: https://docs.brandfetch.com/delivery-methods/webhooks/setup
- **Developer Dashboard**: https://developers.brandfetch.com (manage API keys, quotas, webhooks)

---

> For additional documentation and navigation, see: https://docs.brandfetch.com/llms.txt