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:
- Create an account or log in
- Navigate to Dashboard → API Keys
- 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
| Parameter | Type | Description |
|---|---|---|
style | string | Optional 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)
}