# API 레퍼런스

> ClearLogo 는 단일 HTTP 엔드포인트 `GET /logo/{domain}` 만 노출하며, 도메인의 로고를 일정한 비율과 투명 배경의 PNG(또는 WebP/JPEG)로 돌려줍니다. 낮은 볼륨 테스트는 익명으로도 가능하며, 프로덕션 트래픽은 브라우저 키(클라이언트) 또는 서버 키(백엔드)를 사용합니다.

## 엔드포인트

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

`:domain` 은 스킴과 경로가 없는 순수 호스트명입니다. 예: `github.com`. 응답은 기본 `image/png` 입니다.

## 쿼리 파라미터

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `size` | number | `128` | 출력 이미지 한 변의 픽셀 크기입니다. 정사각형만 지원하며 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024 값을 사용할 수 있습니다. |
| `content` | number | `80` | 캔버스 안에서 로고가 차지하는 비율입니다. 50–100 범위, 5 단위로 조정됩니다. |
| `format` | `png \| webp \| jpeg` | `png` | 출력 포맷. 미지정 시 `Accept` 헤더로 자동 협상됩니다. 현대 브라우저에서 `<img>` 로 불러오면 WebP가 자동 반환됩니다. |
| `theme` | `light \| dark` | `light` | 가능하면 다크 변형을 반환하고, 없으면 라이트 버전으로 대체합니다. |
| `token` | string | — | 클라이언트 코드에서 쓰는 브라우저 키입니다. Origin 또는 Referer 가 허용 도메인과 일치해야 합니다. |

## 인증

낮은 볼륨 테스트는 익명 요청으로도 가능합니다. 프로덕션에서는 브라우저 키(클라이언트용) 또는 서버 키(백엔드용) 중 하나를 붙이세요:

**브라우저**

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

**서버**

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

## 레이트 리밋

키별 한도는 `X-RateLimit-*` 헤더로 내려갑니다. 초과하면 API 는 `429`를 반환하고 `Retry-After` 힌트를 함께 보냅니다.

## 자주 묻는 질문

### 도메인 로고는 어떻게 가져오나요?

`https://api.clearlogo.dev/logo/{domain}` 에 GET 요청을 보내세요. `{domain}` 은 `github.com` 같은 순수 호스트명입니다. 낮은 볼륨 테스트는 로그인 없이 가능하며, 응답은 기본 PNG라 `<img>` 태그에서 바로 사용할 수 있습니다.

### 브라우저 키와 서버 키의 차이는 무엇인가요?

브라우저 키는 프론트엔드 코드와 `<img>` 태그에 그대로 노출해도 안전합니다. 키에 등록된 허용 도메인을 기준으로 요청이 검증됩니다. 서버 키는 `Authorization: Bearer` 헤더로 백엔드에서만 사용해야 하며, 절대 브라우저로 노출되어선 안 됩니다.

### 어떤 출력 포맷을 지원하나요?

`png`(기본), `webp`, `jpeg` 세 가지를 지원합니다. `format` 파라미터를 생략하면 요청의 `Accept` 헤더로 자동 협상되며, 현대 브라우저에서 `<img>` 로 불러올 때 WebP 가 자동 반환됩니다.