Referência da API

Um endpoint, alguns controles, dois modos de autenticação.

Precisa de um caminho de migração antes da referência?

Comece com o guia de migração do Clearbit ou o guia do comprador da logo 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 em um fundo opaco correspondente ao tema (branco para claro, neutro escuro para escuro). 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.
`frame`	`fill, original`	`fill`	`fill` preenche o canvas (menos o padding) com o conteúdo visual do logo, descartando o espaço em branco da fonte. `original` preserva o enquadramento e as proporções originais do ícone fonte.
`padding`	number	`10`	Margem por lado ao redor do conteúdo enquadrado, como % do canvas (0–20, passo 5).
`shape`	`square, circle`	`square`	`square` é o enquadramento padrão. `circle` dimensiona o logo para caber dentro de um círculo inscrito, de modo que não seja cortado em um avatar circular — a saída ainda é uma imagem quadrada, sem máscara de transparência aplicada.
`part`	`full, logo, text`	`full`	Seleciona qual parte do logo servir — `full` (o logo inteiro), `logo` (o ícone/marca), ou `text` (o wordmark) — para domínios cujo logo foi dividido. Se a parte solicitada não estiver disponível, retorna o logo completo (ou uma imagem transparente para logos gerenciados como partes separadas). As partes podem ser raster (PNG) e são renderizadas em suas cores reais.
`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. Também define o fundo opaco: branco para `light`, neutro escuro para `dark`.
`token`	string	—	Chave de navegador usada no código do cliente. Origin ou Referer deve corresponder a um domínio permitido na chave.

Uma requisição típica usando os parâmetros principais:

GET https://api.clearlogo.dev/logo/github.com?size=128&frame=fill&padding=10&shape=square

Solicitar apenas o ícone/marca de um logo dividido com part:

GET https://api.clearlogo.dev/logo/github.com?size=128&part=logo

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

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

Servidor

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>.

Quais são os limites de taxa?

Os limites por chave são retornados nos headers de resposta X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Exceder o limite retorna HTTP 429 com uma dica Retry-After indicando quantos segundos aguardar antes de tentar novamente.

Posso obter fundo transparente ou recorte quadrado?

A saída é sempre uma imagem quadrada e opaca — não existe variante transparente. O fundo corresponde ao theme: branco para light e neutro escuro para dark. Dentro desse canvas quadrado você controla o enquadramento: frame (fill, original) escolhe entre preencher o canvas com o conteúdo do logo ou preservar as proporções originais do ícone fonte; padding (0–20, passo 5) define a margem por lado; e shape (square, circle) encaixa o logo dentro de um círculo inscrito quando definido como circle (ainda renderizado em imagem quadrada). Use size (permitidos: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024) para a dimensão exata em pixels. Para domínios cujo logo foi dividido, part (full, logo, text) seleciona o logo inteiro (full, o padrão), o ícone/marca (logo) ou o wordmark (text), retornando o logo completo quando uma parte não estiver disponível (ou uma imagem transparente para logos gerenciados como partes separadas).