# Serve icon

Get the actual icon file with optional quality transformation. Returns the binary image data.

#### Path Parameters

**`icon_id`** string required

The ID of the icon to retrieve.

#### Query Parameters

**`quality`** string optional · Defaults to `medium`

Image quality/size level. Options:

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


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

## Returns

Returns binary image data with appropriate `Content-Type` header (`image/svg+xml`, `image/png`, or `image/jpeg`).

### Caching Behavior

Response includes optimized caching headers:

- **System icons** (connectors): `Cache-Control: public, max-age=86400, immutable` (24 hours)
- **Custom icons**: `Cache-Control: public, max-age=3600, immutable` (1 hour)
- **ETag**: Unique identifier for cache validation (`"{icon_id}-{quality}"`)
- **Vary**: `Accept-Encoding` for proper compression handling


The `immutable` directive indicates the resource won't change for the given URL, enabling aggressive browser caching.

Request

```bash cURL - Get medium quality (default)
curl https://api.aitronos.com/v1/icons/icon_abc123 \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -o icon.png
```


```bash cURL - Get thumbnail
curl "https://api.aitronos.com/v1/icons/icon_abc123?quality=thumbnail" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -o icon-thumb.png
```


```bash cURL - Get original
curl "https://api.aitronos.com/v1/icons/icon_abc123?quality=original" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -o icon-original.png
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]
icon_id = "icon_abc123"

url = f"https://api.aitronos.com/v1/icons/{icon_id}"
headers = {"X-API-Key": api_key}

# Get medium quality (default)
response = requests.get(url, headers=headers)
with open("icon.png", "wb") as f:
    f.write(response.content)

# Get thumbnail
params = {"quality": "thumbnail"}
response = requests.get(url, headers=headers, params=params)
with open("icon-thumb.png", "wb") as f:
    f.write(response.content)

# Get original
params = {"quality": "original"}
response = requests.get(url, headers=headers, params=params)
with open("icon-original.png", "wb") as f:
    f.write(response.content)
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;
const iconId = 'icon_abc123';

// Get medium quality (default)
const response = await fetch(
  `https://api.aitronos.com/v1/icons/${iconId}`,
  {
    headers: {
      'X-API-Key': apiKey
    }
  }
);

const blob = await response.blob();
// Use blob for display or download

// Get thumbnail
const thumbResponse = await fetch(
  `https://api.aitronos.com/v1/icons/${iconId}?quality=thumbnail`,
  {
    headers: {
      'X-API-Key': apiKey
    }
  }
);

const thumbBlob = await thumbResponse.blob();

// Display in browser
const imageUrl = URL.createObjectURL(blob);
document.getElementById('icon').src = imageUrl;
```

Response

```text 200 OK - Binary image data
Binary image data
Content-Type: image/png
Cache-Control: public, max-age=3600
```


```json 404 Not Found
{
  "success": false,
  "error": {
    "code": "ICON_NOT_FOUND",
    "message": "Icon not found",
    "type": "client_error",
    "status": 404,
    "details": {
      "icon_id": "icon_invalid123"
    },
    "trace_id": "abc-123-def",
    "timestamp": "2025-12-03T10:00:00Z"
  }
}
```