Home Docs API Reference

API Reference

The Iconfyra REST API gives you programmatic access to search the icon font library and retrieve SVG data. 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. Exceeding either limit returns a 429 RATE_LIMIT_EXCEEDED response.

Plan Monthly Limit Per Minute Icon Weights
Free 10,000 1 Solid, Regular
Basic 100,000 5 Solid, Regular, Light, Thin
Pro 1,000,000 10 All weights + Duotone
Max 10,000,000 20 All weights + Duotone

Rate limit information is included in response headers:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Minute-Limit: 5
X-RateLimit-Minute-Remaining: 4

Endpoints Overview #

Method Endpoint Description
GET /v1/ping Health check - returns API status and version
GET /v1/icons Search and list icons
GET /v1/icons/{slug} Get a single icon by slug
GET /v1/icons/{slug}/svgs Get all SVGs for an icon (filtered by plan)
GET /v1/svg/{style}/{slug}.svg Get raw SVG for an icon
GET /v1/icons?slugs=a,b,c Batch fetch up to 10 icons by slug
GET /v1/icons/random Get a random icon

Ping #

Health check endpoint. No authentication required. Useful for monitoring and integration testing.

Request

GET /v1/ping

Response

{
    "success": true,
    "data": {
        "status": "ok",
        "version": "v1",
        "app": "Iconfyra",
        "time": "2026-05-27T12:00:00+00:00"
    }
}

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

curl -X GET "https://api.iconfyra.com/v1/icons?q=house&style=solid&per_page=10" \
  -H "Authorization: Bearer icf_live_your_api_key_here"
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);
$ch = curl_init('https://api.iconfyra.com/v1/icons?q=house&style=solid&per_page=10');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer icf_live_your_api_key_here'],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($data['data']);
import requests

response = requests.get(
    'https://api.iconfyra.com/v1/icons',
    params={'q': 'house', 'style': 'solid', 'per_page': 10},
    headers={'Authorization': 'Bearer icf_live_your_api_key_here'}
)
print(response.json())
package main

import (
    "fmt"; "io"; "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.iconfyra.com/v1/icons?q=house&style=solid", nil)
    req.Header.Set("Authorization", "Bearer icf_live_your_api_key_here")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

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"
const response = await fetch('https://api.iconfyra.com/v1/icons/house', {
  headers: { 'Authorization': 'Bearer icf_live_your_api_key_here' }
});
const { data } = await response.json();
console.log(data);
$ch = curl_init('https://api.iconfyra.com/v1/icons/house');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer icf_live_your_api_key_here'],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
import requests

response = requests.get(
    'https://api.iconfyra.com/v1/icons/house',
    headers={'Authorization': 'Bearer icf_live_your_api_key_here'}
)
print(response.json()['data'])
req, _ := http.NewRequest("GET", "https://api.iconfyra.com/v1/icons/house", nil)
req.Header.Set("Authorization", "Bearer icf_live_your_api_key_here")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

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 All SVGs #

Returns SVG markup for all available styles of an icon in a single request. Results are filtered to the styles allowed by your plan.

Request

GET /v1/icons/{slug}/svgs

Example

curl "https://api.iconfyra.com/v1/icons/house/svgs" \
  -H "Authorization: Bearer icf_live_your_api_key_here"
const response = await fetch('https://api.iconfyra.com/v1/icons/house/svgs', {
  headers: { 'Authorization': 'Bearer icf_live_your_api_key_here' }
});
const { data } = await response.json();
console.log(data['classic-solid'].svg);
$ch = curl_init('https://api.iconfyra.com/v1/icons/house/svgs');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer icf_live_your_api_key_here'],
]);
$svgs = json_decode(curl_exec($ch), true)['data'];
r = requests.get('https://api.iconfyra.com/v1/icons/house/svgs',
    headers={'Authorization': 'Bearer icf_live_your_api_key_here'}
)
svgs = r.json()['data']
print(svgs['classic-solid']['svg'])
req, _ := http.NewRequest("GET", "https://api.iconfyra.com/v1/icons/house/svgs", nil)
req.Header.Set("Authorization", "Bearer icf_live_your_api_key_here")
resp, _ := http.DefaultClient.Do(req)

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

curl "https://api.iconfyra.com/v1/svg/solid/house.svg" \
  -H "Authorization: Bearer icf_live_your_api_key_here"
const response = await fetch('https://api.iconfyra.com/v1/svg/solid/house.svg', {
  headers: { 'Authorization': 'Bearer icf_live_your_api_key_here' }
});
const svgText = await response.text();
document.body.innerHTML += svgText;
$ch = curl_init('https://api.iconfyra.com/v1/svg/solid/house.svg');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer icf_live_your_api_key_here'],
]);
$svg = curl_exec($ch);
curl_close($ch);
echo $svg;
import requests

response = requests.get(
    'https://api.iconfyra.com/v1/svg/solid/house.svg',
    headers={'Authorization': 'Bearer icf_live_your_api_key_here'}
)
with open('house.svg', 'w') as f:
    f.write(response.text)
req, _ := http.NewRequest("GET", "https://api.iconfyra.com/v1/svg/solid/house.svg", nil)
req.Header.Set("Authorization", "Bearer icf_live_your_api_key_here")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
os.WriteFile("house.svg", body, 0644)

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"

Batch Fetch Icons #

