Generative Icons

Developers

Everything below is free, read-only and needs no sign-in: the same library the website shows, ranked the same way (names, search terms, typos and plain-language needs). An optional, anonymous agent credential raises the rate limit (https://generativeicons.com/auth.md).

MCP servers#

Server URL Tools
Icons https://generativeicons.com/mcp search_icons, get_icon, list_categories, read_guide
Guides https://generativeicons.com/mcp/docs search_guides, read_guide

Both use Streamable HTTP (MCP 2025-06-18; 2025-03-26 and 2024-11-05 also answer) and expose the guides as resources. Server cards: https://generativeicons.com/.well-known/mcp/server-card.json and https://generativeicons.com/mcp/docs/server-card. In Claude Code:

Terminal
claude mcp add --transport http generative-icons https://generativeicons.com/mcp

A2A agent#

https://generativeicons.com/a2a answers A2A messages (JSON-RPC; A2A 1.0 SendMessage, and 0.3 message/send) at once, with a Markdown part and a JSON data part. Agent card: https://generativeicons.com/.well-known/agent-card.json. Its skills:

Skill Send Reply
find-icons What an icon should mean, e.g. "upload failed" The best matches with their pages and files
icon-details An icon id, e.g. "trash", or a data part {"id": "trash"} Files, sha256, install commands and code
search-guides A question, e.g. "How do I change an icon's color in React?" The guide sections that answer it

A data part {"skill": "...", "query": "...", "category": "...", "limit": 10} picks the skill explicitly. There are no tasks and no streaming.

REST API#

Base URL https://generativeicons.com/api/v1, described at https://generativeicons.com/openapi.json (OpenAPI 3.1).

Request Answer
GET /api/v1/icons?q=<meaning>&category=&limit= The best matches for what an icon should mean
GET /api/v1/icons?limit=&offset= Every icon, a page at a time
GET /api/v1/icons/<id> One icon: description, states, styles, motions, file URL and sha256, install commands, and code for JavaScript, React, iOS and Android
GET /api/v1/categories The categories with their icon counts
GET /api/v1/search?q= Semantic similarity alone (the website fuses it with word matching)
Terminal
curl 'https://generativeicons.com/api/v1/icons?q=upload+failed&limit=3'

Icon files are at https://generativeicons.com/assets/.lottie, the full catalog at https://generativeicons.com/catalog.json, and every guide as Markdown at https://generativeicons.com/docs/.md.

Errors#

Every error is JSON: {"error": {"code": "...", "message": "..."}}.

Status Code When
400 invalid_parameter A parameter is missing or unknown
404 not_found No such icon, endpoint or file
401 invalid_token A token of this site's that expired or was altered (no token is fine)
405 method_not_allowed Anything but GET (the API is read-only)
429 rate_limited Past the limit; wait the seconds in Retry-After
503 unavailable The library or semantic search could not be read; retry

Limits#

Each client (IP address) may make 120 requests a minute across the API, both MCP servers and the A2A agent. An agent that registers (anonymous, no sign-in: https://generativeicons.com/auth.md) and sends its access token gets its own 600 a minute. Every response carries RateLimit-Policy; past the limit the answer is 429 with Retry-After.

Versions and deprecation#

  • Paths carry the major version: /api/v1/. Additions (new endpoints, fields or parameters) never break v1.
  • A breaking change ships as a new version beside the old one. The old version keeps working for at least six months; its responses carry a Deprecation header (RFC 9745), a Sunset header with the removal date (RFC 8594), and a Link to the successor (rel="successor-version") and to this page (rel="deprecation").
  • The unversioned /api/ paths answer like v1 but are deprecated since 6 October 2026 and will be removed on 6 April 2027. Use /api/v1/.
  • MCP tools change the same way: new tools and optional arguments are additions; a breaking change gets a new tool name, and the old one keeps working for six months.

In the browser#

The home page registers search_icons, open_icon, set_icon_appearance and get_icon_code as WebMCP tools (document.modelContext), and the search box is a declarative tool form; icon pages register the same tools but open_icon.

Discovery#

https://generativeicons.com/llms.txt · https://generativeicons.com/index.md · https://generativeicons.com/.well-known/ard.json · https://generativeicons.com/.well-known/api-catalog · https://generativeicons.com/.well-known/agent-card.json · https://generativeicons.com/.well-known/agent-skills/index.json · https://generativeicons.com/.well-known/oauth-protected-resource · https://generativeicons.com/auth.md · https://generativeicons.com/sitemap.xml

Contact#

Questions and problems: support@lottiefiles.com or https://help.lottiefiles.com/kb-tickets/new.