Analizza i tuoi siti dal tuo codice

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

{
  "sites": [
    {
      "domain": "ilmiosito.it",
      "score": 74,
      "seoScore": 78,
      "geoScore": 70,
      "prevScore": 71,
      "metodoPunteggio": 2,
      "lastScanAt": "2026-08-22T09:12:00.000Z"
    }
  ],
  "total": 1
}

Salta a

Cosa puoi fare con l'API

Sei usi che tornano, dai più semplici ai più completi. Su ogni scheda trovi gli endpoint che servono.

• Rileggere i punteggi ogni notte

  Un cron chiede l'elenco dei siti e scrive i punteggi dove li guardi già: un foglio, un database, il tuo cruscotto.

  GET /sites

• Fermare un rilascio che peggiora il sito

  Dopo ogni pubblicazione la pipeline lancia l'analisi e interrompe la build se il punteggio scende sotto la soglia o compare un problema grave.

  POST /audit

• Avvisare il team quando un sito perde punti

  Confronti il punteggio con quello dell'analisi precedente e, se è calato, mandi un messaggio su Slack o una email.

  GET /sites

• Portare i problemi nel tuo gestionale

  Ogni problema arriva con titolo, gravità, spiegazione e pagine interessate: lo trasformi in un'attività su Jira, Notion o Trello.

  GET /sites/:domain

• Far scrivere i testi all'AI

  Per un sito già analizzato chiedi titolo, descrizione, H1, testi alternativi, dati strutturati, FAQ o llms.txt, pronti da rivedere e pubblicare.

  POST /ai

• Analizzare un cliente appena arriva

  Quando aggiungi un sito nel tuo CRM, lanci la prima analisi e hai subito il punteggio da citare nella proposta.

  POST /auditGET /sites/:domain

Cosa l'API non fa. Analizza e propone, non modifica il sito: per applicare le correzioni su WordPress c'è il plugin Trovavio. Non genera il report in PDF, che si scarica dalla dashboard, non gestisce team, etichette o marchio bianco e non manda webhook: i risultati si leggono quando servono.

Tre esempi pronti da copiare

Sono script completi. Cambia il dominio, metti la chiave nella variabile TROVAVIO_KEY e girano.

#!/usr/bin/env bash
set -euo pipefail
SOGLIA=70

RISPOSTA=$(curl -sS --max-time 300 -X POST https://trovavio.com/api/v1/audit \
  -H "Authorization: Bearer $TROVAVIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"ilmiosito.it","mode":"site"}')

PUNTEGGIO=$(echo "$RISPOSTA" | jq -e '.score')
echo "Punteggio: $PUNTEGGIO"
echo "$RISPOSTA" | jq -r '.issues[] | select(.severity=="high") | "- \(.title)"'

[ "$PUNTEGGIO" -ge "$SOGLIA" ] || { echo "Sotto la soglia di $SOGLIA"; exit 1; }

const risposta = await fetch("https://trovavio.com/api/v1/sites", {
  headers: { Authorization: `Bearer ${process.env.TROVAVIO_KEY}` },
});
if (!risposta.ok) throw new Error(`Trovavio ha risposto ${risposta.status}`);

const { sites } = await risposta.json();
const calati = sites.filter((s) => s.prevScore != null && s.score < s.prevScore);

if (calati.length) {
  await fetch(process.env.SLACK_WEBHOOK, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: calati.map((s) => `${s.domain}: da ${s.prevScore} a ${s.score}`).join("\n"),
    }),
  });
}

import json, os, urllib.request

richiesta = urllib.request.Request(
    "https://trovavio.com/api/v1/sites/ilmiosito.it",
    headers={"Authorization": "Bearer " + os.environ["TROVAVIO_KEY"]},
)
sito = json.load(urllib.request.urlopen(richiesta))

for problema in sito["issues"]:
    if problema["severity"] == "high":
        print(problema["title"], problema["pages"])  # qui crei l'attività

Autenticazione

Gli endpoint sono per chi ha il piano Pro o Agenzia, prova gratuita compresa. 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, per esempio fra le variabili segrete della tua pipeline. 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. Puoi tenere fino a 20 chiavi attive, una per integrazione, e revocarne una senza toccare le altre. La chiave legge i siti dello spazio di lavoro del tuo account: se lavori in agenzia con più persone, tutti vedono gli stessi siti e le chiamate si sommano sulla stessa quota.

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

Piani e limiti

L'API è inclusa nei piani Pro e Agenzia. Free e Solo non la includono: con la chiave di un account su uno di questi piani ogni endpoint risponde 401. Non ci sono limiti al minuto: contano il tetto mensile di chiamate e, per le analisi, il tetto giornaliero del piano.

Le chiamate API si azzerano il primo di ogni mese. I crediti AI sono gli stessi della dashboard, un solo conteggio: durante la prova gratuita del Pro sono 60. Le analisi al giorno sono condivise con la dashboard: una analisi lanciata dall'API vale come una lanciata a mano.

Costo per endpoint

Ogni risposta espone tre header: X-RateLimit-Limit (il tetto del mese), X-RateLimit-Remaining (le chiamate che restano) e X-RateLimit-Reset (quando il conteggio si azzera). Superato il tetto ricevi 429 fino a quella data.

Endpoint

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

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

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

{
  "domain": "ilmiosito.it",
  "score": 74,
  "seoScore": 78,
  "geoScore": 70,
  "prevScore": 71,
  "metodoPunteggio": 2,
  "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"]
    }
  ]
}

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

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

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

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

Tutti gli errori in un posto

Gli errori hanno sempre un codice leggibile dalla macchina nel campo error; dove serve, message lo spiega in italiano.

Domande frequenti