# Icons

Icon sets where every icon has a name, a plain-language description, aliases, and an embedding. Search by meaning, then hotlink or download the PNG or SVG from our CDN. Nothing is served through the API.

MCP: `search_icons`, `get_icon`

Two sets ship first. They hold the same icons drawn two ways.

| Set | Style | Size |
|---|---|---|
| `pixelset` | 16-bit village pixel art, dark outlines, warm palette | 128 px PNG with alpha, and lossless SVG |
| `lineset` | Lucide-style line, even 2 px stroke, moss ink | 160 px (ingredients) or 512 px PNG with alpha, and SVG |

Collections inside a set: `ingredients`, `food-categories`, `book-genres`, `general` (everyday UI icons), and `business` (analytics and partnership icons: gem, eye, target, handshake, wallet, and more) in both sets, plus `village` (the site's own icons) in Pixelset.

Browse on the site at `/icons/pixel` and `/icons/line`; each icon has a page at `/icons/{style}/{collection}/{slug}`, e.g. `/icons/pixel/ingredients/wheat`.

## Search by meaning

```http
GET /v1/icons/search?q=something%20spicy&set=pixelset
```

| Query | Notes |
|---|---|
| `q` | Plain words. Required. Name and alias matches rank first, then full text, then vector similarity |
| `set` | `pixelset` · `lineset`. Omit to search both |
| `collection` | e.g. `ingredients` |
| `limit` | Default 24, max 100 |

Each hit carries `score` (0–1) and `match`: `name`, `alias`, `text`, or `semantic`. `semantic` in the response body tells you whether the vector leg ran. Strong name or alias matches answer from Postgres alone; only vaguer phrasing waits for the embedding model, and repeat queries reuse a cached vector.

Embeddings are `@cf/baai/bge-small-en-v1.5` (384 dims), the same model for stored icons and for your query.

## Get one icon

```http
GET /v1/icons/{id}
GET /v1/iconsets/{set}/{collection}/{slug}
```

`id` is `fds_ic_…`. The path form mirrors the CDN key, so `pixelset/ingredients/wheat` is stable across releases. Both return the icon plus `siblings`: the same slug in the other sets.

```json
{
  "id": "fds_ic_2f5dbd205d00da544f45",
  "set": "pixelset",
  "collection": "ingredients",
  "slug": "wheat",
  "name": "Wheat and flour",
  "description": "Pixel-art icon of single wheat stalk with grains along the head. Village 16-bit style with dark outlines. From the ingredients collection.",
  "aliases": ["flour", "grain", "gluten", "bread flour", "cereal grain", "barley", "rye"],
  "cdn_url": "https://cdn.fulldatasets.com/fulldatasets/icons/pixelset/ingredients/wheat.png",
  "svg_url": "https://cdn.fulldatasets.com/fulldatasets/icons/pixelset/ingredients/wheat.svg",
  "svg_bytes": 3120,
  "width": 128,
  "height": 128,
  "bytes": 1488,
  "license": "CC-BY-4.0",
  "siblings": [{ "set": "lineset", "cdn_url": "https://cdn.fulldatasets.com/fulldatasets/icons/lineset/ingredients/wheat.png" }]
}
```

## List and sets

```http
GET /v1/iconsets
GET /v1/icons?set=lineset&collection=book-genres&limit=200
```

Lists page with `next_cursor`.

## Get the file

```http
GET /v1/iconsets/{set}/{collection}/{slug}.svg
GET /v1/iconsets/{set}/{collection}/{slug}.png
```

Both `302` to the file on the CDN, so an agent can hand a client one API URL and let the browser follow it. `?format=svg` works too.

## Use the PNG or SVG

Every `cdn_url` and `svg_url` is a public object on Cloudflare R2 behind `cdn.fulldatasets.com`, cached for a year and immutable per release. Hotlink it or download it; there is no auth and no meter.

Pixelset SVGs are the pixel grid itself, one path per colour with `shape-rendering="crispEdges"`, so they scale to any size with hard pixel edges and no blur. Lineset SVGs are traced single-colour paths in moss ink `#243226`; recolour them with `fill`.

```html
<img src="https://cdn.fulldatasets.com/fulldatasets/icons/pixelset/ingredients/wheat.png" width="32" height="32" alt="Wheat" style="image-rendering: pixelated">
```

Pixelset icons want `image-rendering: pixelated` so browsers keep the pixels crisp when scaling. Lineset icons scale normally.

## License

Icons are **CC BY 4.0**. Credit “Icons by FullDatasets” with a link to `https://fulldatasets.com/datasets/icons`. The catalog rows (names, aliases, descriptions) are CC0.