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

Google Analytics

Palabras clave

Competidores

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.

EndpointParámetrosPor defecto / máx.Devuelve
GET/portfoliopage perpage 1 / –
per 50 / 200
total hasMore
GET/sites/{siteId}/reportslimitlimit 5 / 20–
GET/sites/{siteId}/issues/{issueId}suggestions_offset suggestions_limitsuggestions_offset 0 / 1,000,000
suggestions_limit 100 / 100
suggestionsNextOffset
GET/sites/{siteId}/auditslimitlimit 5 / 25–
GET/sites/{siteId}/actionslimitlimit 25 / 100–
GET/sites/{siteId}/pagespage perpage 1 / –
per 50 / 200
total
GET/sites/{siteId}/pages/{pageId}/historylimitlimit 30 / 100more
GET/sites/{siteId}/pages/historylimitlimit 30 / 100more
GET/sites/{siteId}/search/rowspage limit cursorlimit 1,000 / 10,000nextCursor
GET/sites/{siteId}/topicslimitlimit 50 / 200–
GET/sites/{siteId}/search/near-page-onepage perpage 1 / –
per 50 / 500
total hasMore
GET/sites/{siteId}/analytics/pageslimit offset cursorlimit 100 / 1,000
offset 0 / 1,000,000
total nextCursor nextOffset
GET/sites/{siteId}/keywordspage perpage 1 / –
per 50 / 200
total hasMore
GET/sites/{siteId}/competitors/gapspage perpage 1 / –
per 50 / 200
total hasMore
GET/sites/{siteId}/competitors/content-ideaspage perpage 1 / –
per 20 / 200
total hasMore
GET/sites/{siteId}/backlinkspage perpage 1 / –
per 50 / 200
total hasMore
GET/sites/{siteId}/outreachpage perpage 1 / –
per 50 / 200
total hasMore
GET/sites/{siteId}/ai-visibilitylimitlimit 50 / 1,000–
GET/sites/{siteId}/agenticpage perpage 1 / 10,000
per 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.