SeoPrimo · SEO per Google e per le AI · presenza garantita, o rimborso della quota di attivazione · Audit gratuito del tuo sito
SeoPrimo · SEO per Google e per le AI · presenza garantita, o rimborso della quota di attivazione · Audit gratuito del tuo sito
seoprimo
— Sviluppatori

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.

REST
API con chiavi e scope
MCP
11 tool per i tuoi agenti
HMAC
webhook firmati
01
Le guide
Quattro porte
OpenAPI pubblica· una chiave per tutte· stessi crediti del pannello

Quattro porte,
un motore.

i API REST

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
autenticazioneBearer
Guida all'API
ii MCP

Server MCP per agenti

  • 11 tool pronti per Claude, Cursor e n8n
  • Streamable HTTP, nessuna sessione
  • Stessa chiave e stessi crediti dell'API
indirizzo/mcp
Configura MCP
iii n8n

Workflow n8n

  • Nodo HTTP Request, nodo MCP Client o Webhook
  • Tre workflow JSON da scaricare
  • Credenziali per nome, nessun segreto nel file
workflow3
Usa n8n
iv Webhook

Eventi in uscita

  • audit.completed, score.changed, rank.changed
  • report.ready, credits.low, agent.completed
  • Firma HMAC-SHA256 e tentativi con attesa crescente
firmaHMAC
Guida ai webhook
— Inizia

Dalla chiave alla prima chiamata.

  1. Crea una chiave. Nel pannello apri seoprimo.it/app/integrations/keys (Integrazioni, Chiavi API), scegli un nome e gli scope: read per leggere, write per avviare operazioni e creare siti. Per l'uso normale servono entrambi. La chiave ha la forma sp_live_… e si vede una sola volta: copiala subito. Noi conserviamo solo il suo hash.
  2. Fai la prima chiamata. Il saldo dei crediti è gratis e prova che la chiave funziona.
  3. Chiedi il prezzo prima di spendere. Aggiungi ?dry_run=true a qualunque POST: la risposta è la stima, non parte niente e non si addebita niente.
curl
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}
Python
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}
JavaScript
// 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.

— Da sapere

Crediti, limiti e sicurezza.

  • Gli stessi crediti del pannello. Le chiamate a pagamento scalano i crediti dell'attività; senza crediti la risposta è 402 con needed e available. I lavori che falliscono restituiscono i crediti.
  • 60 richieste al minuto per chiave, condivise fra API REST e MCP. Oltre il limite la risposta è 429 con l'intestazione Retry-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.

— Strumenti

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.

Swagger UI e ReDoc caricano i loro file da una CDN: la documentazione richiede internet nel tuo browser, l'API no.

Serve un account attivo

Crea la chiave.
Il resto è codice.

Le chiavi si creano dal pannello, in Integrazioni. Se non hai ancora un account, scrivici.

Cosa trovi nella guida
API
Esempi pronti
curl, Python, JavaScript
MCP
Per i tuoi agenti
Claude, Cursor, n8n
n8n
Workflow scaricabili
tre file JSON