SeoPrimo nei tuoi strumenti.
API REST con OpenAPI pubblica, server MCP per Claude, Cursor e n8n, webhook firmati e tre workflow n8n da scaricare. Le stesse funzioni del pannello, con gli stessi crediti.
Quattro porte,
un motore.
API pubblica /api/v1
- Siti, audit, parole chiave, posizioni, backlink, Score, report
- Esempi in curl, Python e JavaScript
- Errori uniformi e dry_run per il prezzo
Server MCP per agenti
- 11 tool pronti per Claude, Cursor e n8n
- Streamable HTTP, nessuna sessione
- Stessa chiave e stessi crediti dell'API
Workflow n8n
- Nodo HTTP Request, nodo MCP Client o Webhook
- Tre workflow JSON da scaricare
- Credenziali per nome, nessun segreto nel file
Eventi in uscita
- audit.completed, score.changed, rank.changed
- report.ready, credits.low, agent.completed
- Firma HMAC-SHA256 e tentativi con attesa crescente
Dalla chiave alla prima chiamata.
- Crea una chiave. Nel pannello apri seoprimo.it/app/integrations/keys (Integrazioni, Chiavi API), scegli un nome e gli scope:
readper leggere,writeper avviare operazioni e creare siti. Per l'uso normale servono entrambi. La chiave ha la formasp_live_…e si vede una sola volta: copiala subito. Noi conserviamo solo il suo hash. - Fai la prima chiamata. Il saldo dei crediti è gratis e prova che la chiave funziona.
- Chiedi il prezzo prima di spendere. Aggiungi
?dry_run=truea qualunque POST: la risposta è la stima, non parte niente e non si addebita niente.
export SEOPRIMO_KEY="sp_live_..."
# 1. your credit balance (free)
curl -sS https://seoprimo.it/api/v1/credits \
-H "Authorization: Bearer $SEOPRIMO_KEY"
# 2. the price of a quick audit, without running it
curl -sS -X POST "https://seoprimo.it/api/v1/sites/<site_id>/audits?dry_run=true" \
-H "Authorization: Bearer $SEOPRIMO_KEY"
# {"estimated_credits": 10}
import os
import httpx
api = httpx.Client(
base_url="https://seoprimo.it/api/v1",
headers={"Authorization": f"Bearer {os.environ['SEOPRIMO_KEY']}"},
timeout=30,
)
print(api.get("/credits").json())
# the price of a quick audit, without running it
print(api.post("/sites/<site_id>/audits", params={"dry_run": "true"}).json())
# {'estimated_credits': 10}
// Node 18+ (global fetch)
const headers = { Authorization: `Bearer ${process.env.SEOPRIMO_KEY}` };
const API = "https://seoprimo.it/api/v1";
console.log(await (await fetch(`${API}/credits`, { headers })).json());
// the price of a quick audit, without running it
const dry = await fetch(`${API}/sites/<site_id>/audits?dry_run=true`, { method: "POST", headers });
console.log(await dry.json()); // { estimated_credits: 10 }
Il percorso completo (sito, audit rapido, attesa del risultato, Score) è nella guida all'API.
Crediti, limiti e sicurezza.
- Gli stessi crediti del pannello. Le chiamate a pagamento scalano i crediti dell'attività; senza crediti la risposta è
402conneededeavailable. I lavori che falliscono restituiscono i crediti. - 60 richieste al minuto per chiave, condivise fra API REST e MCP. Oltre il limite la risposta è
429con l'intestazioneRetry-After. - Fino a 20 chiavi attive per attività e 10 webhook. Le chiavi e i webhook si gestiscono dal pannello (titolare o amministratore) e si revocano con un clic.
- Una chiave vede solo la sua attività. Un sito di un'altra attività risponde
404, come se non esistesse. - Solo HTTPS. La chiave viaggia nell'intestazione
Authorization, mai nell'indirizzo. Tienila nelle variabili d'ambiente o in un gestore di segreti, non nel codice.
Per un agente che deve solo leggere, crea una chiave con il solo scope read: non potrà né creare siti né spendere crediti.
Documentazione interattiva.
L'API è descritta da una specifica OpenAPI 3.1 pubblica: puoi leggerla, importarla in Postman, Insomnia o in un generatore di client, oppure provare le chiamate nel browser.
- /api/v1/docs: Swagger UI, con «Authorize» per inserire la chiave e «Try it out» su ogni endpoint
- /api/v1/redoc: la stessa documentazione in ReDoc, da leggere
- /api/v1/openapi.json: la specifica OpenAPI in JSON
Swagger UI e ReDoc caricano i loro file da una CDN: la documentazione richiede internet nel tuo browser, l'API no.
Crea la chiave.
Il resto è codice.
Le chiavi si creano dal pannello, in Integrazioni. Se non hai ancora un account, scrivici.