Documentación para desarrolladores
API REST
Una URL base, una clave bearer, JSON de entrada y de salida. Puntuaciones, problemas, correcciones, datos de búsqueda y preparación para IA de cada sitio web que cubre tu clave.
URL base y autenticación
https://app.monoranks.com/api/v1
Authorization: Bearer mr_ws_… (or mr_site_…)
Descripción legible por máquinas de cada endpoint y cada evento de webhook: https://app.monoranks.com/api/v1/openapi.json (OpenAPI 3.1). Pégala en Postman, Insomnia, Bruno o un generador de clientes.
Crea una clave de espacio de trabajo en la app, en Settings → Developer access → New key. Cubre todos los sitios web o solo los que marques. Una clave de sitio web (mr_site_…) se crea cuando se conecta el plugin de WordPress, y cubre un solo sitio web. Las claves se muestran una sola vez. Consulta Claves de API y permisos.
Endpoints
Cada endpoint tiene su propia página con parámetros, petición y respuesta, errores y un ejemplo con curl. Todas las rutas empiezan con la URL base.
Las descripciones vienen del documento OpenAPI y están en inglés.
Sitios web y puntuaciones
Auditorías y problemas
Acciones
Páginas
/sites/{siteId}/pages/applyGET/sites/{siteId}/pagesGET/sites/{siteId}/pages/{pageId}GET/sites/{siteId}/pages/findingsGET/sites/{siteId}/pages/{pageId}/historyGET/sites/{siteId}/pages/historyGET/sites/{siteId}/pages/{pageId}/title-comparePOST/sites/{siteId}/pages/{pageId}/title-compareGET/sites/{siteId}/pages/{pageId}/faq-suggestPOST/sites/{siteId}/pages/{pageId}/faq-suggestPOST/sites/{siteId}/pages/{pageId}/faq-suggest/actionGET/sites/{siteId}/pages/{pageId}/claim-checkPOST/sites/{siteId}/pages/{pageId}/claim-checkSearch Console
Google Analytics
Palabras clave
Competidores
Backlinks
Outreach
Visibilidad en IA
Preparación para IA
Públicos, sin clave
Paginación
Las listas llegan por páginas. La tabla muestra cada endpoint que pagina, con qué parámetros y cómo saber si hay más.
| Endpoint | Parámetros | Por defecto / máx. | Devuelve |
|---|---|---|---|
GET/portfolio | page per | page 1 / –per 50 / 200 | total hasMore |
GET/sites/{siteId}/reports | limit | limit 5 / 20 | – |
GET/sites/{siteId}/issues/{issueId} | suggestions_offset suggestions_limit | suggestions_offset 0 / 1,000,000suggestions_limit 100 / 100 | suggestionsNextOffset |
GET/sites/{siteId}/audits | limit | limit 5 / 25 | – |
GET/sites/{siteId}/actions | limit | limit 25 / 100 | – |
GET/sites/{siteId}/pages | page per | page 1 / –per 50 / 200 | total |
GET/sites/{siteId}/pages/{pageId}/history | limit | limit 30 / 100 | more |
GET/sites/{siteId}/pages/history | limit | limit 30 / 100 | more |
GET/sites/{siteId}/search/rows | page limit cursor | limit 1,000 / 10,000 | nextCursor |
GET/sites/{siteId}/topics | limit | limit 50 / 200 | – |
GET/sites/{siteId}/search/near-page-one | page per | page 1 / –per 50 / 500 | total hasMore |
GET/sites/{siteId}/analytics/pages | limit offset cursor | limit 100 / 1,000offset 0 / 1,000,000 | total nextCursor nextOffset |
GET/sites/{siteId}/keywords | page per | page 1 / –per 50 / 200 | total hasMore |
GET/sites/{siteId}/competitors/gaps | page per | page 1 / –per 50 / 200 | total hasMore |
GET/sites/{siteId}/competitors/content-ideas | page per | page 1 / –per 20 / 200 | total hasMore |
GET/sites/{siteId}/backlinks | page per | page 1 / –per 50 / 200 | total hasMore |
GET/sites/{siteId}/outreach | page per | page 1 / –per 50 / 200 | total hasMore |
GET/sites/{siteId}/ai-visibility | limit | limit 50 / 1,000 | – |
GET/sites/{siteId}/agentic | page per | page 1 / 10,000per 50 / 200 | total hasMore |
Errores y límites
Los errores tienen la forma { "error": { "code": "…", "message": "…" } }. El code es estable; el message explica con palabras lo que pasó.
| Estado | Significado |
|---|---|
| 400 | un parámetro o cuerpo incorrecto, por ejemplo un rango de fechas no válido (bad_period, period_too_long), un presupuesto de páginas por encima del plan (over_plan_limit), un filtro que los datos guardados no pueden responder (not_stored) una página que no se puede escribir (not_a_wordpress_post), una petición de historial incorrecta (bad_limit, missing_page) una actualización de outreach incorrecta (nothing_to_change, bad_status, bad_note, note_too_long) o un cambio de competidores incorrecto (bad_action, bad_domain) |
| 401 | falta la clave (missing_key), o es desconocida o está revocada (invalid_key) |
| 403 | falta el permiso (missing_scope), la clave no cubre el sitio web (other_site) o el dueño de la clave perdió el acceso (owner_left) |
| 404 | no existe ese sitio web, problema, página, auditoría, objetivo de outreach o competidor (not_found), o no existe esa ruta (no_route) |
| 409 | algo ya está en cola o en marcha (already_queued, already_running), el sitio web no tiene un conector de WordPress que pueda escribir (wordpress_not_connected, wordpress_not_writable), o Google Analytics no está conectado o niega el acceso (ga4_not_connected, ga4_no_access) |
| 429 | se alcanzó el límite por hora (rate_limited, 1.200 solicitudes por clave y hora), se agotó el presupuesto diario de pruebas de velocidad (budget_used), ya se iniciaron 3 auditorías hoy (too_many_audits), los temas se calcularon demasiadas veces en el último minuto, o la cuota de API de la propiedad GA4 está agotada (ga4_quota) |
| 502 | Google Analytics no respondió (ga4_unavailable) |
| 503 | la API o esta función están desactivadas por ahora (api_disabled, feature_off) |
Ejemplo
curl -H "Authorization: Bearer mr_ws_…" \
"https://app.monoranks.com/api/v1/sites/SITE_ID/actions?limit=5"
{
"waiting": 1,
"actions": [
{ "rank": 1, "issueId": "…", "title": "Missing meta description", "severity": "serious", "effort": "low",
"priority": 8.4, "estimatedScoreGain": 3.2, "status": "open", "ageDays": 16, "waitingWeeks": 2,
"writableField": "seo_description", "link": "https://app.monoranks.com/sites/SITE_ID/actions/…" }
]
}Preguntas frecuentes
¿Hay un SDK?
Todavía no. El documento OpenAPI en /api/v1/openapi.json funciona con los generadores habituales (openapi-generator, Kiota, oazapfts) si quieres clientes con tipos.
¿Puedo escribir datos con la API?
Hay algunas escrituras, cada una con su propio permiso: poner en cola una revisión o volver a ejecutar la prueba de navegación por agentes (issues:recheck), iniciar una auditoría completa (audits:run) y aprobar nuevos títulos SEO, descripciones, canónicas, un archivo llms.txt o reglas para rastreadores de IA que MonoRanks escribe luego mediante el conector de WordPress (actions:apply). Cada escritura aprobada se puede deshacer en la app durante 30 días. El mismo permiso cambia el estado y la nota de un objetivo de outreach y elige, descarta o añade competidores; nada de eso cambia tu sitio web. Todo lo demás es solo lectura.
¿Por qué los ingresos por página dicen ga4_not_connected?
Se leen de la propiedad de Google Analytics (GA4) del propio sitio web. Primero conecta Google Analytics en la pantalla Visitas al sitio del sitio web. La clave también necesita el permiso analytics:read; las claves creadas antes de que existiera ese permiso no lo tienen, así que añádelo con Edit.
¿Y los endpoints públicos?
GET /api/v1/plans y GET /api/v1/changelog no necesitan clave; el sitio web los usa para mostrar precios y notas de versión.