# Referência da API

> ClearLogo expõe um único endpoint HTTP, `GET /logo/{domain}`, que retorna um PNG (ou WebP/JPEG) do logo do domínio com proporção consistente e fundo transparente. Uso anônimo funciona para testes de baixo volume; tráfego em produção usa uma chave de navegador (cliente) ou de servidor (backend).

## Endpoint

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

`:domain` é um hostname sem scheme ou caminho, por exemplo `github.com`. A API retorna `image/png` por padrão.

## Parâmetros de query

| Nome | Tipo | Padrão | Notas |
| --- | --- | --- | --- |
| `size` | number | `128` | Dimensão de saída em px. Apenas quadrado. Valores permitidos: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024. |
| `content` | number | `80` | Espaço do logo dentro do canvas (50–100, passo 5). |
| `format` | `png \| webp \| jpeg` | `png` | Formato de saída. Auto-negociado pelo cabeçalho `Accept` — navegadores modernos recebem WebP automaticamente via `<img>`. |
| `theme` | `light \| dark` | `light` | Retorna a variante escura quando disponível, caso contrário volta para claro. |
| `token` | string | — | Chave de navegador usada no código do cliente. Origin ou Referer deve corresponder a um domínio permitido na chave. |

## Autenticação

Requisições anônimas funcionam para testes de baixo volume. Para tráfego em produção, use uma chave de navegador (cliente) ou uma chave 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"
```

## Limites de taxa

Limites por chave são retornados nos headers `X-RateLimit-*`. Quando você excede, a API responde com `429` e inclui uma dica `Retry-After`.

## Perguntas frequentes

### Como obtenho um logo para um domínio?

Envie uma requisição GET para `https://api.clearlogo.dev/logo/{domain}` onde `{domain}` é um hostname como `github.com`. Login não é necessário para testes de baixo volume. A resposta é um PNG por padrão e funciona diretamente em tags `<img>`.

### Qual é a diferença entre chave de navegador e chave de servidor?

Uma chave de navegador é segura para colocar em código frontend e tags `<img>`; requisições são validadas contra os domínios permitidos que você configura na chave. Uma chave de servidor autentica via header `Authorization: Bearer` do seu backend e nunca deve chegar ao navegador.

### Quais formatos de saída são suportados?

`png` (padrão), `webp` e `jpeg`. Quando o parâmetro `format` é omitido, ClearLogo negocia o conteúdo pelo header `Accept` da requisição — navegadores modernos recebem WebP automaticamente quando a API é carregada via tag `<img>`.