Riferimento API

URL di base

Tutte le richieste API vanno a questa radice:

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

HTTPS è obbligatorio. Le richieste HTTP vengono rifiutate (non reindirizzate).

Autenticazione

Ogni richiesta richiede un token Bearer nell'header Authorization. Generane uno da dashboard → Impostazioni → API Keys. Le key esistono in versione live e test e possono accedere solo al proprio ambiente.

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

• Formato key live: inizia con dxk_live_, 64 caratteri
• Formato key test: inizia con dxk_test_, limitata all'account sandbox
• Non usare mai le key nel codice front-end: fai da proxy tramite il tuo backend
• Se una key viene esposta, revocala e rigenerala subito dalla dashboard

Usalo direttamente da Claude Desktop / Cursor (server MCP)

Distribuiamo un server Model Context Protocol senza dipendenze, così i client MCP come Claude Desktop e Cursor possono leggere direttamente lo stato del tuo AdWhiz. Nessun codice da scrivere: copia un blocco di configurazione, incolla la tua API key e riavvia il client.

• Cinque strumenti di sola lettura: elenco degli account pubblicitari, suggerimenti dell'AI, risparmi del mese, attività recenti, quota API
• Gli strumenti di scrittura (apply / pause) volutamente non sono ancora esposti: aspettano che l'ottimizzatore esca dalla shadow mode e che ci siano prove di calibrazione per abilitarli
• Un unico script Node 18+. Zero npm install. Funziona anche su macchine offline / isolate (airgapped)
• La tua API key non lascia mai il tuo computer. Tutte le richieste vanno in HTTPS direttamente ad www.7275.com

Aggiungi questo al file claude_desktop_config.json di Claude Desktop (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_..."
      }
    }
  }
}

Guida completa all'installazione, configurazione di Cursor e risoluzione dei problemi su GitHub: github.com/dexun-inc/adwhiz/mcp-server.

Endpoint

L'API v1 espone 13 endpoint principali: identità, lettura degli account, generazione dei suggerimenti (applicarli non è ancora disponibile), log di audit, gestione delle API key, verifica della quota e feed del changelog.

Richiesta di esempio

Genera nuovi suggerimenti di ottimizzazione per le tre piattaforme:

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"
  }'

Risposta di esempio:

{
  "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"
    }
  ]
}

Polling incrementale di /changelog

/api/v1/changelog è un endpoint pubblico (nessuna API key richiesta) con quattro opzioni per risparmiare banda: ETag + If-None-Match, Last-Modified + If-Modified-Since (curl -z), ?since=YYYY-MM-DD per filtrare per data e ?limit=N per limitare la dimensione. SDK e script cron possono combinarle per interrogare spesso senza riscaricare lo stesso 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'

Limiti di frequenza

Differenziati per piano di abbonamento, per non sovraccaricare le quote a monte di Google / Meta / TikTok:

• Professional: 120 richieste/minuto
• Business: 600 richieste/minuto
• Enterprise: personalizzato (in genere 3.000 richieste/minuto)
• Oltre il limite si riceve 429 + header retry-after: consigliato il backoff esponenziale

Codici di errore

Tutti gli errori restituiscono JSON con error.code, error.message ed error.request_id: