Home Docs API Reference

API Reference

The Iconfyra REST API gives you programmatic access to search icons, retrieve SVG data, and browse categories. Use it to build custom integrations, design tools, or icon pickers.

Authentication #

All API requests require an API key passed in the Authorization header using the Bearer scheme:

Authorization: Bearer icf_live_your_api_key_here

To get an API key:

  1. Create an account or log in
  2. Navigate to Dashboard → API Keys
  3. Click Generate New Key

Keep your API key secret. Never expose it in client-side code, public repositories, or anywhere end-users can see it. Use server-side requests to proxy API calls.

Base URL #

All API endpoints are relative to the following base URL:

https://api.iconfyra.com/v1

Rate Limits #

API requests are rate-limited based on your plan:

Plan Monthly Limit Rate (per minute)
Free 10,000 requests/month 60 requests/min
Pro 1,000,000 requests/month 600 requests/min

Rate limit information is included in response headers:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1709251200

Endpoints Overview #

Method Endpoint Description
GET /v1/icons Search and list icons
GET /v1/icons/{slug} Get a single icon by slug
GET /v1/svg/{style}/{slug}.svg Get raw SVG for an icon
GET /v1/categories List all icon categories

Search Icons #

Request

GET /v1/icons

Query Parameters

Parameter Type Default Description
q string - Search query (matches icon name, tags, category)
style string all Filter by style: solid, regular, light, thin, duotone
category string - Filter by category slug
page integer 1 Page number for pagination
per_page integer 50 Results per page (max: 200)

Example Request (fetch)

const response = await fetch('https://api.iconfyra.com/v1/icons?q=house&style=solid&per_page=10', {
    headers: {
        'Authorization': 'Bearer icf_live_your_api_key_here'
    }
});

const data = await response.json();
console.log(data);

Example Request (cURL)

curl -X GET "https://api.iconfyra.com/v1/icons?q=house&style=solid" \
  -H "Authorization: Bearer icf_live_your_api_key_here"

Response

{
    "success": true,
    "data": [
        {
            "id": 142,
            "name": "House",
            "slug": "house",
            "category": "buildings",
            "styles": ["solid", "regular", "light", "thin", "duotone"],
            "tags": ["home", "building", "residence"],
            "unicode": "e000",
            "class": "icf-solid icf-house",
            "created_at": "2024-01-15T10:30:00Z"
        }
    ],
    "meta": {
        "total": 3,
        "page": 1,
        "per_page": 10,
        "total_pages": 1
    }
}

Get Single Icon #

Request

GET /v1/icons/{slug}

Example

curl -X GET "https://api.iconfyra.com/v1/icons/house" \
  -H "Authorization: Bearer icf_live_your_api_key_here"

Response

{
    "success": true,
    "data": {
        "id": 142,
        "name": "House",
        "slug": "house",
        "category": {
            "id": 5,
            "name": "Buildings",
            "slug": "buildings"
        },
        "styles": ["solid", "regular", "light", "thin", "duotone"],
        "tags": ["home", "building", "residence"],
        "unicode": "e000",
        "svg": {
            "solid": "<svg viewBox=\"0 0 512 512\">...</svg>",
            "regular": "<svg viewBox=\"0 0 512 512\">...</svg>"
        },
        "created_at": "2024-01-15T10:30:00Z"
    }
}

Get SVG #

Returns the raw SVG content for a specific icon and style. Useful for embedding directly in HTML or design tools.

Request

GET /v1/svg/{style}/{slug}.svg

Example

# Get the solid version of the house icon as SVG
curl "https://api.iconfyra.com/v1/svg/solid/house.svg" \
  -H "Authorization: Bearer icf_live_your_api_key_here"

# Response: raw SVG content (Content-Type: image/svg+xml)
# <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">...</svg>

Optional Query Parameters

Parameter Type Description
color string Set fill color (hex without #, e.g. 4f46e5)
size integer Set width and height in pixels 
# Get a blue house icon at 64px
curl "https://api.iconfyra.com/v1/svg/solid/house.svg?color=4f46e5&size=64" \
  -H "Authorization: Bearer icf_live_your_api_key_here"

List Categories #

Request

GET /v1/categories

Response

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Arrows",
            "slug": "arrows",
            "icon_count": 54
        },
        {
            "id": 2,
            "name": "Business",
            "slug": "business",
            "icon_count": 87
        },
        // ... more categories
    ]
}

Error Codes #

The API uses standard HTTP status codes. Error responses follow a consistent format:

{
    "success": false,
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "You have exceeded your monthly API request limit.",
        "status": 429
    }
}
Status Code Description
400 BAD_REQUEST Invalid request parameters
401 UNAUTHORIZED Missing or invalid API key
403 FORBIDDEN API key lacks permission (e.g., accessing Pro icons on Free plan)
404 NOT_FOUND Icon or resource not found
429 RATE_LIMIT_EXCEEDED Too many requests; slow down or upgrade your plan
500 INTERNAL_ERROR Server error; please try again later

Code Examples #

JavaScript (fetch)

const API_KEY = 'icf_live_your_api_key_here';
const BASE_URL = 'https://api.iconfyra.com/v1';

// Search for icons
async function searchIcons(query, style = 'solid') {
    const params = new URLSearchParams({
        q: query,
        style: style,
        per_page: 20
    });

    const response = await fetch(`${BASE_URL}/icons?${params}`, {
        headers: {
            'Authorization': `Bearer ${API_KEY}`
        }
    });

    if (!response.ok) {
        throw new Error(`API error: ${response.status}`);
    }

    return response.json();
}

// Usage
const results = await searchIcons('arrow');
console.log(results.data);

cURL

# Search icons
curl -s "https://api.iconfyra.com/v1/icons?q=arrow&style=solid&per_page=5" \
  -H "Authorization: Bearer icf_live_your_api_key_here" | python -m json.tool

# Get a specific icon
curl -s "https://api.iconfyra.com/v1/icons/house" \
  -H "Authorization: Bearer icf_live_your_api_key_here"

# Download an SVG
curl -o house.svg "https://api.iconfyra.com/v1/svg/solid/house.svg" \
  -H "Authorization: Bearer icf_live_your_api_key_here"

# List categories
curl -s "https://api.iconfyra.com/v1/categories" \
  -H "Authorization: Bearer icf_live_your_api_key_here"

PHP

$apiKey = 'icf_live_your_api_key_here';
$baseUrl = 'https://api.iconfyra.com/v1';

// Search icons
$ch = curl_init("{$baseUrl}/icons?q=house&style=solid");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$apiKey}"
    ]
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data['data']);