La API REST para leer tu grafo, tu puntuación y tus recomendaciones, y para lanzar análisis. Respuestas JSON, autenticadas con claves de API.
Todos los endpoints cuelgan del prefijo /v1 y se sirven únicamente por HTTPS.
https://api.graphorank.com
Genera una clave desde la página API y MCP de la app. Las claves llevan el prefijogr_, se muestran completas una sola vez al crearlas y se almacenan con hash. Envía la clave en la cabecera X-Api-Key en cada petición.
Las claves tienen ámbitos: read (siempre concedido) cubre todos los endpoints GET, mientras que write es necesario para crear sitios, lanzar análisis y gestionar programaciones. La sesión de la propia app usa en cambio un JWT en la cabecera Authorization: Bearer : las claves de API son para el acceso 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"
Un sitio es un dominio raíz de tu espacio de trabajo. Añádelo, demuestra que es tuyo y luego analízalo. La propiedad se comprueba con un archivo well-known o una etiqueta meta; el fragmento exacto con el token está en Primeros pasos.
/v1/sitesLista los sitios de tu espacio de trabajo.
[
{
"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/sitesAñade un sitio. Requiere el ámbito write. Devuelve 201 con el nuevo sitio; verified empieza en 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}Obtiene un único sitio. La respuesta tiene la misma forma que un elemento de la lista de GET /v1/sites.
/v1/sites/{site_id}/verifyEjecuta la comprobación de propiedad con el método elegido. La respuesta siempre incluye el token de tu sitio, así que puedes llamar a este endpoint una vez para obtenerlo antes de publicar el archivo o la etiqueta 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 análisis ejecuta todo el proceso: rastreo, análisis semántico, construcción del grafo y puntuación. Su estado pasa por queued → crawling → embedding → scoring → done (o failed, con un código de error). Los análisis cuentan para la cuota mensual de tu plan.
/v1/sites/{site_id}/scansLanza un análisis bajo demanda. Requiere el ámbito write. Devuelve 202 con el análisis en cola; si se agota la cuota mensual, recibes 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}Consulta un análisis hasta que su estado sea done y luego lee su grafo, su puntuación y sus recomendaciones.
{
"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"
}El grafo completo de nodos y aristas de un análisis completado, en el mismo formato que consume la vista interactiva de la app. Los grafos grandes se sirven en páginas con cursor de 1.000 elementos (primero los nodos y luego las aristas): sigue pidiendo con el next_cursor devuelto hasta que llegue null. El objeto meta se repite en cada página.
/v1/scans/{scan_id}/graphLos nodos incluyen el rol (pillar | cluster | hub | money | orphan | noindex), los identificadores de clúster estructural y semántico, el PageRank, el grado de entrada y salida, la profundidad de clics y la indexabilidad. Las aristas son enlaces internos.
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 es un referente de 0 a 100 de lo visible que es un sitio para los motores generativos. El endpoint lo devuelve junto con las cuatro puntuaciones por área que muestra la app (estructural, temática, GEO y técnica) y el objeto de detalle que alimenta las explicaciones de la app. La metodología que hay detrás del número es propietaria y se aplica igual a todos los sitios.
/v1/scans/{scan_id}/scoreGraphRank y las cuatro puntuaciones por área de un análisis completado.
{
"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": { … }
}Correcciones priorizadas generadas a partir del análisis, cada una con una gravedad (P0 bloqueante, P1 importante, P2 deseable), mensajes localizados y un objeto meta con la URL afectada y contexto adicional.
/v1/scans/{scan_id}/recommendationsLista las recomendaciones del análisis, de más a menos grave.
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" }
}
]Sigue cómo evoluciona la puntuación entre análisis y compara dos de ellos para ver exactamente qué ha cambiado: páginas añadidas y eliminadas, páginas huérfanas, indexabilidad.
/v1/sites/{site_id}/historySerie temporal de GraphRank del sitio, un punto por análisis completado, ordenada por marca de tiempo.
[
{
"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 dos análisis del mismo sitio. Sin parámetros, compara los dos análisis completados más recientes. score_delta y sub_deltas son null cuando alguno de los análisis no tiene puntuación.
{
"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 análisis recurrente por sitio, con informe por correo al terminar. Disponible en los planes Pro y Agency; en los planes inferiores estos endpoints devuelven 402 quota_exceeded con una sugerencia de mejora de plan.
/v1/sites/{site_id}/scheduleCrea o actualiza la programación del sitio (upsert: una por sitio). Requiere el á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}/scheduleLee la programación actual. Devuelve 404 not_found si no hay ninguna configurada.
/v1/sites/{site_id}/scheduleElimina la programación. Requiere el ámbito write. Devuelve 204 No Content.
Cómo vas respecto a la cuota de tu plan en el periodo de facturación actual. Los límites devuelven null cuando son ilimitados.
/v1/usagePlan, estado de facturación y consumo de cuota del espacio de trabajo.
{
"tier": "pro",
"billing_status": "active",
"scans_used": 4,
"scans_limit": 6,
"pages_limit": 500,
"sites_used": 2,
"sites_limit": 3
}Claves a nivel de espacio de trabajo para el acceso programático, con el prefijo gr_ y almacenadas con hash. La clave en texto plano solo se devuelve una vez, en la respuesta de creación: guárdala en un gestor de secretos. Ámbitos: read (siempre incluido) cubre todos los endpoints GET; write es necesario para cualquier operación que modifique el estado.
/v1/api-keysLista las claves del espacio de trabajo. Los secretos nunca se devuelven después de la creación.
[
{
"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-keysCrea una clave. El campo key de la respuesta es la única vez que el secreto es 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}Revoca una clave. Deja de funcionar de inmediato. Devuelve 204 No Content.
Dos token buckets protegen la API: uno por IP de cliente (se aplica antes de la autenticación) y otro por espacio de trabajo (se aplica después). Cuando alcanzas un límite, la respuesta es 429 con una cabecera Retry-After que indica cuántos segundos esperar.
Los errores usan el formato application/problem+json : { type, title, status, detail, code }. Los errores de validación de la petición (422) devuelven el array estándar detail que señala los campos erróneos.
{
"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"
}