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.lottiefiles.com/auth.md).

MCP servers#

Server	URL	Tools
Icons	https://generativeicons.lottiefiles.com/mcp	`search_icons`, `get_icon`, `list_categories`, `read_guide`
Guides	https://generativeicons.lottiefiles.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.lottiefiles.com/.well-known/mcp/server-card.json and https://generativeicons.lottiefiles.com/mcp/docs/server-card. In Claude Code:

Terminal

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

A2A agent#

https://generativeicons.lottiefiles.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.lottiefiles.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.lottiefiles.com/api/v1, described at https://generativeicons.lottiefiles.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.lottiefiles.com/api/v1/icons?q=upload+failed&limit=3'

Icon files are at https://generativeicons.lottiefiles.com/assets/.lottie, the full catalog at https://generativeicons.lottiefiles.com/catalog.json, and every guide as Markdown at https://generativeicons.lottiefiles.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.lottiefiles.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#

Contact#

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