A API REST para ler o seu grafo, a pontuação e as recomendações — e para iniciar análises. Respostas em JSON, autenticadas com chaves de API.
Todos os endpoints estão sob o prefixo /v1 e são servidos apenas por HTTPS.
https://api.graphorank.com
Gere uma chave na página API e MCP da aplicação. As chaves têm o prefixogr_, são mostradas por inteiro apenas uma vez, na criação, e guardadas com hash. Envie a chave no cabeçalho X-Api-Key em cada pedido.
As chaves têm âmbitos: read (sempre concedido) cobre todos os endpoints GET, enquanto write é necessário para criar sites, iniciar análises e gerir agendamentos. A própria sessão da aplicação usa antes um JWT no cabeçalho Authorization: Bearer — as chaves de API destinam-se ao acesso programático.
# 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"
Um site é um domínio raiz no seu espaço de trabalho. Adicione-o, comprove que é seu e depois analise-o. A titularidade usa um ficheiro well-known ou uma meta tag — o excerto exato com o token está em Primeiros passos.
/v1/sitesLista os sites do seu espaço de trabalho.
[
{
"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/sitesAdiciona um site. Requer o âmbito write. Devolve 201 com o novo site — verified começa como 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}Obtém um único site. A resposta tem a mesma forma de um item da lista de GET /v1/sites.
/v1/sites/{site_id}/verifyExecuta a verificação de titularidade com o método escolhido. A resposta inclui sempre o token do site, pelo que pode chamar este endpoint uma vez para o obter antes de publicar o ficheiro ou a 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"
}Uma análise executa o processo completo: rastreio, análise semântica, construção do grafo, pontuação. O estado avança por queued → crawling → embedding → scoring → done (ou failed, com um código de erro). As análises contam para a quota mensal do seu plano.
/v1/sites/{site_id}/scansInicia uma análise a pedido. Requer o âmbito write. Devolve 202 com a análise em fila; quando a quota mensal se esgota, recebe 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}Consulte uma análise até o estado ser done e depois leia o respetivo grafo, pontuação e recomendações.
{
"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"
}O grafo completo de nós e arestas de uma análise concluída, no mesmo formato que a vista interativa da aplicação consome. Os grafos grandes são servidos em páginas por cursor de 1000 elementos (primeiro os nós, depois as arestas): continue a pedir com o next_cursor devolvido até vir null. O objeto meta repete-se em cada página.
/v1/scans/{scan_id}/graphOs nós trazem a função (pillar | cluster | hub | money | orphan | noindex), os identificadores dos grupos estruturais e semânticos, PageRank, grau de entrada/saída, profundidade de cliques e indexabilidade. As arestas são ligações internas.
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
}O GraphRank é uma referência de 0 a 100 da visibilidade de um site para os motores generativos. O endpoint devolve-o juntamente com as quatro pontuações por área mostradas na aplicação — estrutural, temática, GEO e técnica — e o objeto de detalhe que alimenta as explicações na aplicação. A metodologia por trás do número é proprietária e aplicada de forma idêntica a todos os sites.
/v1/scans/{scan_id}/scoreGraphRank e as quatro pontuações por área de uma análise concluída.
{
"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": { … }
}Correções priorizadas geradas a partir da análise, cada uma com uma gravidade (P0 bloqueante, P1 importante, P2 desejável), mensagens localizadas e um objeto meta com o URL afetado e contexto adicional.
/v1/scans/{scan_id}/recommendationsLista as recomendações da análise, das mais graves para as menos graves.
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" }
}
]Acompanhe a evolução da pontuação ao longo das análises e compare duas delas para ver exatamente o que mudou — páginas adicionadas e removidas, órfãs, indexabilidade.
/v1/sites/{site_id}/historySérie temporal do GraphRank do site, um ponto por análise concluída, ordenada por data e hora.
[
{
"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}/diffCompara duas análises do mesmo site. Sem parâmetros, compara as duas análises concluídas mais recentes. score_delta e sub_deltas são null quando alguma das análises não tem pontuação.
{
"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
}Uma análise recorrente por site, com relatório por e-mail no final. Disponível nos planos Pro e Agency — nos planos inferiores, estes endpoints devolvem 402 quota_exceeded com uma sugestão de mudança de plano.
/v1/sites/{site_id}/scheduleCria ou atualiza o agendamento do site (upsert — um por site). Requer o âmbito 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}/scheduleLê o agendamento atual. Devolve 404 not_found quando não há nenhum configurado.
/v1/sites/{site_id}/scheduleRemove o agendamento. Requer o âmbito write. Devolve 204 No Content.
Onde se encontra face à quota do seu plano no período de faturação atual. Os limites vêm null quando são ilimitados.
/v1/usagePlano, estado de faturação e consumo da quota do espaço de trabalho.
{
"tier": "pro",
"billing_status": "active",
"scans_used": 4,
"scans_limit": 6,
"pages_limit": 500,
"sites_used": 2,
"sites_limit": 3
}Chaves ao nível do espaço de trabalho para acesso programático, com o prefixo gr_ e guardadas com hash. A chave em texto simples é devolvida apenas uma vez, na resposta de criação — guarde-a num gestor de segredos. Âmbitos: read (sempre incluído) cobre todos os endpoints GET; write é necessário para tudo o que altera estado.
/v1/api-keysLista as chaves do espaço de trabalho. Os segredos nunca são devolvidos depois da criação.
[
{
"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-keysCria uma chave. O campo key da resposta é a única vez em que o segredo fica visível.
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}Revoga uma chave. Deixa de funcionar de imediato. Devolve 204 No Content.
Dois token buckets protegem a API: um por IP de cliente (aplicado antes da autenticação) e outro por espaço de trabalho (aplicado depois). Ao atingir um limite, a resposta é 429 com um cabeçalho Retry-After que indica quantos segundos deve esperar.
Os erros usam o formato application/problem+json — { type, title, status, detail, code }. Os erros de validação do pedido (422) devolvem a matriz padrão detail a apontar para os campos em causa.
{
"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"
}