# Icon Horse API docs > Free logo and favicon API. Get any company's or product's logo as PNG, WebP, ICO or SVG (16 to 256px) from a domain or a product name. No API key, no signup. Headers say when an image is a placeholder. Base URL: `https://icon.horse`. HTML version: https://icon.horse/docs.html. OpenAPI 3.1 spec: https://icon.horse/openapi.json. ## 1. Quick start ```html Stripe ``` The URL returns Stripe's icon as a PNG, up to 256x256. If the site has no icon, you get a letter tile instead of a broken image (or a 404, if you ask for one). ```sh curl -o stripe.png https://icon.horse/icon/stripe.com/128 curl -o entra.png https://icon.horse/name/microsoft-entra-id/128 curl 'https://icon.horse/api/icons?q=stripe.com&q=Microsoft%20Entra%20ID' ``` ## 2. Icon by domain: /icon/ | URL | Returns | |-----|---------| | `/icon/github.com` | PNG, the best icon the site has, up to 256px | | `/icon/github.com/64` | PNG at 16, 32, 48, 64, 128 or 256px | | `/icon/github.com/256/webp` | WebP at any allowed size | | `/icon/github.com/ico` | ICO with 16, 32 and 48px frames | | `/icon/github.com/svg` | The site's own SVG, or 404 if it has none | Sizes: 16, 32, 48, 64, 128, 256. Formats: `png` (default), `webp`, `ico`, `svg`. ICO and SVG take no size. `?size=64` and `?format=webp` also work and redirect (301) to the path form. Paste anything. Scheme, `www.`, path, port and case are dropped, and the request redirects (301) to one canonical URL: ``` /icon/https://www.Stripe.com/pricing -> 301 /icon/stripe.com /icon/stripe.com?size=64&format=webp -> 301 /icon/stripe.com/64/webp ``` Icon Horse ranks the site's `` tags, `apple-touch-icon`, web app manifest icons and `/favicon.ico`. SVG wins, then the largest size. Parked "domain for sale" pages count as not found. ## 3. Icon by product name: /name/ Many products do not have their own domain. Microsoft Entra ID lives on microsoft.com; CoCounsel lives on thomsonreuters.com. Ask for them by name: ``` https://icon.horse/name/microsoft-entra-id https://icon.horse/name/microsoft-entra-id/128/webp https://icon.horse/icon?q=Microsoft%20Entra%20ID -> 301 /name/microsoft-entra-id ``` The name becomes a lowercase slug. Sizes, formats and variants work the same as `/icon`. Names resolve in this order: 1. Curated catalog: hand-checked name -> domain or image entries for products that public data gets wrong. 2. Wikidata: the query must match whole words in an entity's label or alias, and the entity must have an icon, a logo or an official website. Icon Horse tries the icon, then a square logo, then the website's favicon, then a wide wordmark. No match means not found. Icon Horse never guesses a logo for a name it does not know. ## 4. Variants: trim, weight, pad, bg, tone, fallback Query options that make a row of logos look even. They work on `/icon` and `/name`, at every size and raster format. | Option | Effect | |--------|--------| | `trim=1` | Cut empty border so the mark fills the frame | | `weight=1` | Scale by visual mass, not bounding box, so a solid square and a thin mark look equally heavy. Implies `trim` | | `pad=0..40` | Padding, percent of each side | | `bg=white`, `bg=black`, `bg=` | Background color. Default is transparent. Hex without `#`, 3 or 6 digits | | `tone=mono`, `color=` | Recolor the mark to one color to match a deck. Default color is black or white, whichever reads on `bg` | | `fallback=404` | Return 404 instead of a letter tile when no icon is found | ``` https://icon.horse/icon/bill.com/128?trim=1&weight=1&pad=8&bg=white https://icon.horse/icon/stripe.com/64?bg=0a2540 https://icon.horse/icon/example.com?fallback=404 ``` ## 5. Honest response headers Every image response says what it is. Browsers can read these cross-origin (`Access-Control-Expose-Headers` is set). | Header | Meaning | |--------|---------| | `X-Icon-Fallback` | `true` when the image is a placeholder letter tile | | `X-Icon-Source-Size` | Original size, such as `48x48`, or `vector`. Under 128px looks soft when scaled up | | `X-Icon-Source` | The URL the icon came from | | `X-Icon-Confidence` | 0 to 1. `0` means placeholder | | `X-Icon-Stand-In` | `true` when a styled request got a neutral stand-in tile because no logo exists | | `X-Icon-Warning` | Problems with a styled icon: low contrast on `bg`, or `tone=mono` skipped | ``` $ curl -sI https://icon.horse/icon/stripe.com/64 HTTP/2 200 content-type: image/png x-icon-fallback: false x-icon-source-size: vector x-icon-confidence: 0.9 x-icon-source: https://images.stripeassets.com/.../favicon.svg ``` ```js const res = await fetch('https://icon.horse/icon/acme.example') if (res.headers.get('X-Icon-Fallback') === 'true') { // No real logo. Show a placeholder of your own, or nothing. } ``` ## 6. Icon pages: /site/ A page for people: the icon, the site's name and description, downloads in every size and format, and copy-paste embed code. Example: https://icon.horse/site/stripe.com. Downloads: PNG at 16 to 256px, WebP 256px, ICO, and SVG when the site has one. ## 7. Batch JSON: /api/icons Resolve up to 20 domains or product names in one call. Each result says whether a real icon was found, how confident the match is, where it came from, and the URLs to use. ```sh curl 'https://icon.horse/api/icons?q=stripe.com&q=Microsoft%20Entra%20ID' curl -X POST https://icon.horse/api/icons \ -H 'Content-Type: application/json' \ -d '{"q": ["stripe.com", "Microsoft Entra ID", "CoCounsel"]}' ``` A query with a space, or with no dot, is a product name. Anything else is a domain. Response (shortened): ```json { "results": [ { "query": "Microsoft Entra ID", "kind": "name", "found": true, "fallback": false, "confidence": 0.85, "name": "Microsoft Entra ID", "hostname": "azure.microsoft.com", "via": "wikidata-logo", "source": { "url": "https://commons.wikimedia.org/wiki/Special:FilePath/Microsoft%20Entra%20ID%20color%20icon.svg", "format": "svg", "size": "vector" }, "urls": { "png": "https://icon.horse/name/microsoft-entra-id", "png_64": "https://icon.horse/name/microsoft-entra-id/64", "webp": "https://icon.horse/name/microsoft-entra-id/256/webp", "ico": "https://icon.horse/name/microsoft-entra-id/ico", "svg": "https://icon.horse/name/microsoft-entra-id/svg", "page": null }, "candidates": [] } ] } ``` | Field | Meaning | |-------|---------| | `kind` | `domain` or `name` | | `found` / `fallback` | Whether a real icon exists. When `found` is false, `urls` is null | | `confidence` | 0 to 1, same as `X-Icon-Confidence` | | `via` | How the icon was found: `website`, `catalog`, or a Wikidata source such as `wikidata-logo` | | `source` | Original URL, format and size (`vector` for SVG) | | `urls` | Ready-to-use links. `svg` is null when there is no vector; `page` is null for names | | `candidates` | Other sources considered, for name lookups | | `error` | Set instead of the fields above when a query is empty or the host is rejected | GET responses are cached for 5 minutes. POST is not cached. More than 20 queries returns 400. ## 8. Force a refresh: /refresh/ ``` curl https://icon.horse/refresh/example.com {"refreshed":true,"changed":true,"purged":true} ``` Without a refresh, a changed icon shows up within about 2 days on its own. ## 9. Use in Google Slides, Docs or PowerPoint Slides and documents accept an image by URL. Use a PNG URL; they do not accept SVG or ICO. 1. Google Slides or Google Docs: Insert -> Image -> By URL. Paste `https://icon.horse/icon/stripe.com/256`. 2. PowerPoint or Word on Windows: Insert -> Pictures -> This Device, then paste the same URL into the file name box. On Mac or the web, open the URL in a browser, save the PNG, and insert the file. 3. Product without a domain: use the name form, such as `https://icon.horse/name/microsoft-entra-id/256`. Tip for an even row of logos: add `?trim=1&weight=1&pad=8&bg=white`. Every logo then fills its square the same way on a white tile. ``` https://icon.horse/icon/stripe.com/256?trim=1&weight=1&pad=8&bg=white https://icon.horse/icon/github.com/256?trim=1&weight=1&pad=8&bg=white https://icon.horse/name/microsoft-entra-id/256?trim=1&weight=1&pad=8&bg=white ``` Google Sheets: `=IMAGE("https://icon.horse/icon/stripe.com/64")`. ## 10. For AI agents: MCP, stack and logo sets Agents can call the plain URLs and `/api/icons` above. Three more endpoints are built for agent workflows; https://icon.horse/openapi.json has every parameter. ### MCP server: /mcp A remote Model Context Protocol server at `https://icon.horse/mcp` (Streamable HTTP, no key) with four tools: - `find_logos`: logos for a list of domains or product names, with confidence and fallback flags. - `get_logo_image`: one logo returned as an image, so the agent can look at it before placing it. - `logo_set`: a matched set of logos for one background color and size, with contrast warnings. - `company_stack`: which tools a company uses, with evidence. ```sh claude mcp add --transport http icon-horse https://icon.horse/mcp ``` ### Company stack: /api/stack Which tools a company uses: client portals, practice software, email, CRM, analytics. It reads the homepage, a few likely pages (client portal, pay, contact) and DNS records. Every tool comes with the evidence that put it there (a link and its text, a script, an MX or TXT record) and a confidence. No observed signal, no tool. A missing tool means no evidence was found, not that the company does not use it. ```sh curl 'https://icon.horse/api/stack?domain=stripe.com' ``` ### Logo set: /api/set A row of logos with the same size, visual weight, padding, background and tone. Parameters: `q` (repeat, up to 20), `size`, `bg`, `pad`, `tone` (`color` or `mono`), `color`, `gap`. Each result adds `set_url` (the styled image), `warnings` (for example low contrast on a dark row) and `standIn` (true when no real logo exists and a neutral tile stands in). `row_url` renders the whole row as one PNG. ```sh curl 'https://icon.horse/api/set?q=stripe.com&q=Microsoft%20Teams&size=128&bg=ffffff&pad=8' curl -X POST https://icon.horse/api/set -d '{"q": ["stripe.com", "Microsoft Teams"], "bg": "1f2937", "tone": "mono"}' ``` ## 11. Caching and limits - No API key. CORS is open (`Access-Control-Allow-Origin: *`). - Icons are cached at the edge for 1 day and refreshed in the background. Letter tiles are cached for 5 minutes, so a site that adds an icon shows up fast. - Requests that reach the origin are rate-limited per IP: about 60 per minute for icons and pages, 20 per minute for `/api/icons`, 5 per minute for `/refresh`. Edge cache hits do not count. Over the limit returns 429. - Errors are plain text with a 400, such as `invalid size: must be one of 16, 32, 48, 64, 128, 256`. Contact: hi@icon.horse