Developer Docs · v1

Lovicons API

A single HTTPS endpoint for every icon — curated open-source sets and your AI-generated brand packs. Works in any framework, any agent, any <img> tag.

Quickstart

1. Sign in and generate a pack from the dashboard.
2. Open API tokens and create a token. Copy it — shown only once.
3. Drop the URL into your app:

<img src="https://lovicons.com/api/public/v1/icons/<packId>/dashboard.svg?token=icn_xxx" />

Authentication

Send your token either as a Bearer header (preferred, server-side) or as a ?token= query param (fine for static <img> tags). Curated open-source packs need no token.

# Bearer (recommended)
curl -H "Authorization: Bearer icn_xxx" \
  https://lovicons.com/api/public/v1/icons/<packId>

# Query param
https://lovicons.com/api/public/v1/icons/<packId>/arrow.svg?token=icn_xxx

Endpoints

GET/api/public/v1/manifestAutonomous discovery — every pack + every icon name + svg_url in a single response. Recommended first call for agents.

GET/api/public/v1/search?q=cart,basketCross-pack ranked icon search by keyword(s). Add &include_svg=1 to inline SVG.

GET/api/public/v1/packsList packs visible to your token (with icon counts + URL templates).

GET/api/public/v1/icons/{packId}Pack manifest (name, icon list).

GET/api/public/v1/icons/{packId}/{name}.svgSingle icon as SVG.

GET/api/public/v1/icons/{library}/{name}.svgCurated open-source set (e.g. lucide, tabler, solar) — no token required.

POST/api/public/mcpMCP server for Lovable / Cursor / Claude. Includes use_pack for automatic app-wide icon replacement by pack name.

Use it in a Lovable app

Connect the Lovicons MCP once, then use plain language in agent chat. You do not need pack IDs, endpoint details, or icon names:

Use my Lovicons pack "Brand v2" to replace all icons in this app.
Inspect the interface, choose icons by meaning, implement the SVG replacements,
preserve accessibility and styling, and verify every updated screen.

JavaScript / TypeScript

async function loadIcon(name: string) {
  const res = await fetch(
    `https://lovicons.com/api/public/v1/icons/${PACK_ID}/${name}.svg`,
    { headers: { Authorization: `Bearer ${process.env.LOVICONS_API_KEY}` } }
  );
  if (!res.ok) throw new Error((await res.json()).error.message);
  return res.text(); // raw SVG string
}

React component

export function Icon({ name }: { name: string }) {
  return (
    <img
      src={`https://lovicons.com/api/public/v1/icons/${PACK_ID}/${name}.svg?token=${TOKEN}`}
      alt={name} width={24} height={24}
    />
  );
}

For server-rendered apps, prefer fetching server-side so the token isn't in HTML.

Errors

All errors return JSON in this shape:

{ "error": { "code": "invalid_token", "message": "API token is invalid or has been revoked." } }

Code	Meaning
401 missing_token	No token supplied.
401 invalid_token	Token unknown or revoked.
403 token_scope_mismatch	Token scoped to a different pack.
404 pack_not_found	Pack does not exist or isn't yours.
404 icon_not_found	No such icon in the pack/library.

Caching

SVG responses ship with ETag and Cache-Control: public, max-age=3600 (24h for curated sets). Send If-None-Match to get a cheap 304.

MCP server

Lovicons ships an MCP endpoint at https://lovicons.com/api/public/mcp. Connect it once and any agent — Lovable, Cursor, Claude Desktop — can browse, search, and place your icons on its own.

Set up with Lovable →