API Reference

REST API for programmatic access to Unicon's icon library. Search, filter, and retrieve icon data in JSON format.

Base URL

https://unicon.sh/api

All endpoints are HTTPS only. No authentication required for public endpoints.

Rate Limits

Icon search (GET /api/icons)100 req/hour

Semantic search (POST /api/search)50 req/hour

MCP endpoints200 req/hour

Rate limits are per IP address. Contact us for higher limits or API key access.

GET

/api/icons

Fetch icons with optional filters. Supports AI-powered semantic search for queries with 3+ characters.

Parameters

Parameter	Type	Required	Default	Description
q	string	No	—	Search query (AI search if 3+ characters)
source	string	No	all	Filter by library (lucide, phosphor, etc.)
category	string	No	all	Filter by category
names	string	No	—	Comma-separated exact icon names
limit	number	No	100	Results per page (max: 320)
offset	number	No	0	Pagination offset
ai	boolean	No	true	Enable AI search

Response

Example Response

{
  "icons": [
    {
      "id": "lucide:home",
      "name": "Home",
      "normalizedName": "home",
      "sourceId": "lucide",
      "category": "Buildings",
      "tags": ["house", "building", "residence"],
      "viewBox": "0 0 24 24",
      "content": "<path d=\"M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z\"/><polyline points=\"9 22 9 12 15 12 15 22\"/>",
      "defaultStroke": true,
      "defaultFill": false,
      "strokeWidth": "2",
      "brandColor": null
    }
  ],
  "hasMore": true,
  "searchType": "semantic"
}

Examples

Search with AI:

curl "https://unicon.sh/api/icons?q=dashboard"

Filter by source:

curl "https://unicon.sh/api/icons?q=arrow&source=lucide&limit=10"

Get specific icons by name:

curl "https://unicon.sh/api/icons?names=home,settings,user"

Browse by category:

curl "https://unicon.sh/api/icons?category=Social&limit=50"

POST

/api/search

Hybrid semantic + exact match search with relevance scoring. More advanced than the GET endpoint.

Request Body

application/json

{
  "query": "dashboard",
  "sourceId": "lucide",
  "limit": 50,
  "useAI": false
}

Parameters

Parameter	Type	Required	Default	Description
query	string	Yes	—	Search query
sourceId	string	No	all	Filter by library
limit	number	No	50	Max results
useAI	boolean	No	false	Enable AI semantic search

Response

Example Response

{
  "results": [
    {
      "id": "lucide:home",
      "name": "Home",
      "normalizedName": "home",
      "sourceId": "lucide",
      "category": "Buildings",
      "tags": ["house", "building"],
      "viewBox": "0 0 24 24",
      "content": "<path d=\"...\"/>",
      "score": 0.95
    }
  ]
}

Examples

Basic search:

curl -X POST "https://unicon.sh/api/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "dashboard"}'

Filter by source:

curl -X POST "https://unicon.sh/api/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "arrow", "sourceId": "phosphor", "limit": 20}'

GET

/api/mcp

MCP server information and capabilities. Used by the MCP server package.

Response

Example Response

{
  "name": "Unicon MCP API",
  "version": "1.0.0",
  "description": "REST API for Unicon icon library with MCP compatibility",
  "capabilities": {
    "tools": ["search_icons", "get_icon", "get_multiple_icons"],
    "resources": ["sources", "categories", "stats"]
  },
  "usage": {
    "direct": "POST /api/mcp with { action, params }",
    "mcp": "Install: npx @webrenew/unicon-mcp-server",
    "docs": "https://unicon.sh/docs/mcp"
  }
}

POST

/api/mcp

Execute MCP actions. Used internally by the MCP server package. For direct use, prefer the CLI or standard API endpoints.

This endpoint is designed for MCP protocol communication. For easier integration, use the MCP Server package which handles the protocol details for you.

Icon Sources

Available icon libraries for filtering. Use these IDs in the source or sourceId parameters.

Source ID	Name	Icons	License
lucide	Lucide Icons	1,900+	ISC
phosphor	Phosphor Icons	1,500+	MIT
hugeicons	Huge Icons	1,800+	MIT
heroicons	Heroicons	292	MIT
tabler	Tabler Icons	4,600+	MIT
feather	Feather Icons	287	MIT
remix	Remix Icon	2,800+	Apache-2.0
simple-icons	Simple Icons	3,300+	CC0
iconoir	Iconoir	1,600+	MIT

Error Responses

All errors return a JSON object with an error message and appropriate HTTP status code.

400 Bad Request

{
  "error": "Invalid query parameter"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded. Please try again later."
}

500 Internal Server Error

{
  "error": "Internal server error"
}

Complete Examples

JavaScript/TypeScript

fetch-icons.ts

async function searchIcons(query: string) {
  const response = await fetch(
    `https://unicon.sh/api/icons?q=${encodeURIComponent(query)}&limit=20`
  );
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  const data = await response.json();
  return data.icons;
}

// Usage
const icons = await searchIcons("dashboard");
console.log(icons);

Python

fetch_icons.py

import requests

def search_icons(query: str, limit: int = 20):
    response = requests.get(
        "https://unicon.sh/api/icons",
        params={"q": query, "limit": limit}
    )
    response.raise_for_status()
    return response.json()["icons"]

# Usage
icons = search_icons("dashboard")
print(icons)

cURL

search-icons.sh

#!/bin/bash

# Search for icons
curl -s "https://unicon.sh/api/icons?q=dashboard&limit=10" \
  | jq '.icons[] | {name: .name, source: .sourceId}'

# Get specific icons
curl -s "https://unicon.sh/api/icons?names=home,settings,user" \
  | jq '.icons'

CORS

All API endpoints support CORS and can be called from any origin. This enables browser-based applications to use the API directly.

Access-Control-Allow-Origin: *