REST API do odczytu grafu, wyniku i rekomendacji — oraz do uruchamiania skanów. Odpowiedzi w JSON, uwierzytelnianie kluczami API.
Wszystkie endpointy znajdują się pod prefiksem /v1 i są udostępniane wyłącznie przez HTTPS.
https://api.graphorank.com
Klucz można wygenerować w aplikacji, na stronie API i MCP — klucze mają prefiksgr_, są pokazywane w całości tylko raz, przy tworzeniu, i przechowywane w postaci skrótu. Klucz należy przesyłać w nagłówku X-Api-Key z każdym żądaniem.
Klucze mają zakresy: read (zawsze przyznawany) obejmuje wszystkie endpointy GET, natomiast write jest wymagany do tworzenia witryn, uruchamiania skanów i zarządzania harmonogramami. Sesja samej aplikacji używa zamiast tego tokenu JWT w nagłówku Authorization: Bearer — klucze API służą do dostępu programistycznego.
# 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"
Witryna to domena główna w przestrzeni roboczej. Dodaj ją, potwierdź własność, a następnie przeskanuj. Własność potwierdza się plikiem well-known lub tagiem meta — dokładny fragment z tokenem znajduje się w Pierwsze kroki.
/v1/sitesWyświetla witryny w przestrzeni roboczej.
[
{
"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/sitesDodaje witrynę. Wymaga zakresu write. Zwraca 201 z nową witryną — pole verified ma początkowo wartość 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}Pobiera pojedynczą witrynę. Odpowiedź ma ten sam kształt co element listy z GET /v1/sites.
/v1/sites/{site_id}/verifyUruchamia sprawdzenie własności wybraną metodą. Odpowiedź zawsze zawiera token witryny, więc można wywołać ten endpoint jednokrotnie, aby go pobrać przed opublikowaniem pliku lub tagu 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"
}Skan uruchamia pełny potok: przeszukiwanie, analizę semantyczną, budowę grafu i ocenę. Jego status przechodzi przez queued → crawling → embedding → scoring → done (lub failed, z kodem błędu). Skany wliczają się w miesięczny limit planu.
/v1/sites/{site_id}/scansUruchamia skan na żądanie. Wymaga zakresu write. Zwraca 202 ze skanem w kolejce; po wyczerpaniu miesięcznego limitu zwracane jest 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}Odpytuj skan, aż status przyjmie wartość done, a następnie odczytaj jego graf, wynik i rekomendacje.
{
"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"
}Kompletny graf węzłów i krawędzi ukończonego skanu, w tym samym formacie, którego używa interaktywny widok aplikacji. Duże grafy są udostępniane w stronach kursora po 1000 elementów (najpierw węzły, potem krawędzie): wysyłaj kolejne żądania ze zwróconym next_cursor, aż wróci null. Obiekt meta powtarza się na każdej stronie.
/v1/scans/{scan_id}/graphWęzły zawierają rolę (pillar | cluster | hub | money | orphan | noindex), identyfikatory klastrów strukturalnych i semantycznych, PageRank, stopień wejściowy/wyjściowy, głębokość kliknięć i indeksowalność. Krawędzie to linki wewnętrzne.
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 to wzorzec 0–100 określający, jak widoczna jest witryna dla silników generatywnych. Endpoint zwraca go razem z czterema wynikami obszarowymi pokazywanymi w aplikacji — strukturalnym, tematycznym, GEO i technicznym — oraz obiektem szczegółów, który zasila wyjaśnienia w aplikacji. Metodologia stojąca za liczbą jest zastrzeżona i stosowana identycznie wobec każdej witryny.
/v1/scans/{scan_id}/scoreGraphRank i cztery wyniki obszarowe dla ukończonego skanu.
{
"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": { … }
}Poprawki według priorytetu, wygenerowane na podstawie skanu, każda z poziomem ważności (P0 blokująca, P1 istotna, P2 pożądana), zlokalizowanymi komunikatami i obiektem meta z adresem URL, którego dotyczy, oraz dodatkowym kontekstem.
/v1/scans/{scan_id}/recommendationsWyświetla rekomendacje skanu, od najpoważniejszych.
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" }
}
]Śledź, jak wynik zmienia się między skanami, i porównaj dwa z nich, by zobaczyć dokładnie, co się zmieniło — strony dodane i usunięte, strony osierocone, indeksowalność.
/v1/sites/{site_id}/historySzereg czasowy GraphRank dla witryny, jeden punkt na każdy ukończony skan, uporządkowany według znacznika czasu.
[
{
"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}/diffPorównuje dwa skany tej samej witryny. Bez parametrów porównuje dwa ostatnie ukończone skany. score_delta i sub_deltas mają wartość null, gdy któryś skan nie ma wyniku.
{
"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
}Jeden cykliczny skan na witrynę, z raportem e-mail po zakończeniu. Dostępne w planach Pro i Agency — w niższych planach te endpointy zwracają 402 quota_exceeded z podpowiedzią o przejściu na wyższy plan.
/v1/sites/{site_id}/scheduleTworzy lub aktualizuje harmonogram witryny (upsert — jeden na witrynę). Wymaga zakresu 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}/scheduleOdczytuje bieżący harmonogram. Zwraca 404 not_found, gdy żaden nie jest skonfigurowany.
/v1/sites/{site_id}/scheduleUsuwa harmonogram. Wymaga zakresu write. Zwraca 204 No Content.
Jak wygląda zużycie względem limitu planu w bieżącym okresie rozliczeniowym. Limity mają wartość null, gdy są nieograniczone.
/v1/usagePlan, status rozliczeń i zużycie limitów przestrzeni roboczej.
{
"tier": "pro",
"billing_status": "active",
"scans_used": 4,
"scans_limit": 6,
"pages_limit": 500,
"sites_used": 2,
"sites_limit": 3
}Klucze na poziomie przestrzeni roboczej do dostępu programistycznego, z prefiksem gr_ i przechowywane w postaci skrótu. Klucz w postaci jawnej jest zwracany tylko raz, w odpowiedzi na utworzenie — zapisz go w menedżerze sekretów. Zakresy: read (zawsze dołączany) obejmuje wszystkie endpointy GET; write jest wymagany do wszystkiego, co zmienia stan.
/v1/api-keysWyświetla klucze przestrzeni roboczej. Sekrety nigdy nie są zwracane po utworzeniu.
[
{
"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-keysTworzy klucz. Pole key w odpowiedzi to jedyny moment, w którym sekret jest widoczny.
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}Unieważnia klucz. Przestaje działać natychmiast. Zwraca 204 No Content.
API chronią dwa limity typu token bucket: jeden na adres IP klienta (stosowany przed uwierzytelnieniem) i jeden na przestrzeń roboczą (stosowany po nim). Po osiągnięciu limitu odpowiedzią jest 429 z nagłówkiem Retry-After informującym, ile sekund należy odczekać.
Błędy mają format application/problem+json — { type, title, status, detail, code }. Błędy walidacji żądania (422) zwracają standardową tablicę detail wskazującą błędne pola.
{
"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"
}