# favi
> Public favicon picker and HTTP API for free icon libraries (Lucide, Tabler, Phosphor, Hugeicons free, Remix Icon). Search icons, recolor them, compose initials, and download a favicon zip (SVG + ICO + apple-touch + PWA / maskable pack).

Use the HTTP API for agents. Prefer curl over browser automation. No auth required. Brand: getfavi. Base URL: https://getfavi.vercel.app

Canonical API version is **v1** at `/api/v1/`. Unversioned `/api/*` is a stable alias. Breaking changes will ship as `/api/v2/` with `Deprecation` and `Sunset` headers. See [favi REST versioning](https://getfavi.vercel.app/docs/versioning).

Production is rate-limited by client IP (Vercel WAF). Responses include `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit`, `RateLimit-Policy`, and `Retry-After` on HTTP 429. Local `http://127.0.0.1:3000` is not limited. See [favi rate limits](https://getfavi.vercel.app/docs/rate-limits).

| Method | Path | Limit |
| --- | --- | --- |
| `POST` | `/api/v1/export` | 20 / 60s / IP |
| `GET` | `/api/v1/icons`, `/api/v1/icons/:library/:name` | 120 / 60s / IP |
| `GET` | `/api/v1/health`, `/api/v1/libraries` | 40 / 60s / IP |

This is the Next.js app (public source). Local override: http://127.0.0.1:3000

## When to use favi

Use favi when the job is to search a free icon library and export a favicon package (SVG, ICO, apple-touch, PWA / maskable) via HTTP. Call `GET /api/v1/icons` then `POST /api/v1/export`. Do not drive the browser UI.

Do not use favi for an MCP server, OAuth, webhooks, a paid icon marketplace, or generating original artwork. Those are not part of this product.

## Install agent skill

```bash
npx skills add JoeBuildsStuff/favi-next
```

Install a single skill:

```bash
npx skills add JoeBuildsStuff/favi-next --skill favi
```

## favi developer resources

- [getfavi (favi) developer resources](https://getfavi.vercel.app/docs): API docs, authentication, OpenAPI spec, auth docs, webhooks, MCP server notes (Vercel-hosted origin)
- [favi developers](https://getfavi.vercel.app/developers): Same getfavi developer resources index
- [favi developer resources (for-agents)](https://getfavi.vercel.app/for-agents): Same getfavi developer resources index
- [favi agents](https://getfavi.vercel.app/agents): Markdown-friendly agent onboarding and API workflow
- [favi API docs](https://getfavi.vercel.app/docs/api): HTTP API reference
- [Vercel developer resources](https://getfavi.vercel.app/vercel): getfavi API docs, OpenAPI spec, auth docs, webhooks, MCP server on Vercel
- [Vercel developer resources for getfavi](https://getfavi.vercel.app/docs/vercel): Same Vercel developer resources index
- [favi authentication (auth docs)](https://getfavi.vercel.app/docs/auth): No API keys, OAuth, or login
- [favi webhooks](https://getfavi.vercel.app/docs/webhooks): Not offered; use the HTTP API
- [favi MCP server](https://getfavi.vercel.app/docs/mcp): Not offered; use the HTTP API and skill
- [favi OpenAPI spec](https://getfavi.vercel.app/openapi.json): OpenAPI 3.1 for the public HTTP API (path `/api/v1/` plus aliases)
- [favi OpenAPI spec (docs)](https://getfavi.vercel.app/docs/openapi): Human page for the spec
- [favi REST versioning](https://getfavi.vercel.app/docs/versioning): `/api/v1/` and deprecation (`Deprecation` / `Sunset`)
- [favi rate limits](https://getfavi.vercel.app/docs/rate-limits): RateLimit headers and 429 Retry-After
- [favi API errors](https://getfavi.vercel.app/docs/errors): RFC 9457 problem+json codes and hints
- [favi API catalog](https://getfavi.vercel.app/.well-known/api-catalog): RFC 9727 linkset
- [favi API catalog (Markdown)](https://getfavi.vercel.app/.well-known/api-catalog.md): Human- and agent-readable API catalog
- [favi HTTP API index](https://getfavi.vercel.app/api/v1): JSON list of endpoints
- [getfavi](https://getfavi.vercel.app/getfavi): Brand page for getfavi.vercel.app
- [About getfavi](https://getfavi.vercel.app/about): Product and maintainer
- [Contact getfavi](https://getfavi.vercel.app/contact): GitHub Issues
- [getfavi privacy](https://getfavi.vercel.app/privacy): Request handling and data
- [Agent skill (live)](https://getfavi.vercel.app/skills/favi/SKILL.md): Step-by-step API workflow for searching icons and exporting favicons
- [GitHub skill](https://github.com/JoeBuildsStuff/favi-next/tree/main/skills/favi): Canonical `SKILL.md` in this public repo
- [Human UI](https://getfavi.vercel.app/): Visual search, compose, download zip (canonical getfavi domain)
- [Sitemap](https://getfavi.vercel.app/sitemap.xml): Canonical public URLs

## API
- [Health](https://getfavi.vercel.app/api/v1/health): Service status and indexed icon count
- [Libraries](https://getfavi.vercel.app/api/v1/libraries): Available packs, licenses, styles
- [Search icons](https://getfavi.vercel.app/api/v1/icons?q=image&limit=12): `q`, `library`, `style`, `limit` (1–300), `offset` (`q` expands curated synonyms such as photo→image, trash→delete)
- [Exact icon](https://getfavi.vercel.app/api/v1/icons/lucide/image?style=outline): `GET /api/v1/icons/:library/:name?style=`
- [Export favicon](https://getfavi.vercel.app/api/v1/export): `POST` JSON `{library,name,style}` **or** `{text}` (1–2 initials) plus `{bg,bg_mode,bg_to,bg_angle,fill,stroke,padding,stroke_scale,shape,include_dark_mode,dark_bg,dark_bg_to,dark_fill,dark_stroke,site_name}` → zip always includes SVG/ICO/apple-touch/PWA pack (`README.txt` includes HTML / Next.js install notes; optional `favicon-dark.svg` + `prefers-color-scheme` media links; optional 2-stop linear plate via `bg_mode=linear`; initials via `text`)

## Optional
- [App source](https://github.com/JoeBuildsStuff/favi-next): Public Next.js repository
- Shareable UI config: `https://getfavi.vercel.app/?library=tabler&name=icons&style=outline`