Fivicon Documentation

Discover & scanning

POST /api/v1/discover is the entry point. Give it a domain and Fivicon scans the live site for logo-shaped assets — favicons, header logos, Open Graph images, web app manifest icons — and records what it found.

A discover call is also how you refresh a domain: calling it again re-scans the site and appends a new changelog entry if anything changed. It's safe to call on a domain you don't manage — Fivicon scans only what's publicly reachable, and skips domains whose robots.txt blocks scraping.

A domain doesn't need to be watched for you to discover it — discovery and watching are separate: discovery gets you the data, watching keeps it fresh automatically.

Logos & scoring

Every asset Fivicon finds is one logo variant with a type (primary, icon, wordmark, favicon), a format (svg, png, …), and a score from 0–100.

The score is a sum of signals, not a black box:

• Format — vector formats score higher than raster; they scale cleanly at any size.
• Resolution — bigger, sharper raster assets beat tiny or blurry ones.
• Relevance — how confident Fivicon is that this asset actually is the brand mark, not incidental site art.
• File size — reasonable file weight for something that's going to be embedded, not a multi-megabyte export.

Penalties subtract points for things like a broken URL or a blocked fetch. The best logo for a domain is whichever variant has the highest score after penalties — that's what an embed serves by default, unless you pin a specific one.

Companies & watchlist

A company, in Fivicon, is just a domain with data on file — whatever you've discovered or looked up. Your watchlist is the subset of those domains Fivicon actively keeps fresh: watched domains get periodically re-scanned on their own, without you calling /discover again by hand.

Add a domain to your watchlist with POST /api/v1/me/watchlist, remove it with DELETE /api/v1/me/watchlist/{domain}. Every domain you've discovered still shows up in Companies whether or not it's watched — watching just adds the "keep this current for me" guarantee.

Changelog

Each re-scan of a domain (manual or from the watchlist) can produce a changelog entry: GET /api/v1/catalog/domains/{domain}/changelog. An entry's summary reports what moved — added, removed, score_updated, asset_updated, or url_broken counts — or nothing at all if the re-scan found the site unchanged.

This is what a rebrand looks like from the API's side: a company swaps its logo, the next watchlist scan picks it up, a changelog entry records the change, and the domain's status turns from Healthy to Changed until someone looks at it.

Logo preference

By default, an embed serves whichever logo variant currently scores highest — fully automatic, and it follows the score if a better asset shows up later. If you'd rather lock a domain to one specific logo (a particular format, or a specific variant you've picked by eye), set a preference:

• PUT /api/v1/me/logo-preferences/{domain} — { "logo_url": "…" } to lock to that exact asset.
• DELETE /api/v1/me/logo-preferences/{domain} — clear the lock and go back to automatic.

The preference is per your account and per domain — it never changes what's in the shared catalog for that domain, only which asset your embeds resolve to.

Three ways to authenticate

Pick whichever fits where the call is coming from:

• Allowlist — the browser's own Origin/Referer header matches a domain you've allowed. No key ever touches the page; this is the right choice for embedding a logo directly in a site you control.
• API key — append ?api_key=… to the static embed URL. Useful anywhere an allowlisted Origin/Referer isn't available (native apps, server-rendered emails, tools that strip Referer).
• Bearer token — your account's access token, sent as Authorization: Bearer …, for server-side calls against /api/v1/… (discover, catalog, watchlist, preferences, admin).

Discover a domain

curl -X POST https://api.fivicon.com/api/v1/discover \
  -H "Authorization: Bearer $FIVICON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"stripe.com"}'

Then read back what it found any time:

curl https://api.fivicon.com/api/v1/catalog/domains/stripe.com \
  -H "Authorization: Bearer $FIVICON_TOKEN"

Embed a logo

The CDN serves the resolved logo for a domain — automatic best match, or your pinned preference if you set one — behind a static URL:

<img src="https://static.fivicon.com/stripe.com?api_key=YOUR_KEY" alt="Stripe" />

If stripe.com is on your allowed domains list and the request's Origin/Referer matches, you can drop the ?api_key= entirely.

Pin a specific logo

curl -X PUT https://api.fivicon.com/api/v1/me/logo-preferences/stripe.com \
  -H "Authorization: Bearer $FIVICON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"logo_url":"https://.../stripe-icon.svg"}'

Reset to automatic scoring at any time:

curl -X DELETE https://api.fivicon.com/api/v1/me/logo-preferences/stripe.com \
  -H "Authorization: Bearer $FIVICON_TOKEN"

Watch companies

curl -X POST https://api.fivicon.com/api/v1/me/watchlist \
  -H "Authorization: Bearer $FIVICON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"stripe.com"}'

Watched domains are re-scanned for you; everything else is scan-on-demand only.

Allow an embed domain

curl -X POST https://api.fivicon.com/api/v1/me/allowed-domains \
  -H "Authorization: Bearer $FIVICON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"app.mycompany.com"}'

Lowercase hostname only — no scheme, no path. Wildcards (*.mycompany.com) and localhost both work. Max 50 per account.

Endpoints

All /api/v1/… calls except the CDN embed URL take a Bearer token. See Authentication for the embed URL's own options.