L'API REST pour lire votre graphe, votre score et vos recommandations — et pour lancer des scans. Réponses JSON, authentification par clés API.
Tous les endpoints se trouvent sous le préfixe /v1 et ne sont servis qu'en HTTPS.
https://api.graphorank.com
Générez une clé depuis la page API et MCP de l'application. Les clés portent le préfixegr_, ne s'affichent en entier qu'une seule fois à la création et sont stockées hachées. Envoyez la clé dans l'en-tête X-Api-Key à chaque requête.
Les clés portent des scopes : read (toujours accordé) couvre tous les endpoints GET, tandis que write est requis pour créer des sites, lancer des scans et gérer les planifications. La session de l'application utilise à la place un JWT dans l'en-tête Authorization: Bearer — les clés API servent à l'accès programmatique.
# 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 site est un domaine racine de votre espace de travail. Ajoutez-le, prouvez que vous en êtes propriétaire, puis scannez-le. La preuve de propriété passe par un fichier well-known ou une balise meta — l'extrait exact avec le jeton se trouve dans Prise en main.
/v1/sitesListe les sites de votre espace de travail.
[
{
"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/sitesAjoute un site. Requiert le scope write. Renvoie 201 avec le nouveau site — verified vaut false au départ.
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}Récupère un site. La réponse a la même forme qu'un élément de la liste de GET /v1/sites.
/v1/sites/{site_id}/verifyLance la vérification de propriété avec la méthode choisie. La réponse inclut toujours le jeton de votre site : vous pouvez donc appeler ce endpoint une première fois pour le récupérer avant de publier le fichier ou la balise meta.
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"
}Un scan exécute tout le pipeline : exploration, analyse sémantique, construction du graphe, calcul du score. Son statut passe par queued → crawling → embedding → scoring → done (ou failed, avec un code d'erreur). Les scans comptent dans le quota mensuel de votre offre.
/v1/sites/{site_id}/scansLance un scan à la demande. Requiert le scope write. Renvoie 202 avec le scan en file d'attente ; quand le quota mensuel est épuisé, vous obtenez 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}Interrogez un scan jusqu'à ce que status vaille done, puis lisez son graphe, son score et ses recommandations.
{
"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"
}Le graphe complet de nœuds et d'arêtes d'un scan terminé, au même format que celui consommé par la vue interactive de l'application. Les grands graphes sont servis par pages à curseur de 1 000 éléments (d'abord les nœuds, puis les arêtes) : continuez à interroger avec le next_cursor renvoyé jusqu'à ce qu'il revienne null. L'objet meta est répété sur chaque page.
/v1/scans/{scan_id}/graphLes nœuds portent le rôle (pillar | cluster | hub | money | orphan | noindex), les identifiants de groupes structurels et sémantiques, le PageRank, les degrés entrant/sortant, la profondeur de clic et l'indexabilité. Les arêtes sont les liens internes.
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 est une référence de 0 à 100 de la visibilité d'un site auprès des moteurs génératifs. Le endpoint le renvoie avec les quatre scores par domaine affichés dans l'application — structurel, thématique, GEO et technique — ainsi que l'objet detail qui alimente les explications dans l'application. La méthodologie derrière le chiffre est propriétaire et appliquée à l'identique à chaque site.
/v1/scans/{scan_id}/scoreGraphRank et les quatre scores par domaine d'un scan terminé.
{
"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": { … }
}Des correctifs priorisés générés à partir du scan, chacun avec une gravité (P0 bloquant, P1 important, P2 souhaitable), des messages localisés et un objet meta contenant l'URL concernée et du contexte supplémentaire.
/v1/scans/{scan_id}/recommendationsListe les recommandations du scan, les plus graves d'abord.
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" }
}
]Suivez l'évolution du score d'un scan à l'autre et comparez-en deux pour voir exactement ce qui a changé — pages ajoutées et supprimées, orphelines, indexabilité.
/v1/sites/{site_id}/historySérie temporelle du GraphRank du site, un point par scan terminé, triée par horodatage.
[
{
"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}/diffCompare deux scans d'un même site. Sans paramètres, compare les deux derniers scans terminés. score_delta et sub_deltas valent null si l'un des scans n'a pas de score.
{
"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
}Un scan récurrent par site, avec un rapport envoyé par e-mail à la fin. Disponible dans les offres Pro et Agency — sur les offres inférieures, ces endpoints renvoient 402 quota_exceeded avec une suggestion de montée en gamme.
/v1/sites/{site_id}/scheduleCrée ou met à jour la planification du site (upsert — une par site). Requiert le 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}/scheduleLit la planification en cours. Renvoie 404 not_found si aucune n'est configurée.
/v1/sites/{site_id}/scheduleSupprime la planification. Requiert le scope write. Renvoie 204 No Content.
Où vous en êtes par rapport au quota de votre offre sur la période de facturation en cours. Les limites valent null quand elles sont illimitées.
/v1/usageOffre, statut de facturation et consommation du quota pour l'espace de travail.
{
"tier": "pro",
"billing_status": "active",
"scans_used": 4,
"scans_limit": 6,
"pages_limit": 500,
"sites_used": 2,
"sites_limit": 3
}Des clés au niveau de l'espace de travail pour l'accès programmatique, préfixées gr_ et stockées hachées. La clé en clair n'est renvoyée qu'une seule fois, dans la réponse de création — conservez-la dans un gestionnaire de secrets. Scopes : read (toujours inclus) couvre tous les endpoints GET ; write est requis pour tout ce qui modifie l'état.
/v1/api-keysListe les clés de l'espace de travail. Les secrets ne sont jamais renvoyés après la création.
[
{
"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-keysCrée une clé. Le champ key de la réponse est le seul moment où le secret est visible.
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}Révoque une clé. Elle cesse de fonctionner immédiatement. Renvoie 204 No Content.
Deux compartiments de jetons protègent l'API : un par IP cliente (appliqué avant l'authentification) et un par espace de travail (appliqué après). Quand vous atteignez une limite, la réponse est 429 assortie d'un en-tête Retry-After qui indique le nombre de secondes à attendre.
Les erreurs suivent le format application/problem+json — { type, title, status, detail, code }. Les erreurs de validation de requête (422) renvoient le tableau standard detail qui désigne les champs en cause.
{
"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"
}