brandKIT

Open-source logo API. Give it a domain, it returns a clean logo.

brandKIT is a small, agent-friendly HTTP API that returns a clean logo for any public domain. It's built with Next.js 16, runs anywhere Node runs, and ships with zero external service dependencies. You can run it in five minutes on your laptop or deploy it to Vercel with one click.

---

Quickstart

git clone https://github.com/z1fex/brandKIT
cd brandKIT
npm install
npm run dev

Then:

curl "http://localhost:3000/api/v1/logo?domain=stripe.com"

{
  "domain": "stripe.com",
  "logo_url": "http://localhost:3000/api/v1/logo/image?domain=stripe.com",
  "source": "apple-touch-icon",
  "format": "png",
  "width": 256,
  "height": 256,
  "content_type": "image/png",
  "cached": false,
  "fetched_at": "2026-04-23T12:34:56.000Z"
}

Want just the image bytes for an <img> tag?

<img src="https://your-host/api/v1/logo/image?domain=stripe.com" alt="Stripe" />

---

Features

• Smart fallback chain — apple-touch-icon → <link rel="icon"> → og:image → twitter:image → favicon → generated placeholder. Nothing returns 404.
• Zero config — works with no env vars at all. Override what you need.
• Pluggable cache — memory (default), filesystem, or supabase. Swap with one env var.
• Agent-ready — predictable JSON schema, clean error shape, no auth by default.
• Self-hostable anywhere — Next.js app, no database required.
• Optional API key — set API_SECRET_KEY to gate the endpoint; leave unset to run it open.
• Per-IP rate limiting — 60/min default, configurable.
• MIT licensed — use it however you want.

---

Endpoints

Method	Path	Returns
GET	/api/v1/logo	JSON: logo metadata + image URL
GET	/api/v1/logo/image	Raw image bytes (PNG or SVG)
GET	/api/v1/health	Health check + active cache adapter name

Visit /docs in a running instance for the full reference.

---

Configuration

Every option is an environment variable. All are optional.

Variable	Default	Purpose
API_SECRET_KEY	unset	If set, requires x-api-key header on every request.
RATE_LIMIT_PER_MINUTE	60	Per-IP limit.
CACHE_TYPE	memory	memory, filesystem, or supabase.
CACHE_TTL_DAYS	30	How long cached logos live.
MAX_LOGO_SIZE_BYTES	2097152	2 MB upstream image cap.
REQUEST_TIMEOUT_MS	5000	Outgoing HTTP timeout.
OUTPUT_SIZE	256	Default output dimension in px.
FILESYSTEM_CACHE_DIR	./.cache/brandkit	Where the filesystem adapter writes.
SUPABASE_URL	unset	Required when CACHE_TYPE=supabase.
SUPABASE_SERVICE_ROLE_KEY	unset	Required when CACHE_TYPE=supabase.
SUPABASE_STORAGE_BUCKET	logos	Storage bucket name.
BRANDKIT_USER_AGENT	brandKIT/1.0 ...	UA sent when scraping.

See .env.example for a copy-pasteable template.

---

Self-hosting

Vercel (one click)

Or import the repo manually in the Vercel dashboard. No env vars required.

Docker

docker build -t brandkit .
docker run -p 3000:3000 brandkit

Any Node host

brandKIT is a standard Next.js app. Run npm run build && npm start on Railway, Fly.io, Render, or your own VPS.

Supabase cache (optional)

When you want persistent, multi-instance cache:

1. Create a Supabase project.

2. Create a storage bucket named logos (public read).

3. Run this SQL to create the metadata table:

   create table brandkit_logo_cache (
     domain text primary key,
     source text not null,
     content_type text not null,
     width int not null,
     height int not null,
     format text not null,
     fetched_at timestamptz not null default now(),
     expires_at timestamptz not null
   );

4. Set CACHE_TYPE=supabase, SUPABASE_URL, and SUPABASE_SERVICE_ROLE_KEY in your env.

---

Agent integration

brandKIT is designed to drop into any tool-use system. A minimal schema (Anthropic / OpenAI compatible):

{
  "name": "get_company_logo",
  "description": "Fetch a company's logo given its domain. Returns a URL and metadata.",
  "input_schema": {
    "type": "object",
    "properties": {
      "domain": {
        "type": "string",
        "description": "The company's domain, e.g. 'stripe.com'"
      }
    },
    "required": ["domain"]
  }
}

Your tool handler calls GET /api/v1/logo?domain=<value> and returns the JSON to the model.

---

Contributing

See CONTRIBUTING.md. Issues and PRs are welcome — especially new cache adapters and fallback sources for sites that currently fail.

---

License

MIT — use it anywhere, sell products built on top of it, fork it, rebrand it. No strings attached.