API Reference

A free, public, zero-auth REST API over the Grida Icons catalog — 5,000+ icons from Heroicons, Lucide, Phosphor, Octicons, Radix UI, and SVGL, enriched with keywords and descriptions. No API key, CORS open to all origins, responses cached at the edge.

Base URL

https://icons.grida.co

Search icons

Ranked keyword search over icon names and tags (prefix + fuzzy matching). Returns one result per logical icon, with its variants grouped. This is the recommended endpoint for building search UIs.

GET/api/search

Parameter	Type	Description
q	string	Search query (matches name + tags). Alias: name.
vendor	string	Restrict to one set, e.g. lucide-icons.
limit	number	Page size. Default 100, max 500.
offset	number	Pagination offset. Default 0.

curl "https://icons.grida.co/api/search?q=trash&limit=2"

{
  "total": 16,
  "count": 2,
  "limit": 2,
  "offset": 0,
  "items": [
    {
      "id": "heroicons/trash",
      "vendor": "heroicons",
      "name": "trash",
      "description": "Wastebasket symbol indicating the action of deleting data.",
      "tags": ["trash", "delete", "remove", "bin"],
      "download": "https://icons.grida.co/dist/heroicons/src/24/outline/trash.svg",
      "url": "/icons/heroicons/trash",
      "variants": [
        {
          "name": "trash",
          "properties": { "size": "24", "style": "solid" },
          "download": "https://icons.grida.co/dist/heroicons/src/24/solid/trash.svg"
        }
      ]
    }
  ]
}

List icons

Lists every icon file (each variant is a separate item). Filtering is exact substring on name. Use /api/search for ranked search.

GET/api

Parameter	Type	Description
vendor	string	Restrict to one set.
q	string	Case-insensitive substring on the icon name.
variant:<key>	string	Filter by a variant property, e.g. variant:style=solid or variant:weight=bold.

curl "https://icons.grida.co/api?vendor=phosphor-icons&variant:weight=bold"

Brand logos (SVGL)

Same shape as /api, scoped to the SVGL brand logo set (light/dark themes, symbol/wordmark kinds).

GET/api/logos

curl "https://icons.grida.co/api/logos?variant:theme=dark"

List sets

Metadata for every icon set, including its variant axes and counts.

GET/api/vendors

{
  "total": 6,
  "items": [
    {
      "id": "heroicons",
      "name": "Heroicons",
      "version": "2.2.0",
      "count": 1288,
      "variants": {
        "size": { "title": "Size", "default": "24", "enum": ["16", "20", "24"] },
        "style": { "title": "Style", "default": "outline", "enum": ["solid", "outline"] }
      }
    }
  ]
}

Raw SVG assets

Every download URL points at the raw SVG, served with Access-Control-Allow-Origin: * and an immutable one-year cache — safe to hotlink or embed directly.

GET/dist/{vendor}/{file}

<img src="https://icons.grida.co/dist/lucide-icons/src/arrow-up.svg" width="24" height="24" />

Notes

No authentication. All endpoints accept GET and respond with JSON.
CORS is open to every origin; responses set s-maxage=3600, stale-while-revalidate=86400.
Each icon set keeps its upstream license — review the source project before redistribution.