# Iconic Icon Catalog

> 30,000+ free macOS app icons and curated style collections at https://icons.ahmetdedeler.com. Public read API — no API key. Publish your own collection with a one-time bearer token.

Browse icons, search by app name, download 1024px PNGs, or apply icons on macOS with the [Iconic](https://github.com/Ahmet-Dedeler/Iconic) app and CLI.

## API (read — no auth)

- [Search icons](https://icons.ahmetdedeler.com/api/search): `POST` JSON `{ "query": "notion", "searchOptions": { "hitsPerPage": 50, "page": 1 } }` → `{ hits, totalHits, totalPages }`. Backup: `GET /api/icons?q=notion&limit=50`.
- [Categories](https://icons.ahmetdedeler.com/api/categories): `GET` → category names and icon counts for filters.
- [Stats](https://icons.ahmetdedeler.com/api/stats): `GET` → total icon and listed-collection counts.
- [List collections](https://icons.ahmetdedeler.com/api/collections): `GET` → official style sets in `collections`; listed community sets in `community`. Add `?include=community` to merge community into `collections`.
- [Collection detail](https://icons.ahmetdedeler.com/api/collections/paper): `GET` → metadata + every icon URL in the set (works for unlisted community sets via direct link).
- [Icon PNG](https://icons.ahmetdedeler.com/icons/<objectID>.png): `GET` — 1024×1024 catalog icon from search hit `lowResPngUrl` / `icnsUrl`.
- [Collection icon PNG](https://icons.ahmetdedeler.com/collection-icons/<slug>/<app>.png): `GET` — one icon from a style collection.
- [API index](https://icons.ahmetdedeler.com/health): `GET` JSON list of all HTTP routes.

## Publish a collection (write — bearer token)

Create a local collection in Iconic, upload Dock-ready PNGs (1024×1024 RGBA), then publish:

1. `POST /api/collections` — body `{ "name", "description?", "accent?", "slug?" }` → `publishToken` (shown once).
2. `PUT /api/collections/{slug}/icons/{appSlug}` — `Authorization: Bearer <token>`, `Content-Type: image/png`.
3. `POST /api/collections/{slug}/finalize` — `Authorization: Bearer <token>`.

Full contract: [publish-collections.md](https://github.com/Ahmet-Dedeler/Iconic/blob/main/docs/publish-collections.md)

## macOS agents (preferred for applying icons)

This HTTP API serves search and download. To **change app icons on a Mac**, use the `iconic` CLI (shares state with the Iconic app):

- [Agent API guide](https://github.com/Ahmet-Dedeler/Iconic/blob/main/docs/agent-api.md)
- [iconic skill](https://github.com/Ahmet-Dedeler/Iconic/blob/main/skills/iconic/SKILL.md)

```bash
iconic search-icons "notion yellow" --json
iconic apply-from-catalog Notion --style yellow --json
iconic collections apply paper --dock --json
```

## Optional

- [Browse UI](https://icons.ahmetdedeler.com/): human-facing search and style-collection previews.
- [Iconic app](https://github.com/Ahmet-Dedeler/Iconic): open-source macOS icon changer.
- [Report a collection](https://icons.ahmetdedeler.com/api/report): `POST` `{ "slug", "reason" }`.