API Trovavio

Integra audit SEO e GEO nel tuo stack

Q: Come ottengo una API key Trovavio?

La API key si genera dal pannello Account ed è disponibile per gli utenti con piano Agenzia attivo. La chiave ha il prefisso trv_ e viene mostrata una sola volta.

Q: Quante richieste posso fare al mese?

Il piano Agenzia include 2.000 chiamate API al mese, che si azzerano all'inizio di ogni mese. Non ci sono limiti separati al minuto o al giorno.

API REST con autenticazione Bearer. Lanci scansioni, leggi punteggi SEO e GEO in JSON e generi contenuti con l'AI Lab, per automatizzare i workflow dei tuoi clienti. Base URL: https://trovavio.com

Ottieni la tua API key →

Autenticazione Crediti e limiti GET /sites GET /sites/:domain POST /audit POST /ai

Autenticazione

Gli endpoint richiedono il piano Agenzia. Genera la chiave da Account, sezione API Keys: ha il prefisso trv_ seguito da 32 caratteri esadecimali e viene mostrata una sola volta, quindi salvala in un posto sicuro. Nel database Trovavio ne conserva solo l'hash, mai la chiave in chiaro.

Ogni richiesta deve includere l'header Authorization. Tutte le risposte sono in formato JSON.

curl -H "Authorization: Bearer trv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://trovavio.com/api/v1/sites

Crediti e limiti

Ci sono due contatori separati, entrambi inclusi nel piano Agenzia e azzerati all'inizio di ogni mese. Non esistono limiti al minuto o al giorno: vale solo il tetto mensile.

Contatore	Incluso (Agenzia)	Cosa lo consuma
Chiamate API	2.000 al mese	Ogni richiesta a un endpoint `/api/v1/*` vale 1 chiamata.
Crediti AI	2.000 al mese	Solo `POST /api/v1/ai`: 1 credito per azione. Stesso pool della dashboard.

Costo per endpoint

Endpoint	Chiamate API	Crediti AI
GET /api/v1/sites	1	0
GET /api/v1/sites/:domain	1	0
POST /api/v1/audit	1	0 (numero pagine limitato dal piano, fino a 200 in mode site)
POST /api/v1/ai	1	1 per azione

Ogni risposta espone gli header X-RateLimit-Remaining (chiamate residue nel mese) e X-RateLimit-Reset (data di azzeramento). Al superamento del tetto mensile ricevi 429.

Endpoint

GET /api/v1/sites

Elenca tutti i siti dell'account con i punteggi dell'ultimo audit salvato. Non richiede parametri.

Esempio

curl -H "Authorization: Bearer trv_xxx" \
  https://trovavio.com/api/v1/sites

Risposta 200

{
  "sites": [
    {
      "domain": "ilmiosito.it",
      "score": 74,
      "seoScore": 78,
      "geoScore": 70,
      "prevScore": 71,
      "lastScanAt": "2026-07-01T08:00:00.000Z"
    }
  ],
  "total": 1
}

Errori

401	`INVALID_API_KEY`: chiave mancante, non valida o account senza piano Agenzia.
429	`API_RATE_LIMIT_EXCEEDED`: superate le 2.000 chiamate del mese.

GET /api/v1/sites/:domain

Dettaglio dell'ultimo audit di un singolo sito: punteggi SEO e GEO, variazione rispetto al controllo precedente ed elenco dei problemi.

Parametri (path)

Nome	Tipo	Descrizione
domain obbligatorio	string	Dominio del sito, senza protocollo ne www (es. `ilmiosito.it`).

Esempio

curl -H "Authorization: Bearer trv_xxx" \
  https://trovavio.com/api/v1/sites/ilmiosito.it

Risposta 200

{
  "domain": "ilmiosito.it",
  "score": 74,
  "seoScore": 78,
  "geoScore": 70,
  "prevScore": 71,
  "lastScanAt": "2026-07-01T08:00:00.000Z",
  "issues": [
    {
      "title": "Title troppo corto",
      "simpleTitle": "Il titolo della pagina è troppo corto",
      "category": "seo",
      "severity": "high",
      "description": "Il tag title è sotto i 10 caratteri.",
      "pages": ["/servizi"]
    }
  ]
}

Errori

400	`BAD_REQUEST`: dominio mancante o non valido.
401	`INVALID_API_KEY`: chiave non valida o account senza piano Agenzia.
404	`NOT_FOUND`: nessun audit salvato per quel dominio.
429	`API_RATE_LIMIT_EXCEEDED`: tetto mensile di chiamate superato.

