API docs

Search and render service icons.

Iconic API exposes a searchable service-icon catalog and a render endpoint that returns transparent PNGs from primary and accent mask layers.

Auth

Send an API key as a Bearer token.

Authorization: Bearer ic_live_...

Search icons

Search matches category names, category keys, service names, service keys, aliases, and searchable icon text.

GET /api/icons?query=roof repair

Example response

{
  "niches": [
    {
      "id": "uuid",
      "niche_key": "roofing",
      "niche_name": "Roofing",
      "icons": [
        {
          "id": "uuid",
          "service_key": "roof-repair",
          "service_name": "Roof Repair",
          "primary_mask_url": "/assets/service-icons/roofing/masks/roof-repair-primary-mask.png",
          "accent_mask_url": "/assets/service-icons/roofing/masks/roof-repair-accent-mask.png"
        }
      ]
    }
  ]
}

Render PNG

Render one icon as a transparent PNG. Colors should be sent as hex values without the leading hash.

GET /api/icons/roofing/roof-repair/render?primary=4B9CD3&accent=071427&size=512

Query	Required	Notes
primary	Yes	Primary mask fill color.
accent	Yes	Accent mask fill color.
size	No	PNG size in pixels. Defaults to 512.

Data model

Supabase stores icon categories and icon rows separately. Each icon has a category reference, UUID, stable service key, display name, aliases, status, source cell path, primary mask path, and accent mask path.

Status codes

200	Request succeeded.
401	Missing or invalid API key.
404	Icon or mask files were not found.
500	Unexpected server error.