Developer Documentation

API Reference - Endpoints & Methods

Scalable Vector Icons for Modern Interfaces

Core Endpoints

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

GET

/v2/icons/list

Retrieves a paginated list of all available icon packs and individual SVG assets. Supports filtering by category, license, and format.

Authentication Required

POST

/v2/icons/bundle

Generates a custom, optimized ZIP archive containing selected icon sets. Automatically strips unused paths and applies requested color overrides.

Rate Limited: 50 req/min

GET

/v2/icons/{id}/metadata

Fetches detailed metadata for a specific icon, including viewBox dimensions, author credits, license terms (MIT/Commercial), and related alternatives.

Public Access

POST

/v2/auth/token

Exchanges your project API key and secret for a short-lived Bearer token. Tokens expire after 3600 seconds and must be refreshed automatically.

Security Critical

Base URL: https://api.iconflow.dev/v2. All response payloads are returned as application/json with UTF-8 encoding.

Request Parameters & Headers

Configure your API calls using the standardized query parameters and authentication headers listed below.

Parameter	Type	Required	Description
`Authorization`	Header	Yes	Bearer token obtained via `/v2/auth/token`. Format: `Bearer <token>`
`X-Project-ID`	Header	Yes	Your unique workspace identifier. Found in the IconFlow dashboard under Settings > API Keys.
`limit`	Query	No	Number of records to return. Defaults to 25. Maximum allowed: 100.
`offset`	Query	No	Record offset for pagination. Defaults to 0.
`filter[license]`	Query	No	Filter by license type. Accepts: `mit`, `commercial`, `enterprise`.
`format`	Query	No	Output format for bundle requests. Accepts: `svg`, `png`, `webp`.

Tip: Use the Accept-Encoding: gzip header to reduce payload sizes by up to 70% for large bundle requests.

JSON Response Examples

Standardized response structures for successful requests, errors, and paginated results.

Successful GET /v2/icons/list

{
  "status": "success",
  "data": {
    "icons": [
      {
        "id": "icf-8821a",
        "name": "layer-stack",
        "category": "development",
        "license": "mit",
        "svg_url": "https://cdn.iconflow.dev/assets/icf-8821a.svg",
        "dimensions": { "width": 24, "height": 24 }
      },
      {
        "id": "icf-9932b",
        "name": "cloud-upload",
        "category": "infrastructure",
        "license": "commercial",
        "svg_url": "https://cdn.iconflow.dev/assets/icf-9932b.svg",
        "dimensions": { "width": 24, "height": 24 }
      }
    ],
    "pagination": {
      "total": 1482,
      "limit": 25,
      "offset": 0,
      "next_cursor": "eyJvZmZzZXQiOjI1fQ=="
    }
  },
  "meta": {
    "request_id": "req_7f3d9a2c1b",
    "latency_ms": 42,
    "timestamp": "2023-10-24T14:30:00Z"
  }
}

Error Response (401 Unauthorized)

{
  "status": "error",
  "error": {
    "code": "AUTH_TOKEN_EXPIRED",
    "message": "The provided Bearer token has expired. Please refresh via /v2/auth/token.",
    "details": {
      "token_issued_at": "2023-10-24T13:25:00Z",
      "expires_at": "2023-10-24T14:25:00Z"
    }
  },
  "meta": {
    "request_id": "req_8a2f1c4d9e",
    "latency_ms": 12,
    "timestamp": "2023-10-24T14:30:05Z"
  }
}

Rate Limiting: IconFlow enforces a soft limit of 1,200 requests per hour per project. Exceeding this returns a 429 Too Many Requests status with a Retry-After header.