# Справочник API

> ClearLogo предоставляет единственный HTTP-эндпоинт, `GET /logo/{domain}`, который возвращает PNG (или WebP/JPEG) логотипа домена с консистентным соотношением сторон и прозрачным фоном. Анонимное использование работает для тестов низкого объёма; для боевого трафика используется браузерный ключ (клиент) или серверный ключ (бэкенд).

## Endpoint

```
GET https://api.clearlogo.dev/logo/:domain
```

`:domain` — это имя хоста без схемы и пути, например `github.com`. По умолчанию API возвращает `image/png`.

## Параметры запроса

| Название | Тип | По умолчанию | Примечания |
| --- | --- | --- | --- |
| `size` | number | `128` | Размер выходного изображения в px. Только квадратные. Допустимые значения: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024. |
| `content` | number | `80` | Занимаемое логотипом пространство внутри канваса (50–100, шаг 5). |
| `format` | `png \| webp \| jpeg` | `png` | Формат вывода. Автоматически согласуется через заголовок `Accept` — современные браузеры автоматически получают WebP через `<img>`. |
| `theme` | `light \| dark` | `light` | Возвращает тёмный вариант, если доступен, иначе возвращается светлый. |
| `token` | string | — | Браузерный ключ, используемый из клиентского кода. Origin или Referer должны совпадать с одним из разрешённых доменов на ключе. |

## Аутентификация

Анонимные запросы работают для низкого объёма тестирования. Для боевого трафика используйте браузерный ключ (клиент) или серверный ключ (бэкенд):

**Браузер**

```html
<img
  src="https://api.clearlogo.dev/logo/example.com?token=YOUR_BROWSER_KEY"
  alt="" />
```

**Сервер**

```bash
curl \
  -H "Authorization: Bearer YOUR_SERVER_KEY" \
  "https://api.clearlogo.dev/logo/example.com"
```

## Ограничения скорости

Лимиты по ключам возвращаются в заголовках `X-RateLimit-*`. При превышении API отвечает `429` и включает подсказку `Retry-After`.

## Часто задаваемые вопросы

### Как получить логотип для домена?

Отправьте GET-запрос на `https://api.clearlogo.dev/logo/{domain}`, где `{domain}` — имя хоста вроде `github.com`. Для тестов низкого объёма вход не требуется. Ответ по умолчанию — PNG, и он работает напрямую в тегах `<img>`.

### В чём разница между браузерным и серверным ключом?

Браузерный ключ безопасен для размещения в коде фронтенда и тегах `<img>`; запросы проверяются против разрешённых доменов, которые вы настраиваете на ключе. Серверный ключ аутентифицируется через заголовок `Authorization: Bearer` с бэкенда и никогда не должен попадать в браузер.

### Какие форматы вывода поддерживаются?

`png` (по умолчанию), `webp` и `jpeg`. Когда параметр `format` опущен, ClearLogo согласует содержимое через заголовок `Accept` запроса — современные браузеры автоматически получают WebP при загрузке API через тег `<img>`.