# Icon Management API

The Icon Management API allows you to upload custom icons, browse system icons, and assign icons to assistants. Icons support multiple formats (SVG, PNG, JPG) and quality levels for optimal performance.

## Overview

Icons in Freddy can be:

- **System icons**: 24 curated icons available to all users across business, creative, and technical categories
- **Custom icons**: Organization-specific icons uploaded by users


## Key Features

- Upload custom icons in SVG, PNG, or JPG format (max 5MB)
- Browse and search through system and custom icons
- Serve icons with quality transformations (thumbnail, small, medium, large, original)
- Assign icons to assistants via `icon_id` field
- Organize icons with tags and categories
- Soft-delete custom icons


## System Icons

24 curated icons are available to all users:

- **Business** (9): briefcase, building, chart-bar, chart, dollar-sign, presentation, target, trending-up, users
- **Creative** (7): camera, image, music, palette, pen-tool, sparkles, video
- **Technical** (8): cloud, code, cpu, database, git-branch, server, settings, terminal


**Recommended for Assistants**: sparkles, users, briefcase, code, palette, target, cpu, terminal, pen-tool, chart-bar

## Quality Levels

Icons can be served at different quality levels:

- `thumbnail` - 64x64px
- `small` - 128x128px
- `medium` - 256x256px (default)
- `large` - 512x512px
- `original` - Original size


Note: SVG icons always return original regardless of quality parameter.

## Best Practices

- Use **recommended icons** when listing icons for assistant selection (`?recommended_for=assistants`)
- Request **appropriate quality** - Use thumbnail for lists, medium for detail views, original for downloads
- **Cache icon URLs** - Icons are cached for 1 hour, safe to cache on client
- **SVG preferred** - SVG icons scale perfectly at any size
- **Optimize uploads** - Keep custom icons under 1MB for best performance


## Assistant Integration

Assign icons to assistants by including the `icon_id` field when creating or updating:


```json
{
  "name": "My Assistant",
  "icon_id": "icon_abc123...",
  ...
}
```

The assistant response will include both `icon_id` and `icon_url` for easy access.