# Référence API

> ClearLogo expose un seul point de terminaison HTTP, `GET /logo/{domain}`, qui retourne un PNG (ou WebP/JPEG) du logo du domaine avec un ratio cohérent et un fond transparent. L'usage anonyme fonctionne pour les tests à faible volume ; le trafic en production utilise une clé navigateur (client) ou une clé serveur (backend).

## Point de terminaison

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

`:domain` est un nom d'hôte nu sans schéma ni chemin, par exemple `github.com`. L'API retourne `image/png` par défaut.

## Paramètres de requête

| Nom | Type | Défaut | Notes |
| --- | --- | --- | --- |
| `size` | number | `128` | Dimension de sortie en px. Carré uniquement. Valeurs autorisées : 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024. |
| `content` | number | `80` | Empreinte du logo à l'intérieur du canevas (50–100, étape 5). |
| `format` | `png \| webp \| jpeg` | `png` | Format de sortie. Auto-négocié depuis l'en-tête `Accept` — les navigateurs modernes reçoivent WebP automatiquement via `<img>`. |
| `theme` | `light \| dark` | `light` | Retourne la variante sombre quand disponible, sinon revient à la version claire. |
| `token` | string | — | Clé navigateur utilisée à partir du code client. L'origine ou l'en-tête Referer doit correspondre à un domaine autorisé sur la clé. |

## Authentification

Les requêtes anonymes fonctionnent pour les tests en faible volume. Pour le trafic en production, utilisez une clé navigateur (client) ou une clé serveur (backend) :

**Navigateur**

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

**Serveur**

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

## Limites de débit

Les limites par clé sont retournées dans les en-têtes `X-RateLimit-*`. Quand vous les dépassez, l'API répond avec `429` et inclut un indice `Retry-After`.

## Questions fréquentes

### Comment obtenir un logo pour un domaine ?

Envoyez une requête GET à `https://api.clearlogo.dev/logo/{domain}` où `{domain}` est un nom d'hôte comme `github.com`. Aucune connexion n'est requise pour les tests à faible volume. La réponse est un PNG par défaut et fonctionne directement dans les balises `<img>`.

### Quelle est la différence entre une clé navigateur et une clé serveur ?

Une clé navigateur peut être déployée sans danger dans le code frontend et les balises `<img>` ; les requêtes sont validées contre les domaines autorisés que vous configurez sur la clé. Une clé serveur s'authentifie via l'en-tête `Authorization: Bearer` depuis votre backend et ne doit jamais atteindre le navigateur.

### Quels formats de sortie sont pris en charge ?

`png` (par défaut), `webp` et `jpeg`. Quand le paramètre `format` est omis, ClearLogo négocie le contenu à partir de l'en-tête `Accept` de la requête — les navigateurs modernes reçoivent WebP automatiquement quand l'API est chargée via une balise `<img>`.