# API-Referenz

> ClearLogo stellt einen einzigen HTTP-Endpoint, `GET /logo/{domain}`, bereit, der ein PNG (oder WebP/JPEG) des Domain-Logos mit konsistentem Seitenverhältnis und transparentem Hintergrund zurückgibt. Anonyme Nutzung funktioniert für Tests mit geringem Volumen; Produktionsverkehr verwendet einen Browser-Schlüssel (Client) oder einen Server-Schlüssel (Backend).

## Endpoint

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

`:domain` ist ein einfacher Hostname ohne Schema oder Pfad, z. B. `github.com`. Die API gibt standardmäßig `image/png` zurück.

## Query-Parameter

| Name | Typ | Standard | Hinweise |
| --- | --- | --- | --- |
| `size` | number | `128` | Ausgabedimension in px. Nur Quadrat. Zulässige Werte: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024. |
| `content` | number | `80` | Logo-Fußabdruck innerhalb der Canvas (50–100, Schritt 5). |
| `format` | `png \| webp \| jpeg` | `png` | Ausgabeformat. Wird automatisch vom `Accept`-Header ausgehandelt — moderne Browser erhalten WebP automatisch über `<img>`. |
| `theme` | `light \| dark` | `light` | Gibt die dunkle Variante zurück, wenn verfügbar, sonst fällt auf hell zurück. |
| `token` | string | — | Browser-Schlüssel, der von Client-Code verwendet wird. Origin oder Referer müssen einer zulässigen Domain auf dem Schlüssel entsprechen. |

## Authentifizierung

Anonyme Anfragen funktionieren für Tests mit geringem Volumen. Verwenden Sie für Produktionsverkehr einen Browser-Schlüssel (Client) oder einen Server-Schlüssel (Backend):

**Browser**

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

**Server**

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

## Rate-Limits

Pro-Schlüssel-Limits werden in `X-RateLimit-*`-Headern zurückgegeben. Wenn Sie diese überschreiten, antwortet die API mit `429` und enthält einen `Retry-After`-Hinweis.

## Häufige Fragen

### Wie erhalte ich ein Logo für eine Domain?

Senden Sie eine GET-Anfrage an `https://api.clearlogo.dev/logo/{domain}`, wobei `{domain}` ein einfacher Hostname wie `github.com` ist. Für Tests mit geringem Volumen ist keine Anmeldung erforderlich. Die Antwort ist standardmäßig ein PNG und funktioniert direkt in `<img>`-Tags.

### Was ist der Unterschied zwischen einem Browser- und einem Server-Schlüssel?

Ein Browser-Schlüssel kann sicher in Frontend-Code und `<img>`-Tags eingesetzt werden; Anfragen werden gegen die auf dem Schlüssel konfigurierten zulässigen Domains validiert. Ein Server-Schlüssel authentifiziert sich über den `Authorization: Bearer`-Header vom Backend und darf den Browser niemals erreichen.

### Welche Ausgabeformate werden unterstützt?

`png` (Standard), `webp` und `jpeg`. Wenn der `format`-Parameter weggelassen wird, verhandelt ClearLogo den Inhalt anhand des `Accept`-Anfrage-Headers — moderne Browser erhalten WebP automatisch, wenn die API über ein `<img>`-Tag geladen wird.