API 레퍼런스

기본 URL

모든 API 요청은 이 루트로 보냅니다:

https://www.7275.com/api/v1

HTTPS가 필수입니다. HTTP 요청은 거부됩니다(리디렉션되지 않음).

인증

모든 요청의 Authorization 헤더에 Bearer 토큰이 필요합니다. 대시보드 → 설정 → API Keys에서 발급하세요. 키는 live와 test 두 종류가 있으며 각각 자기 환경에만 접근할 수 있습니다.

curl https://www.7275.com/api/v1/accounts \
  -H "Authorization: Bearer dxk_live_...your-key..."

• live 키 형식: dxk_live_로 시작하는 64자
• test 키 형식: dxk_test_로 시작하며 sandbox 계정으로 제한
• 프런트엔드 코드에서 키를 직접 사용하지 마세요 — 자체 백엔드를 프록시로 거치세요
• 유출되면 대시보드에서 즉시 폐기하고 다시 발급하세요

Claude Desktop / Cursor에서 바로 사용(MCP 서버)

의존성이 없는 Model Context Protocol 서버를 제공하므로 Claude Desktop, Cursor 같은 MCP 클라이언트가 AdWhiz 상태를 직접 읽을 수 있습니다. 코드를 작성할 필요 없이 설정 블록을 복사하고 API 키를 붙여 넣은 뒤 클라이언트를 다시 시작하면 됩니다.

• 읽기 전용 도구 5개: 광고 계정 목록, AI 추천 보기, 이번 달 절감액, 최근 활동, API 할당량 확인
• 쓰기 도구(apply / pause)는 의도적으로 아직 공개하지 않았습니다 — 옵티마이저가 shadow mode를 벗어나고 이를 통제할 보정 근거가 확보된 후 공개합니다
• Node 18+ 단일 스크립트. npm install 불필요. 오프라인 / 망 분리(airgapped) 환경에서도 문제없이 실행됩니다
• API 키는 사용자 컴퓨터 밖으로 나가지 않습니다. 모든 요청은 HTTPS로 www.7275.com에 직접 연결됩니다

Claude Desktop의 claude_desktop_config.json(macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\)에 다음을 추가하세요:

{
  "mcpServers": {
    "adwhiz": {
      "command": "node",
      "args": ["/path/to/mcp-server/src/index.mjs"],
      "env": {
        "ADWHIZ_API_KEY": "dxk_live_..."
      }
    }
  }
}

전체 설치 가이드, Cursor 설정, 문제 해결은 GitHub에서 확인하세요: github.com/dexun-inc/adwhiz/mcp-server.

엔드포인트

v1 API는 13개의 핵심 엔드포인트를 제공하며 신원 확인, 계정 조회, 추천 생성(적용은 아직 사용할 수 없음), 감사 로그, API 키 관리, 할당량 조회, 변경 로그 피드를 다룹니다.

요청 예시

3개 플랫폼의 새 최적화 추천 생성:

curl -X POST https://www.7275.com/api/v1/recommendations/generate \
  -H "Authorization: Bearer dxk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "ga-548-203-7184",
    "platforms": ["google_ads", "meta_ads", "tiktok_ads"],
    "window": "7d"
  }'

응답 예시:

{
  "summary": "Pausing 3 high-CPA keywords and reallocating budget...",
  "recommendations": [
    {
      "id": "rec_001",
      "type": "pause_keyword",
      "target": { "accountId": "ga-548-203-7184", "keywordText": "wool socks" },
      "title": "Pause broad-match 'wool socks'",
      "reason": "7-day CPA $45.82 vs target $8",
      "expectedImpact": "Save ~$412/week",
      "confidence": "high"
    }
  ]
}

/changelog 증분 폴링

/api/v1/changelog는 공개 엔드포인트(API 키 불필요)이며 대역폭을 아끼는 네 가지 옵션을 지원합니다: ETag + If-None-Match, Last-Modified + If-Modified-Since(curl -z), 날짜로 필터링하는 ?since=YYYY-MM-DD, 크기를 제한하는 ?limit=N. SDK와 cron 스크립트는 이를 조합해 같은 JSON을 다시 내려받지 않고도 자주 폴링할 수 있습니다.

# 1. First call — store the ETag (or Last-Modified) you get back.
curl -i 'https://www.7275.com/api/v1/changelog?limit=10'

# 2. Subsequent calls — pass the stored ETag.
#    Server returns 304 with empty body if nothing has shipped.
curl -i 'https://www.7275.com/api/v1/changelog?limit=10' \
  -H 'If-None-Match: "abc123..."'

# 3. Or anchor on a date instead of an ETag.
#    Only entries whose `date >= since` come back; pair with ?limit
#    to cap the response size.
curl 'https://www.7275.com/api/v1/changelog?since=2026-01-01&limit=20'

# 4. curl -z for Last-Modified-style conditional GET (no ETag needed):
curl -z 'Mon, 20 May 2026 00:00:00 GMT' \
  'https://www.7275.com/api/v1/changelog'

속도 제한

상위 Google / Meta / TikTok API 할당량에 부담을 주지 않도록 구독 요금제별로 차등 적용됩니다:

• 프로페셔널: 분당 120회 요청
• 비즈니스: 분당 600회 요청
• 엔터프라이즈: 맞춤(일반적으로 분당 3,000회 요청)
• 한도를 넘으면 429 + retry-after 헤더가 반환됩니다 — 지수 백오프를 권장합니다

오류 코드

모든 오류는 error.code, error.message, error.request_id를 포함한 JSON으로 반환됩니다: