API reference

The icon and Open Graph image endpoints, their parameters, caching and allowed origins.

The image API lives at https://logo.parsew.com. It has two endpoints, both GET (and HEAD), both authenticated with a publishable key in the token query parameter.

Endpoint	Returns
`GET /{domain}`	The company’s icon, square, 128 pixels by default
`GET /og/{domain}`	The site’s Open Graph image, 1200 pixels wide by default

{domain} is a bare domain like stripe.com. A scheme, a path and a leading www. are ignored: https://www.stripe.com/pricing and stripe.com are the same image.

Parameters

Parameter	Values	Default	Meaning
`token`	`pk_…`	required	Your publishable key
`size`	`1`–`2048`	`128` (icon), `1200` (og)	Width and height of an icon; width of an Open Graph image, which keeps its aspect ratio. Out-of-range values are clamped
`format`	`png`, `webp`, `jpg`	`png`	Output format. `jpg` gets a white background. Anything else means `png`
`theme`	`light`, `dark`	`light`	The surface the icon is shown on (icons only). Sites that declare a dark-mode icon get it on `dark`, and single-colour mask icons are tinted to fit
`fallback`	`monogram`, `404`	`monogram` (icon), `404` (og)	What to send when there’s no image: a monogram of the domain’s initial, or a `404`
`retina`	`true`	off	Twice the pixels at the same `size`
`v`	any string	none	A version. A new value makes Parsew fetch the site’s image again

https://logo.parsew.com/github.com?token=pk_XXXXXXXXXXXX&size=64&format=webp&theme=dark
https://logo.parsew.com/og/github.com?token=pk_XXXXXXXXXXXX&size=600&format=jpg

What you get back

An image: image/png, image/webp or image/jpeg at the size you asked for.
An SVG: when the icon itself is an SVG (many brands ship one), it is served as sanitized image/svg+xml whatever the format, since vectors scale to any size. Scripts, event handlers and external references are stripped, and it’s served with Content-Security-Policy: sandbox.
A monogram: an SVG with the domain’s first letter, when no icon is found and fallback is monogram.
A 404: when nothing is found and fallback is 404.

Every response carries Access-Control-Allow-Origin: *, so the images also work in <canvas> and fetch.

How an icon is found

The home page’s declarations: SVG icons, touch icons, <link rel="icon">, Safari mask icons, JSON-LD logos, the web app manifest, browserconfig tiles and well-known paths such as /apple-touch-icon.png.
A curated vector mark (thesvg) for well-known brands, which outranks the site’s own files.
Candidates are scored by source, resolution, squareness and fit for the requested theme; the best one wins.
When the site yields nothing usable: the curated mark, then Google’s and DuckDuckGo’s favicon services, then the fallback.

Open Graph images come from the page’s og:image.

Caching

The source image is stored once per domain (and theme) and refreshed from the site about once a week. A site without an image is asked again after an hour.
Each rendition (a domain, size, format, theme, fallback, retina, v) is cached at Cloudflare’s edge for a day; monograms and 404s for an hour. The key is checked before a cached image is served, so a deleted key stops working everywhere.

Allowed origins

A key with an empty allowed-origins list works on any site. Add hostnames on the Keys page to limit it:

example.com allows exactly that host.
*.example.com allows its subdomains (not example.com itself).

The browser’s Origin header (or else Referer) decides. Requests with neither, such as from your server or curl, are always allowed, and so is localhost and every *.localhost, for local development. A page on a host that isn’t listed gets 401 Origin not allowed.

Usage and limits

Every request that passes the key and origin checks counts toward your plan’s monthly requests, whether it’s served from the cache or not. Going over never blocks or degrades an image: the dashboard shows a banner and the account owner gets one email per month. See your usage on the Usage page.