Fetch up to 10 icons by slug in a single request using the slugs parameter.

Request

GET /v1/icons?slugs={slug1},{slug2},{slug3}

Example

curl "https://api.iconfyra.com/v1/icons?slugs=house,arrow-up,star" \
  -H "Authorization: Bearer icf_live_your_api_key_here"
const response = await fetch('https://api.iconfyra.com/v1/icons?slugs=house,arrow-up,star', {
  headers: { 'Authorization': 'Bearer icf_live_your_api_key_here' }
});
const { data } = await response.json();
$ch = curl_init('https://api.iconfyra.com/v1/icons?slugs=house,arrow-up,star');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer icf_live_your_api_key_here'],
]);
$data = json_decode(curl_exec($ch), true);
r = requests.get('https://api.iconfyra.com/v1/icons',
    params={'slugs': 'house,arrow-up,star'},
    headers={'Authorization': 'Bearer icf_live_your_api_key_here'}
)
print(r.json())
req, _ := http.NewRequest("GET", "https://api.iconfyra.com/v1/icons?slugs=house,arrow-up,star", nil)
req.Header.Set("Authorization", "Bearer icf_live_your_api_key_here")
resp, _ := http.DefaultClient.Do(req)

Random Icon #

Returns a single randomly selected icon. Optionally filter by style.

Request

GET /v1/icons/random

Query Parameters

ParameterTypeDescription
stylestringOptional style filter: solid, regular, light, thin, duotone

Example

curl "https://api.iconfyra.com/v1/icons/random" \
  -H "Authorization: Bearer icf_live_your_api_key_here"
const response = await fetch('https://api.iconfyra.com/v1/icons/random', {
  headers: { 'Authorization': 'Bearer icf_live_your_api_key_here' }
});
const { data } = await response.json();
console.log(data.slug);
$ch = curl_init('https://api.iconfyra.com/v1/icons/random');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer icf_live_your_api_key_here'],
]);
$icon = json_decode(curl_exec($ch), true)['data'];
r = requests.get('https://api.iconfyra.com/v1/icons/random',
    headers={'Authorization': 'Bearer icf_live_your_api_key_here'}
)
print(r.json()['data']['slug'])
req, _ := http.NewRequest("GET", "https://api.iconfyra.com/v1/icons/random", nil)
req.Header.Set("Authorization", "Bearer icf_live_your_api_key_here")
resp, _ := http.DefaultClient.Do(req)

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 #

A complete client example covering search, single icon fetch, and SVG download.

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

# 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"
const API_KEY = 'icf_live_your_api_key_here';
const BASE_URL = 'https://api.iconfyra.com/v1';

async function icfRequest(path) {
  const res = await fetch(`${BASE_URL}${path}`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });
  if (!res.ok) throw new Error(`API error: ${res.status}`);
  return res.json();
}

// Search icons
const results = await icfRequest('/icons?q=arrow&style=solid&per_page=5');
console.log(results.data);

// Get single icon
const icon = await icfRequest('/icons/house');
console.log(icon.data);

// Download SVG as text
const svgRes = await fetch(`${BASE_URL}/svg/solid/house.svg`, {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const svg = await svgRes.text();
$apiKey  = 'icf_live_your_api_key_here';
$baseUrl = 'https://api.iconfyra.com/v1';

function icfRequest($url, $apiKey): array {
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ["Authorization: Bearer {$apiKey}"],
    ]);
    $body = curl_exec($ch);
    curl_close($ch);
    return json_decode($body, true);
}

// Search icons
$results = icfRequest("{$baseUrl}/icons?q=arrow&style=solid&per_page=5", $apiKey);
print_r($results['data']);

// Get single icon
$icon = icfRequest("{$baseUrl}/icons/house", $apiKey);

// Download SVG
$ch = curl_init("{$baseUrl}/svg/solid/house.svg");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer {$apiKey}"],
]);
$svg = curl_exec($ch);
curl_close($ch);
file_put_contents('house.svg', $svg);
import requests

API_KEY  = 'icf_live_your_api_key_here'
BASE_URL = 'https://api.iconfyra.com/v1'
HEADERS  = {'Authorization': f'Bearer {API_KEY}'}

# Search icons
r = requests.get(f'{BASE_URL}/icons', params={'q': 'arrow', 'style': 'solid', 'per_page': 5}, headers=HEADERS)
print(r.json()['data'])

# Get single icon
r = requests.get(f'{BASE_URL}/icons/house', headers=HEADERS)
print(r.json()['data'])

# Download SVG
r = requests.get(f'{BASE_URL}/svg/solid/house.svg', headers=HEADERS)
with open('house.svg', 'w') as f:
    f.write(r.text)
package main

import (
    "fmt"; "io"; "net/http"; "os"
)

const (
    apiKey  = "icf_live_your_api_key_here"
    baseURL = "https://api.iconfyra.com/v1"
)

func icfGet(path string) []byte {
    req, _ := http.NewRequest("GET", baseURL+path, nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    return body
}

func main() {
    // Search icons
    fmt.Println(string(icfGet("/icons?q=arrow&style=solid&per_page=5")))

    // Get single icon
    fmt.Println(string(icfGet("/icons/house")))

    // Download SVG
    os.WriteFile("house.svg", icfGet("/svg/solid/house.svg"), 0644)
}