# API reference

> ClearLogo exposes a single HTTP endpoint, `GET /logo/{domain}`, that returns a PNG (or WebP/JPEG) of the domain's logo with consistent ratio and transparent background. Anonymous use works for low-volume testing; production traffic uses a browser key (client) or server key (backend).

## Endpoint

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

`:domain` is a bare hostname with no scheme or path, for example `github.com`. The API returns `image/png` by default.

## Query parameters

| Name | Type | Default | Notes |
| --- | --- | --- | --- |
| `size` | number | `128` | Output dimension in px. Square only. Allowed values: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024. |
| `content` | number | `80` | Logo footprint as % of the canvas (50–100, step 5). `50` = padded with visible margin; `100` = fills edge to edge. |
| `format` | `png \| webp \| jpeg` | `png` | Output format. Auto-negotiated from the `Accept` header when omitted — modern browsers receive WebP automatically via `<img>`. |
| `theme` | `light \| dark` | `light` | Returns the dark variant when available, otherwise falls back to light. |
| `token` | string | — | Browser key used from client code. Origin or Referer must match an allowed domain on the key. |

## Authentication

Anonymous requests work for low-volume testing. For production traffic, use a browser key (client) or a server key (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

Per-key limits are returned in `X-RateLimit-*` headers. When you exceed them the API responds with `429` and includes a `Retry-After` hint.

## FAQ

### How do I get a logo for a domain?

Send a GET request to `https://api.clearlogo.dev/logo/{domain}` where `{domain}` is a bare hostname like `github.com`. No login is required for low-volume testing. The response is a PNG by default and works directly in `<img>` tags.

### What's the difference between a browser key and a server key?

A browser key is safe to ship in frontend code and `<img>` tags; requests are validated against the allowed domains you configure on the key. A server key authenticates via the `Authorization: Bearer` header from your backend and must never reach the browser.

### What output formats are supported?

`png` (default), `webp`, and `jpeg`. When the `format` parameter is omitted, ClearLogo content-negotiates from the `Accept` request header — modern browsers receive WebP automatically when the API is loaded via an `<img>` tag.

### What are the rate limits?

Per-key limits are returned in `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` response headers. Exceeding the limit returns HTTP `429` with a `Retry-After` hint indicating how many seconds to wait before retrying.

### Can I get a transparent background or a square crop?

The API returns a transparent background by default and always crops to a square canvas. Use the `size` parameter (allowed: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024) for the exact pixel dimension and `content` (50–100, step 5) to control how much of the canvas the logo occupies.