---
title: "Developers"
description: "The Generative Icons API and MCP servers: endpoints, tools, limits, errors, versioning and deprecation."
canonical: https://generativeicons.lottiefiles.com/developers/
---

# 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:

```sh
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) |

```sh
curl 'https://generativeicons.lottiefiles.com/api/v1/icons?q=upload+failed&limit=3'
```

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

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

## Contact

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