API Reference

Complete documentation for all SVG API endpoints.

Interactive API Explorer

Try out the API directly from your browser. Click on any endpoint to see parameters and send requests.

Base URL

Terminal

https://svg-api.org/v1

All endpoints are available without authentication.

Response format defaults to SVG. Add Accept: application/json header for JSON responses with metadata.

Rate Limits

Tier	Requests/min	Requests/day
Anonymous	60	1,000
Registered	300	10,000
Pro	1,000	100,000

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Endpoints

GET/v1/icons/{name}

Retrieve a single icon by name. Returns SVG by default, or JSON with metadata when requested.

Parameters

Parameter	Type	Default	Description
`name`*	string	-	Icon name (e.g., home, arrow-right)
`source`	string	lucide	Icon source library (lucide, tabler, heroicons, phosphor, etc.)
`size`	integer	24	Icon size in pixels (8-512)
`color`	string	currentColor	Color as hex (#ff0000) or named color. URL-encode # as %23
`stroke`	number	2	Stroke width (0.5-3)

Terminal

# Get SVG directly
curl "https://svg-api.org/v1/icons/home?source=lucide"
# Get JSON with metadata
curl -H "Accept: application/json" \
  "https://svg-api.org/v1/icons/home?source=lucide"
# Custom size and color
curl "https://svg-api.org/v1/icons/heart?source=lucide&size=32&color=%23ef4444"

Response

HTML

<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
  <path d="m3 9 9-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"/>
</svg>

GET/v1/search

Full-text search across all icons with relevance scoring.

Parameters

Parameter	Type	Default	Description
`q`*	string	-	Search query (minimum 2 characters)
`source`	string	-	Filter by icon source
`category`	string	-	Filter by category
`limit`	integer	20	Results per page (1-100)
`offset`	integer	0	Pagination offset

Terminal

# Search for arrow icons
curl "https://svg-api.org/v1/search?q=arrow"
# Filter by source
curl "https://svg-api.org/v1/search?q=arrow&source=lucide&limit=10"
# Filter by category
curl "https://svg-api.org/v1/search?q=mail&category=communication"

Response

JSON

{
  "data": [
    {
      "name": "arrow-right",
      "source": "lucide",
      "category": "arrows",
      "score": 0.95,
      "preview_url": "https://svg-api.org/v1/icons/arrow-right?source=lucide"
    },
    {
      "name": "arrow-left",
      "source": "lucide",
      "category": "arrows",
      "score": 0.93,
      "preview_url": "https://svg-api.org/v1/icons/arrow-left?source=lucide"
    }
  ],
  "meta": {
    "query": "arrow",
    "total": 156,
    "limit": 20,
    "offset": 0,
    "has_more": true,
    "search_time_ms": 12
  }
}

POST/v1/icons/batch

Fetch multiple icons in a single request. Maximum 50 icons per request.

Terminal

curl -X POST "https://svg-api.org/v1/icons/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "icons": [
      {"name": "home", "source": "lucide"},
      {"name": "search", "source": "lucide", "size": 32},
      {"name": "user", "source": "tabler", "color": "#3b82f6"}
    ],
    "defaults": {
      "size": 24,
      "stroke": 2
    }
  }'

Response

JSON

{
  "data": {
    "home:lucide": {
      "success": true,
      "name": "home",
      "source": "lucide",
      "svg": "<svg>...</svg>",
      "category": "navigation"
    },
    "search:lucide": {
      "success": true,
      "name": "search",
      "source": "lucide",
      "svg": "<svg>...</svg>",
      "category": "general"
    },
    "user:tabler": {
      "success": true,
      "name": "user",
      "source": "tabler",
      "svg": "<svg>...</svg>",
      "category": "users"
    }
  },
  "errors": {},
  "meta": {
    "requested": 3,
    "successful": 3,
    "failed": 0
  }
}

GET/v1/sources

List all available icon sources with metadata.

Terminal

curl "https://svg-api.org/v1/sources"

Response

JSON

{
  "data": [
    {
      "id": "lucide",
      "name": "Lucide",
      "description": "Beautiful & consistent icon toolkit",
      "version": "0.303.0",
      "icon_count": 1420,
      "website": "https://lucide.dev",
      "license": {
        "type": "ISC",
        "url": "https://github.com/lucide-icons/lucide/blob/main/LICENSE"
      },
      "variants": ["default"],
      "categories": ["arrows", "devices", "files", "shapes"]
    },
    {
      "id": "tabler",
      "name": "Tabler Icons",
      "description": "5000+ free and open source icons",
      "version": "2.47.0",
      "icon_count": 5000,
      "website": "https://tabler.io/icons",
      "license": {
        "type": "MIT",
        "url": "https://github.com/tabler/tabler-icons/blob/main/LICENSE"
      }
    }
  ],
  "meta": {
    "total_sources": 7,
    "total_icons": 22000
  }
}

GET/v1/categories

List all icon categories with counts.

Parameters

Parameter	Type	Default	Description
`source`	string	-	Filter categories by icon source

Terminal

# Get all categories
curl "https://svg-api.org/v1/categories"
# Filter by source
curl "https://svg-api.org/v1/categories?source=lucide"

Response

JSON

{
  "data": [
    {
      "id": "navigation",
      "name": "Navigation",
      "description": "Arrows, menus, and navigation elements",
      "icon_count": 342,
      "sources": ["lucide", "tabler", "heroicons"]
    },
    {
      "id": "communication",
      "name": "Communication",
      "description": "Email, chat, and messaging icons",
      "icon_count": 156,
      "sources": ["lucide", "tabler"]
    }
  ],
  "meta": {
    "total_categories": 24
  }
}

GET/v1/random

Get a random icon. Useful for testing or inspiration.

Parameters

Parameter	Type	Default	Description
`source`	string	-	Limit to specific source
`category`	string	-	Limit to specific category

Terminal

# Get random icon
curl "https://svg-api.org/v1/random"
# Random icon from specific source
curl "https://svg-api.org/v1/random?source=lucide"
# Random icon from category
curl "https://svg-api.org/v1/random?category=navigation"

Response

JSON

{
  "data": {
    "name": "sparkles",
    "source": "lucide",
    "category": "effects",
    "tags": ["magic", "stars", "shine"],
    "svg": "<svg>...</svg>",
    "preview_url": "https://svg-api.org/v1/icons/sparkles?source=lucide"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Error Handling

All errors return a consistent JSON structure:

JSON

{
  "error": {
    "code": "ICON_NOT_FOUND",
    "message": "Icon 'nonexistent' not found in source 'lucide'",
    "details": {
      "icon": "nonexistent",
      "source": "lucide",
      "suggestions": ["search", "magnifying-glass"]
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-07T12:00:00Z"
  }
}

Status	Code	Description
400	`INVALID_PARAMETER`	Invalid query parameter
404	`ICON_NOT_FOUND`	Icon does not exist
404	`SOURCE_NOT_FOUND`	Icon source does not exist
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Unexpected server error

Caching

All responses include appropriate cache headers:

Endpoint	Cache-Control	TTL
/icons/*	`public, max-age=86400`	24 hours
/search	`public, max-age=300`	5 minutes
/sources	`public, max-age=3600`	1 hour
/random	`no-cache`	None

ETags are supported for conditional requests. Use If-None-Match header to check for changes.