De REST API om je grafiek, score en aanbevelingen te lezen — en om scans te starten. JSON-responses, geauthenticeerd met API-sleutels.
Alle endpoints staan onder het /v1 voorvoegsel en worden uitsluitend via HTTPS aangeboden.
https://api.graphorank.com
Genereer een sleutel op de pagina API & MCP in de app. Sleutels beginnen metgr_, worden bij het aanmaken slechts één keer volledig getoond en worden gehasht opgeslagen. Stuur de sleutel mee in de X-Api-Key header bij elk verzoek.
Sleutels hebben scopes: read (altijd toegekend) dekt elk GET-endpoint, terwijl write nodig is om sites aan te maken, scans te starten en schema’s te beheren. De eigen sessie van de app gebruikt een JWT in de Authorization: Bearer header — API-sleutels zijn bedoeld voor programmatische toegang.
# 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"
Een site is een rootdomein in je workspace. Voeg het toe, bewijs dat het van jou is en scan het daarna. Eigendomsverificatie gebruikt een well-known bestand of een metatag — het exacte tokenfragment staat in Aan de slag.
/v1/sitesToon de sites in je 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/sitesVoeg een site toe. Vereist de write-scope. Geeft 201 terug met de nieuwe site — verified begint als 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}Haal één site op. De respons heeft dezelfde vorm als een item uit de lijst van GET /v1/sites.
/v1/sites/{site_id}/verifyVoer de eigendomscontrole uit met de gekozen methode. De respons bevat altijd je sitetoken, zodat je dit endpoint één keer kunt aanroepen om het op te halen voordat je het bestand of de metatag publiceert.
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"
}Een scan doorloopt de volledige pipeline: crawl, semantische analyse, grafiekopbouw, scoring. De status loopt van queued → crawling → embedding → scoring → done (of failed, met een foutcode). Scans tellen mee voor het maandelijkse quotum van je plan.
/v1/sites/{site_id}/scansStart een scan op aanvraag. Vereist de write-scope. Geeft 202 terug met de ingeplande scan; als het maandelijkse quotum op is, krijg je 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}Poll een scan tot de status done is en lees dan de grafiek, score en aanbevelingen.
{
"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"
}De volledige node/edge-grafiek van een voltooide scan, in hetzelfde formaat als de interactieve weergave van de app. Grote grafieken worden aangeboden in cursorpagina’s van 1.000 elementen (eerst nodes, dan edges): blijf aanvragen met de teruggegeven next_cursor tot die null teruggeeft. Het meta-object wordt op elke pagina herhaald.
/v1/scans/{scan_id}/graphNodes bevatten de rol (pillar | cluster | hub | money | orphan | noindex), structurele en semantische cluster-ID’s, PageRank, in-/uitgraad, klikdiepte en indexeerbaarheid. Edges zijn interne links.
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 is een benchmark van 0–100 voor hoe zichtbaar een site is voor generatieve zoekmachines. Het endpoint levert hem samen met de vier gebiedsscores uit de app — structureel, thematisch, GEO en technisch — plus het detailobject dat de uitleg in de app voedt. De methodiek achter het getal is eigen en wordt op elke site identiek toegepast.
/v1/scans/{scan_id}/scoreGraphRank en de vier gebiedsscores van een voltooide scan.
{
"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": { … }
}Geprioriteerde verbeteringen die uit de scan voortkomen, elk met een urgentie (P0 blokkerend, P1 belangrijk, P2 nice-to-have), gelokaliseerde berichten en een meta-object met de betrokken URL plus extra context.
/v1/scans/{scan_id}/recommendationsToon de aanbevelingen van de scan, de ernstigste eerst.
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" }
}
]Volg hoe de score zich over scans ontwikkelt en vergelijk er twee om precies te zien wat er veranderd is — toegevoegde en verwijderde pagina’s, weespagina’s, indexeerbaarheid.
/v1/sites/{site_id}/historyGraphRank-tijdreeks voor de site, één punt per voltooide scan, gesorteerd op tijdstempel.
[
{
"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}/diffVergelijk twee scans van dezelfde site. Zonder parameters vergelijkt het de twee meest recente voltooide scans. score_delta en sub_deltas zijn null als een van beide scans geen score heeft.
{
"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
}Eén terugkerende scan per site, met een e-mailrapport na afloop. Beschikbaar in de plannen Pro en Agency — bij lagere plannen geven deze endpoints 402 quota_exceeded terug met een upgradehint.
/v1/sites/{site_id}/scheduleMaak de planning van de site aan of werk hem bij (upsert — één per site). Vereist de write-scope.
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}/scheduleLees de huidige planning. Geeft 404 not_found terug als er geen is ingesteld.
/v1/sites/{site_id}/scheduleVerwijder de planning. Vereist de write-scope. Geeft 204 No Content terug.
Waar je staat ten opzichte van het quotum van je plan in de huidige factuurperiode. Limieten komen als null terug als ze onbeperkt zijn.
/v1/usagePlan, factuurstatus en quotumverbruik van de workspace.
{
"tier": "pro",
"billing_status": "active",
"scans_used": 4,
"scans_limit": 6,
"pages_limit": 500,
"sites_used": 2,
"sites_limit": 3
}Sleutels op workspaceniveau voor programmatische toegang, met voorvoegsel gr_ en gehasht opgeslagen. De sleutel in platte tekst wordt slechts één keer teruggegeven, in de respons bij het aanmaken — bewaar hem in een secret manager. Scopes: read (altijd inbegrepen) dekt elk GET-endpoint; write is vereist voor alles wat de status wijzigt.
/v1/api-keysToon de sleutels van de workspace. Geheimen worden na het aanmaken nooit meer teruggegeven.
[
{
"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-keysMaak een sleutel aan. Het veld key in de respons is het enige moment waarop het geheim zichtbaar is.
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}Trek een sleutel in. Hij werkt direct niet meer. Geeft 204 No Content terug.
Twee token buckets beschermen de API: één per client-IP (toegepast vóór authenticatie) en één per workspace (toegepast erna). Als je een limiet raakt, is de respons 429 met een Retry-After header die aangeeft hoeveel seconden je moet wachten.
Fouten gebruiken het application/problem+json formaat — { type, title, status, detail, code }. Fouten bij de validatie van verzoeken (422) geven de standaard detail array terug die naar de betreffende velden wijst.
{
"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"
}