POST /api/v1/audit

Lancia una scansione sincrona SEO e GEO di un dominio e restituisce il risultato strutturato. Consuma solo 1 chiamata API, nessun credito AI. In modalità site il numero di pagine è limitato dal piano (fino a 200).

Parametri (body JSON)

Nome	Tipo	Descrizione
domain obbligatorio	string	Dominio da analizzare, senza protocollo ne www (es. `ilmiosito.it`). Stesso formato di `GET /api/v1/sites/:domain`.
url alias deprecato	string	Accettato per retrocompatibilità al posto di `domain`. Se usato, la risposta include `deprecation_warning`. Usa `domain`.
mode opzionale	string	`single` (default) analizza una pagina; `site` effettua il crawl del sito.

Esempio

curl -X POST https://trovavio.com/api/v1/audit \
  -H "Authorization: Bearer trv_xxx" \
  -H "Content-Type: application/json" \
  -d '{"domain":"ilmiosito.it","mode":"single"}'

Risposta 200

{
  "domain": "ilmiosito.it",
  "score": 74,
  "seoScore": 78,
  "geoScore": 70,
  "prevScore": 71,
  "lastScanAt": "2026-07-05T09:12:00.000Z",
  "issues": [ ... ]
}

Errori

400	`BAD_REQUEST`: manca `domain` (o l'alias `url`).
401	`INVALID_API_KEY`: chiave non valida o account senza piano Agenzia.
429	`API_RATE_LIMIT_EXCEEDED`: tetto mensile di chiamate superato.
500	`INTERNAL_ERROR`: il sito non è raggiungibile o l'analisi è fallita.

POST /api/v1/ai

Genera un contenuto ottimizzato con l'AI Lab per un dominio già analizzato. Consuma 1 chiamata API e 1 credito AI per azione. Devi prima aver lanciato un audit del dominio.

Parametri (body JSON)

Nome	Tipo	Descrizione
domain obbligatorio	string	Dominio già presente in un audit (es. `ilmiosito.it`).
action obbligatorio	string	Azione AI. Valori: `title`, `description`, `h1`, `alts`, `schema`, `checklist`, `schema_org`, `faq_schema`, `llms_txt`.
vertical opzionale	string	Settore per calibrare il tono (es. `avvocato`, `medico`). Default `generico`.

Esempio

curl -X POST https://trovavio.com/api/v1/ai \
  -H "Authorization: Bearer trv_xxx" \
  -H "Content-Type: application/json" \
  -d '{"domain":"ilmiosito.it","action":"title","vertical":"avvocato"}'

Risposta 200

{
  "result": {
    "proposals": [
      "Studio Legale Rossi, Avvocato Civilista a Milano"
    ]
  }
}

Errori

400	`BAD_REQUEST`: `domain` o `action` mancante, oppure azione non valida (la risposta include `allowedActions`).
401	`INVALID_API_KEY`: chiave non valida o account senza piano Agenzia.
402	`CREDITS_EXHAUSTED`: crediti AI del mese esauriti (la risposta include `aiCredits`).
404	`NOT_FOUND`: nessun audit per quel dominio, lancia prima `POST /api/v1/audit`.
429	`API_RATE_LIMIT_EXCEEDED`: tetto mensile di chiamate superato.
500	`INTERNAL_ERROR`: errore di generazione. In questo caso il credito AI viene rimborsato automaticamente.

Hai un sito WordPress? Con il plugin Trovavio applichi i fix direttamente nell'editor, senza scrivere codice.

Domande frequenti

Come ottengo una API key Trovavio?

La API key si genera dal pannello Account, sezione API Keys, per gli utenti con piano Agenzia attivo. Ha il prefisso trv_ e viene mostrata una sola volta.

L'API Trovavio supporta l'audit GEO?

Sì. L'API restituisce sia il punteggio SEO sia il punteggio GEO (visibilità su ChatGPT, Claude, Perplexity, Gemini) per ogni sito analizzato.

Chiamate API e crediti AI sono la stessa cosa?

No, sono due contatori separati. Il piano Agenzia include 2.000 chiamate API al mese e 2.000 crediti AI al mese. Ogni richiesta a un endpoint conta come una chiamata API; solo POST /api/v1/ai consuma anche un credito AI.

Quante richieste posso fare al mese?

Il piano Agenzia include 2.000 chiamate API al mese, azzerate all'inizio di ogni mese. Non ci sono limiti separati al minuto o al giorno.