Developer Resources
API Referenz – Programmatischer Zugriff
Premium Icons für moderne Interfaces
The IconSphere REST API provides programmatic access to our library of 42,000+ premium icons across 380 curated packs. Use it to search, preview, and license icons directly from your applications, design tools, or CI/CD pipelines. Base URL: https://api.iconsphere.io/v1
Getting Started
Authentication
All API requests require authentication via an API key. Generate your key from the Dashboard → API Settings panel. Include it in every request using the Authorization header:
Authorization: Bearer is_live_sk_8f3a9c2d1e7b4f6a0d5c8e2b9f1a3d7e
Two key scopes are available: is_test_sk_* for sandbox testing with mock responses, and is_live_sk_* for production access. Rotate keys quarterly; expired keys return HTTP 401 with {"error":"invalid_api_key"}. Never expose live keys in client-side code.
Core Resources
Endpoints
The API exposes four primary resource groups. All responses are JSON-encoded with charset=utf-8.
GET
/icons/search
Search the icon library by keyword, tag, or pack ID. Supports pagination (limit up to 100, offset). Returns icon metadata including slug, dimensions, format (SVG, PNG, WebP), and license tier.
GET
/icons/{slug}
Retrieve full details for a specific icon by its slug (e.g., arrow-north-east-bold). Includes color variants, stroke weight options, and associated pack information. Returns 404 if the slug is not found.
GET
/packs
List all available icon packs. Filter by category (ui, maps, finance, medical, social) or by author. Each pack entry includes icon count, license type, and preview URLs.
GET
/packs/{id}/icons
Fetch every icon within a specific pack. Useful for bulk imports into design systems. Returns a paginated array of icon objects with thumbnail URLs and download tokens.
POST
/licensing/checkout
Initiate a license checkout for one or more icons. Accepts an array of icon slugs and a target license tier (personal, commercial, enterprise). Returns a Stripe Checkout session URL.
GET
/me/licenses
List all active licenses tied to the authenticated API key. Returns license ID, associated icons, tier, activation date, and expiration. Enterprise licenses include seat count and domain restrictions.
Usage Policy
Rate Limits
Rate limits are enforced per API key and vary by subscription tier. Exceeding a limit returns HTTP 429 with a Retry-After header.
Free Tier
60 requests per minute. 1,000 requests per day. Access to public icon metadata only — no download tokens. Suitable for prototyping and evaluation.
Pro Tier
600 requests per minute. 50,000 requests per day. Full search, preview, and download access. Includes webhook support for license events.
Enterprise Tier
5,000 requests per minute. Unlimited daily requests. Dedicated rate-limit bucket with burst allowance of 12,000 req/min. Includes SLA guarantee and priority support via api-support@iconsphere.io.
Current usage is reported in every response via the X-RateLimit-Remaining and X-RateLimit-Reset headers. Monitor these to implement client-side backoff before hitting the ceiling.
Code Samples
Request & Response Examples
Concrete examples for the most common API workflows.
Search Icons
GET /icons/search?q=calendar&limit=3
Request:
GET https://api.iconsphere.io/v1/icons/search?q=calendar&limit=3
Response (200):
{
"data": [
{
"slug": "calendar-month-outline",
"pack_id": "pack_7f2a1c",
"pack_name": "Horizon UI Essentials",
"formats": ["svg", "png", "webp"],
"license_tier": "commercial",
"tags": ["date", "schedule", "event"]
},
{
"slug": "calendar-check-bold",
"pack_id": "pack_3e9d0f",
"pack_name": "Nimbus Finance",
"formats": ["svg", "png"],
"license_tier": "commercial",
"tags": ["confirmed", "booking", "appointment"]
},
{
"slug": "calendar-plus-duotone",
"pack_id": "pack_7f2a1c",
"pack_name": "Horizon UI Essentials",
"formats": ["svg", "png", "webp"],
"license_tier": "personal",
"tags": ["create", "new-event", "add"]
}
],
"meta": {
"total_results": 184,
"limit": 3,
"offset": 0
}
}Retrieve Icon Details
GET /icons/calendar-month-outline
Request:
GET https://api.iconsphere.io/v1/icons/calendar-month-outline
Response (200):
{
"slug": "calendar-month-outline",
"pack_id": "pack_7f2a1c",
"dimensions": { "width": 24, "height": 24 },
"viewBox": "0 0 24 24",
"stroke_weight": 1.5,
"color_variants": ["monochrome", "duotone", "filled"],
"formats": {
"svg": "https://cdn.iconsphere.io/v1/svg/calendar-month-outline.svg",
"png_24": "https://cdn.iconsphere.io/v1/png/calendar-month-outline-24.png",
"png_48": "https://cdn.iconsphere.io/v1/png/calendar-month-outline-48.png",
"webp": "https://cdn.iconsphere.io/v1/webp/calendar-month-outline.webp"
},
"download_token": "dt_9k3m2x7p4q1w"
}License Checkout
POST /licensing/checkout
Request Body:
{
"icons": [
"calendar-month-outline",
"calendar-check-bold",
"arrow-north-east-bold"
],
"license_tier": "commercial",
"success_url": "https://myapp.io/checkout/success",
"cancel_url": "https://myapp.io/checkout/cancel"
}Response (200):
{
"checkout_session_id": "cs_live_8f2a9d3e1b7c",
"stripe_url": "https://checkout.stripe.com/pay/cs_live_8f2a9d3e1b7c",
"expires_at": "2025-07-12T14:30:00Z",
"total_usd": 29.00
}Error Response
HTTP 429 – Rate Limit Exceeded
Headers:
Retry-After: 23
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718157600
Body:
{
"error": "rate_limit_exceeded",
"message": "You have exceeded 60 requests per minute. Retry after 23 seconds.",
"documentation_url": "https://docs.iconsphere.io/rate-limits"
}SDKs & Integrations
Official client libraries are available for JavaScript/Node.js (@iconsphere/sdk), Python (pip install iconsphere), and Ruby (gem install iconsphere-ruby). All SDKs handle authentication, pagination, and automatic retry on 429 responses.