L’API REST per leggere il tuo grafo, punteggio e raccomandazioni — e per avviare scansioni. Risposte JSON, autenticate con API key.
Tutti gli endpoint si trovano sotto il prefisso /v1 e vengono serviti solo via HTTPS.
https://api.graphorank.com
Genera una chiave dalla pagina API & MCP dell’app. Le chiavi hanno il prefissogr_, mostrato per intero solo alla creazione, e vengono salvate come hash. Invia la chiave nell’header X-Api-Key a ogni richiesta.
Le chiavi hanno degli scope: read (sempre concesso) copre ogni endpoint GET, mentre write è necessario per creare siti, avviare scansioni e gestire le pianificazioni. La sessione dell’app usa invece un JWT nell’header Authorization: Bearer — le API key servono per l’accesso programmatico.
# Create a key in the app under API & MCP — keys start with "gr_" export GRAPHORANK_API_KEY="gr_..." curl https://api.graphorank.com/v1/sites \ -H "X-Api-Key: $GRAPHORANK_API_KEY"
Un sito è un dominio radice nel tuo workspace. Aggiungilo, dimostra di esserne proprietario, poi scansionalo. La verifica della proprietà usa un file well-known o un meta tag — lo snippet esatto del token si trova in Per iniziare.
/v1/sitesElenca i siti nel tuo workspace.
[
{
"id": "0d9f1c4e-6a3b-4f6e-9a2d-1b7c8e5f0a21",
"root_url": "https://rovere-arredamenti.com",
"label": "Rovere Arredamenti",
"verified": true,
"created_at": "2026-06-02T08:15:00Z"
}
]/v1/sitesAggiunge un sito. Richiede lo scope write. Restituisce 201 con il nuovo sito — verified parte come false.
curl -X POST https://api.graphorank.com/v1/sites \
-H "X-Api-Key: $GRAPHORANK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"root_url": "https://rovere-arredamenti.com", "label": "Rovere Arredamenti"}'{
"id": "0d9f1c4e-6a3b-4f6e-9a2d-1b7c8e5f0a21",
"root_url": "https://rovere-arredamenti.com",
"label": "Rovere Arredamenti",
"verified": false,
"created_at": "2026-07-03T09:12:44Z"
}/v1/sites/{site_id}Recupera un singolo sito. La risposta ha la stessa struttura di un elemento della lista di GET /v1/sites.
/v1/sites/{site_id}/verifyEsegue il controllo di proprietà con il metodo scelto. La risposta include sempre il token del sito, così puoi richiamare questo endpoint una volta per recuperarlo prima di pubblicare il file o il meta tag.
curl -X POST https://api.graphorank.com/v1/sites/{site_id}/verify \
-H "X-Api-Key: $GRAPHORANK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"method": "file"}'{
"verified": true,
"method": "file",
"token": "9Kd2mQx7Ln4pTv8waZrGQg",
"detail": "token found at /.well-known/graphorank-verify.txt"
}Una scansione esegue l’intera pipeline: scansione, analisi semantica, costruzione del grafo, punteggio. Il suo stato passa attraverso queued → crawling → embedding → scoring → done (oppure failed, con un codice di errore). Le scansioni contano ai fini della quota mensile del tuo piano.
/v1/sites/{site_id}/scansAvvia una scansione on demand. Richiede lo scope write. Restituisce 202 con la scansione in coda; quando la quota mensile è esaurita ottieni 402 quota_exceeded.
curl -X POST https://api.graphorank.com/v1/sites/{site_id}/scans \
-H "X-Api-Key: $GRAPHORANK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"render_mode": "auto"}'{
"id": "7f2a4c0e-9d1b-4b8a-b6c3-2e5f8a7d9c10",
"site_id": "0d9f1c4e-6a3b-4f6e-9a2d-1b7c8e5f0a21",
"status": "queued",
"render_mode": "auto",
"pages_count": 0,
"error_code": null,
"error_detail": null,
"started_at": null,
"finished_at": null,
"created_at": "2026-07-03T09:38:12Z"
}/v1/scans/{scan_id}Interroga periodicamente una scansione finché lo stato non è done, poi leggi il suo grafo, punteggio e raccomandazioni.
{
"id": "7f2a4c0e-9d1b-4b8a-b6c3-2e5f8a7d9c10",
"site_id": "0d9f1c4e-6a3b-4f6e-9a2d-1b7c8e5f0a21",
"status": "done",
"render_mode": "auto",
"pages_count": 214,
"error_code": null,
"error_detail": null,
"started_at": "2026-07-03T09:38:20Z",
"finished_at": "2026-07-03T09:40:41Z",
"created_at": "2026-07-03T09:38:12Z"
}Il grafo completo di nodi/archi di una scansione completata, nello stesso formato usato dalla vista interattiva dell’app. I grafi di grandi dimensioni vengono serviti in pagine cursor da 1.000 elementi (prima i nodi, poi gli archi): continua a richiedere con il next_cursor restituito finché non torna null. L’oggetto meta si ripete a ogni pagina.
/v1/scans/{scan_id}/graphI nodi riportano il ruolo (pillar | cluster | hub | money | orphan | noindex), gli id dei cluster strutturali e semantici, PageRank, grado in entrata/uscita, profondità di click e indicizzabilità. Gli archi sono link interni.
curl "https://api.graphorank.com/v1/scans/{scan_id}/graph?cursor=0" \
-H "X-Api-Key: $GRAPHORANK_API_KEY"{
"nodes": [
{
"id": "d41f4d6a-1a52-4b0e-8c7a-b9e4f1c2a3d4",
"url": "https://rovere-arredamenti.com/collezioni/tavoli",
"role": "pillar",
"cluster_struct": 3,
"cluster_sem": 2,
"pagerank": 0.0184,
"in_degree": 42,
"out_degree": 18,
"depth": 1,
"indexable": true
}
],
"edges": [
{ "s": "d41f4d6a-…", "t": "9c2b1e07-…", "type": "internal" }
],
"meta": {
"nodes": 214,
"edges": 1310,
"modularity": 0.62,
"avg_depth": 2.4,
"orphan_count": 7,
"cluster_agreement": 0.81
},
"next_cursor": 1000
}GraphRank è un benchmark da 0 a 100 di quanto un sito sia visibile ai motori generativi. L’endpoint lo restituisce insieme ai quattro punteggi per area mostrati nell’app — strutturale, tematico, GEO e tecnico — più l’oggetto detail che alimenta le spiegazioni nell’app. La metodologia dietro il numero è proprietaria e viene applicata in modo identico a ogni sito.
/v1/scans/{scan_id}/scoreGraphRank e i quattro punteggi per area di una scansione completata.
{
"scan_id": "7f2a4c0e-9d1b-4b8a-b6c3-2e5f8a7d9c10",
"graphrank": 68.4,
"sub_structural": 78.2,
"sub_topical": 71.5,
"sub_geo": 54.1,
"sub_tech": 49.8,
"detail": { … }
}Correzioni prioritizzate generate dalla scansione, ciascuna con una gravità (P0 bloccante, P1 importante, P2 facoltativa), messaggi localizzati e un oggetto meta con l’URL interessato più contesto aggiuntivo.
/v1/scans/{scan_id}/recommendationsElenca le raccomandazioni della scansione, dalla più grave.
curl "https://api.graphorank.com/v1/scans/{scan_id}/recommendations?severity=P0" \
-H "X-Api-Key: $GRAPHORANK_API_KEY"[
{
"id": "b7e3a9c1-5d2f-4e8b-a1c6-3f9d7e2b8a54",
"page_id": "9c2b1e07-4f6a-4d3e-b8a1-7c5e9f2d1b36",
"type": "orphan_page",
"severity": "P0",
"message_it": "Pagina orfana: nessun link interno la raggiunge. Collegala dalla sezione pertinente.",
"message_en": "Orphan page: no internal link reaches it and crawlers struggle to find it. Link it from the relevant section.",
"meta": { "url": "https://rovere-arredamenti.com/blog/cura-del-rovere" }
}
]Traccia come evolve il punteggio tra le scansioni e confronta due scansioni per vedere esattamente cosa è cambiato — pagine aggiunte e rimosse, pagine orfane, indicizzabilità.
/v1/sites/{site_id}/historySerie storica del GraphRank per il sito, un punto per ogni scansione completata, ordinata per timestamp.
[
{
"ts": "2026-06-05T03:00:00Z",
"graphrank": 64.2,
"sub_structural": 76.0,
"sub_topical": 70.1,
"sub_geo": 50.3,
"sub_tech": 47.9
},
{
"ts": "2026-07-03T09:40:41Z",
"graphrank": 68.4,
"sub_structural": 78.2,
"sub_topical": 71.5,
"sub_geo": 54.1,
"sub_tech": 49.8
}
]/v1/sites/{site_id}/diffConfronta due scansioni dello stesso sito. Senza parametri confronta le due scansioni completate più recenti. score_delta e sub_deltas sono null quando una delle due scansioni non ha un punteggio.
{
"from_scan": "5b1c8e2d-7a4f-4c9b-8d3e-1f6a2c7b9e05",
"to_scan": "7f2a4c0e-9d1b-4b8a-b6c3-2e5f8a7d9c10",
"score_delta": 4.2,
"sub_deltas": { "structural": 2.2, "topical": 1.4, "geo": 3.8, "tech": 1.9 },
"pages_added": {
"count": 6,
"sample": ["https://rovere-arredamenti.com/blog/cura-del-rovere"]
},
"pages_removed": {
"count": 1,
"sample": ["https://rovere-arredamenti.com/vecchia-landing"]
},
"orphans_from": 12,
"orphans_to": 7,
"indexable_from": 195,
"indexable_to": 203
}Una scansione ricorrente per sito, con un report via email al completamento. Disponibile sui piani Pro e Agency — sui piani inferiori questi endpoint restituiscono 402 quota_exceeded con un suggerimento di upgrade.
/v1/sites/{site_id}/scheduleCrea o aggiorna la pianificazione del sito (upsert — una per sito). Richiede lo scope write.
curl -X POST https://api.graphorank.com/v1/sites/{site_id}/schedule \
-H "X-Api-Key: $GRAPHORANK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"freq": "weekly", "day": 0, "time": "03:00", "recipients": ["seo@rovere-arredamenti.com"]}'{
"id": "3e8d1f5a-2b7c-4a9e-b4d1-6c8f2a5e7b93",
"site_id": "0d9f1c4e-6a3b-4f6e-9a2d-1b7c8e5f0a21",
"freq": "weekly",
"day": 0,
"time": "03:00",
"recipients": ["seo@rovere-arredamenti.com"],
"active": true,
"last_run_at": null,
"created_at": "2026-07-03T10:02:19Z"
}/v1/sites/{site_id}/scheduleLegge la pianificazione attuale. Restituisce 404 not_found quando non ne è configurata nessuna.
/v1/sites/{site_id}/scheduleRimuove la pianificazione. Richiede lo scope write. Restituisce 204 No Content.
A che punto sei rispetto alla quota del tuo piano nel periodo di fatturazione corrente. I limiti tornano null quando sono illimitati.
/v1/usagePiano, stato di fatturazione e consumo della quota per il workspace.
{
"tier": "pro",
"billing_status": "active",
"scans_used": 4,
"scans_limit": 6,
"pages_limit": 500,
"sites_used": 2,
"sites_limit": 3
}Chiavi a livello di workspace per l’accesso programmatico, con prefisso gr_ e salvate come hash. La chiave in chiaro viene restituita una sola volta, nella risposta di creazione — conservala in un secret manager. Scope: read (sempre incluso) copre ogni endpoint GET; write è necessario per qualsiasi operazione che modifica lo stato.
/v1/api-keysElenca le chiavi del workspace. I secret non vengono mai restituiti dopo la creazione.
[
{
"id": "a1f7c3e9-8b2d-4e6a-9c5f-2d7b4a8e1c60",
"scopes": ["read"],
"created_at": "2026-06-20T11:05:00Z",
"last_used_at": "2026-07-03T09:41:07Z"
}
]/v1/api-keysCrea una chiave. Il campo key nella risposta è l’unico momento in cui il secret è visibile.
curl -X POST https://api.graphorank.com/v1/api-keys \
-H "X-Api-Key: $GRAPHORANK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"scopes": ["read", "write"]}'{
"id": "e4b8d2f6-1c9a-4d7e-8b3c-5f2a7d9c1e48",
"key": "gr_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"scopes": ["read", "write"],
"created_at": "2026-07-03T10:15:33Z"
}/v1/api-keys/{key_id}Revoca una chiave. Smette di funzionare immediatamente. Restituisce 204 No Content.
Due token bucket proteggono l’API: uno per IP del client (applicato prima dell’autenticazione) e uno per workspace (applicato dopo). Quando raggiungi un limite la risposta è 429 con un header Retry-After che indica quanti secondi attendere.
Gli errori usano il formato application/problem+json — { type, title, status, detail, code }. Gli errori di validazione della richiesta (422) restituiscono il campo standard detail con l’array che indica i campi non validi.
{
"type": "about:blank",
"title": "Quota Exceeded",
"status": 402,
"detail": "monthly scan quota reached (6/6): upgrade your plan or wait for the next period",
"code": "quota_exceeded"
}