Die REST-API zum Lesen von Graph, Score und Empfehlungen – und zum Starten von Scans. JSON-Antworten, authentifiziert mit API-Keys.
Alle Endpunkte liegen unter dem Präfix /v1 und werden ausschließlich über HTTPS ausgeliefert.
https://api.graphorank.com
Erzeugen Sie einen Key auf der Seite API & MCP der App. Keys tragen das Präfixgr_, werden nur bei der Erstellung einmalig vollständig angezeigt und gehasht gespeichert. Senden Sie den Key mit jeder Anfrage im X-Api-Key Header.
Keys haben Scopes: read (stets enthalten) deckt alle GET-Endpunkte ab, während write zum Anlegen von Websites, Starten von Scans und Verwalten von Zeitplänen nötig ist. Die Sitzung der App selbst nutzt stattdessen ein JWT im Header Authorization: Bearer – API-Keys sind für den programmatischen Zugriff gedacht.
# 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"
Eine Site ist eine Root-Domain in Ihrem Workspace. Fügen Sie sie hinzu, weisen Sie Ihren Besitz nach und scannen Sie sie dann. Der Besitznachweis erfolgt per Well-known-Datei oder Meta-Tag – das genaue Token-Snippet finden Sie unter Erste Schritte.
/v1/sitesListet die Websites in Ihrem Workspace auf.
[
{
"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/sitesFügt eine Website hinzu. Erfordert den Scope write. Liefert 201 mit der neuen Site – verified beginnt mit 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}Ruft eine einzelne Website ab. Die Antwort hat dieselbe Form wie ein Listeneintrag von GET /v1/sites.
/v1/sites/{site_id}/verifyFührt die Besitzprüfung mit der gewählten Methode aus. Die Antwort enthält immer Ihr Site-Token, sodass Sie diesen Endpunkt einmal aufrufen können, um es abzurufen, bevor Sie die Datei oder das Meta-Tag veröffentlichen.
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"
}Ein Scan durchläuft die gesamte Pipeline: Crawl, semantische Analyse, Graph-Aufbau, Scoring. Sein Status wechselt von queued → crawling → embedding → scoring → done (oder failed, mit einem Fehlercode). Scans zählen auf das monatliche Kontingent Ihres Tarifs.
/v1/sites/{site_id}/scansStartet einen On-Demand-Scan. Erfordert den Scope write. Liefert 202 mit dem eingereihten Scan; ist das monatliche Kontingent erschöpft, erhalten Sie 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}Fragt einen Scan ab, bis der Status done lautet; danach lassen sich Graph, Score und Empfehlungen lesen.
{
"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"
}Der vollständige Knoten-Kanten-Graph eines abgeschlossenen Scans, im selben Format, das die interaktive Ansicht der App verwendet. Große Graphen werden in Cursor-Seiten zu je 1.000 Elementen ausgeliefert (zuerst Knoten, dann Kanten): Fragen Sie weiter mit dem zurückgegebenen next_cursor ab, bis er null zurückgibt. Das meta-Objekt wird auf jeder Seite wiederholt.
/v1/scans/{scan_id}/graphKnoten enthalten die Rolle (pillar | cluster | hub | money | orphan | noindex), strukturelle und semantische Cluster-IDs, PageRank, Ein-/Ausgangsgrad, Klicktiefe und Indexierbarkeit. Kanten sind 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 ist ein Benchmark von 0 bis 100 dafür, wie sichtbar eine Website für generative Suchmaschinen ist. Der Endpunkt liefert ihn zusammen mit den vier Bereichs-Scores aus der App – Struktur, Thematik, GEO und Technik – sowie dem Detail-Objekt, das die Erklärungen in der App speist. Die Methodik hinter der Zahl ist proprietär und wird bei jeder Website identisch angewendet.
/v1/scans/{scan_id}/scoreGraphRank und die vier Bereichs-Scores für einen abgeschlossenen 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": { … }
}Priorisierte Maßnahmen, aus dem Scan erzeugt, jeweils mit einem Schweregrad (P0 blockierend, P1 wichtig, P2 wünschenswert), lokalisierten Meldungen und einem meta-Objekt mit der betroffenen URL sowie zusätzlichem Kontext.
/v1/scans/{scan_id}/recommendationsListet die Empfehlungen des Scans auf, die schwerwiegendsten zuerst.
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" }
}
]Verfolgen Sie, wie sich der Score über mehrere Scans entwickelt, und vergleichen Sie zwei davon, um genau zu sehen, was sich geändert hat – hinzugekommene und entfernte Seiten, verwaiste Seiten, Indexierbarkeit.
/v1/sites/{site_id}/historyGraphRank-Zeitreihe für die Website, ein Punkt pro abgeschlossenem Scan, nach Zeitstempel sortiert.
[
{
"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}/diffVergleicht zwei Scans derselben Website. Ohne Parameter werden die beiden jüngsten abgeschlossenen Scans verglichen. score_delta und sub_deltas sind null, wenn einer der Scans keinen Score hat.
{
"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
}Ein wiederkehrender Scan pro Website, mit E-Mail-Report nach Abschluss. Verfügbar in den Tarifen Pro und Agency – in niedrigeren Tarifen liefern diese Endpunkte 402 quota_exceeded mit einem Upgrade-Hinweis.
/v1/sites/{site_id}/scheduleLegt den Zeitplan der Website an oder aktualisiert ihn (Upsert – einer pro Website). Erfordert den 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}/scheduleLiest den aktuellen Zeitplan. Liefert 404 not_found, wenn keiner konfiguriert ist.
/v1/sites/{site_id}/scheduleEntfernt den Zeitplan. Erfordert den Scope write. Liefert 204 No Content.
Wo Sie im aktuellen Abrechnungszeitraum gegenüber dem Kontingent Ihres Tarifs stehen. Limits werden als null zurückgegeben, wenn sie unbegrenzt sind.
/v1/usageTarif, Abrechnungsstatus und Kontingentverbrauch des Workspace.
{
"tier": "pro",
"billing_status": "active",
"scans_used": 4,
"scans_limit": 6,
"pages_limit": 500,
"sites_used": 2,
"sites_limit": 3
}Keys auf Workspace-Ebene für den programmatischen Zugriff, mit dem Präfix gr_ und gehasht gespeichert. Der Klartext-Key wird nur einmal zurückgegeben, in der Antwort auf die Erstellung – bewahren Sie ihn in einem Secret Manager auf. Scopes: read (immer enthalten) deckt alle GET-Endpunkte ab; write ist für alles erforderlich, was den Zustand verändert.
/v1/api-keysListet die Keys des Workspace auf. Secrets werden nach der Erstellung nie zurückgegeben.
[
{
"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-keysErstellt einen Key. Das Feld key in der Antwort ist die einzige Gelegenheit, bei der das Secret sichtbar ist.
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}Widerruft einen Key. Er funktioniert sofort nicht mehr. Liefert 204 No Content.
Zwei Token-Buckets schützen die API: einer pro Client-IP (vor der Authentifizierung) und einer pro Workspace (danach). Wenn Sie ein Limit erreichen, lautet die Antwort 429 mit einem Retry-After Header, der angibt, wie viele Sekunden Sie warten sollen.
Fehler werden im Format application/problem+json mit den Feldern { type, title, status, detail, code } zurückgegeben. Validierungsfehler (422) liefern das Standard-Array detail zurück, das auf die fehlerhaften Felder verweist.
{
"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"
}