# Referencia de API

> ClearLogo expone un único endpoint HTTP, `GET /logo/{domain}`, que devuelve un PNG (o WebP/JPEG) del logo del dominio con proporción consistente y fondo transparente. El uso anónimo funciona para pruebas de bajo volumen; el tráfico de producción usa una clave de navegador (cliente) o de servidor (backend).

## Endpoint

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

`:domain` es un nombre de host sin esquema ni ruta, por ejemplo `github.com`. La API devuelve `image/png` por defecto.

## Parámetros de consulta

| Nombre | Tipo | Por defecto | Notas |
| --- | --- | --- | --- |
| `size` | number | `128` | Dimensión de salida en px. Solo cuadrado. Valores permitidos: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024. |
| `content` | number | `80` | Huella del logo dentro del lienzo (50–100, paso 5). |
| `format` | `png \| webp \| jpeg` | `png` | Formato de salida. Negociado automáticamente desde el encabezado `Accept` — los navegadores modernos reciben WebP automáticamente con `<img>`. |
| `theme` | `light \| dark` | `light` | Devuelve la variante oscura cuando está disponible; de lo contrario, recurre a clara. |
| `token` | string | — | Clave de navegador utilizada desde código cliente. El origen o Referer debe coincidir con un dominio permitido en la clave. |

## Autenticación

Las solicitudes anónimas funcionan para pruebas de bajo volumen. Para tráfico de producción, usa una clave de navegador (cliente) o una clave de servidor (backend):

**Navegador**

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

**Servidor**

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

## Límites de velocidad

Los límites por clave se devuelven en encabezados `X-RateLimit-*`. Cuando los superas, la API responde con `429` e incluye una sugerencia de `Retry-After`.

## Preguntas frecuentes

### ¿Cómo obtengo un logo para un dominio?

Envía una solicitud GET a `https://api.clearlogo.dev/logo/{domain}` donde `{domain}` es un nombre de host como `github.com`. No se requiere inicio de sesión para pruebas de bajo volumen. La respuesta es un PNG por defecto y funciona directamente en etiquetas `<img>`.

### ¿Cuál es la diferencia entre una clave de navegador y una de servidor?

Una clave de navegador es segura para enviar en código frontend y etiquetas `<img>`; las solicitudes se validan contra los dominios permitidos que configuras en la clave. Una clave de servidor se autentica mediante el encabezado `Authorization: Bearer` desde tu backend y nunca debe llegar al navegador.

### ¿Qué formatos de salida son compatibles?

`png` (por defecto), `webp` y `jpeg`. Cuando se omite el parámetro `format`, ClearLogo negocia el contenido desde el encabezado `Accept` de la solicitud — los navegadores modernos reciben WebP automáticamente cuando la API se carga vía `<img>`.