Developer docs

REST API

One base URL, one bearer key, JSON in and out. Scores, issues, fixes, search data and AI readiness for every website your key covers.

Base URL and authentication

https://app.monoranks.com/api/v1
Authorization: Bearer mr_ws_… (or mr_site_…)

Machine-readable description of every endpoint and webhook event: https://app.monoranks.com/api/v1/openapi.json (OpenAPI 3.1). Paste it into Postman, Insomnia, Bruno or a client generator.

Make a workspace key in the app under Settings → Developer access → New key. It covers every website, or only the ones you tick. A website key (mr_site_…) is made when the WordPress plugin connects, and covers one website. Keys are shown once. See API keys and scopes.

Endpoints

Every endpoint has its own page with parameters, the request and response, errors and a curl example. All paths start with the base URL.

Websites and scores

Audits and issues

Actions

Pages

Google Analytics

Keywords

Competitors

Outreach

AI visibility

AI readiness

Public, no key

Paging

Lists come one page at a time. This table lists every endpoint that pages, what it pages with, and what tells you there is more.

EndpointParametersDefault / maxReturns
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

Errors and limits

Errors are { "error": { "code": "…", "message": "…" } }. The code is stable; the message says what happened in words.

Status Meaning
400 a bad parameter or body, for example a bad date range (bad_period, period_too_long), a page budget above the plan (over_plan_limit), a filter the stored data cannot answer (not_stored), a page that cannot be written (not_a_wordpress_post), a bad history request (bad_limit, missing_page) a bad outreach update (nothing_to_change, bad_status, bad_note, note_too_long) or a bad competitor change (bad_action, bad_domain)
401 key missing (missing_key), unknown or revoked (invalid_key)
403 scope missing (missing_scope), website not covered by the key (other_site), or the key’s owner lost access (owner_left)
404 no such website, issue, page, audit, outreach target or competitor (not_found), or no such route (no_route)
409 something is already queued or running (already_queued, already_running), the website has no WordPress connector that can write (wordpress_not_connected, wordpress_not_writable), or Google Analytics is not connected or refuses access (ga4_not_connected, ga4_no_access)
429 hourly limit reached (rate_limited, 1,200 requests per key per hour), the daily speed test budget is used up (budget_used), 3 audits were already started today (too_many_audits), topics were computed too often in the last minute, or the GA4 property’s API quota is used up (ga4_quota)
502 Google Analytics did not answer (ga4_unavailable)
503 the API or this feature is switched off for now (api_disabled, feature_off)

Example

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/…" }
  ]
}

Common questions

Is there an SDK?

Not yet. The OpenAPI document at /api/v1/openapi.json works with the usual generators (openapi-generator, Kiota, oazapfts) if you want typed clients.

Can I write data through the API?

A few writes exist, each behind its own scope: queue a recheck or re-run the Agentic browsing check (issues:recheck), start a full audit (audits:run), and approve new SEO titles, descriptions, canonicals, an llms.txt file or AI crawler rules that MonoRanks then writes through the WordPress connector (actions:apply). Every approved write can be undone in the app for 30 days. The same scope sets the status and note of an outreach target and picks, dismisses or adds competitors; neither changes anything on your website. Everything else is read-only.

Why does revenue per page say ga4_not_connected?

It reads the website's own Google Analytics (GA4) property. Connect Google Analytics on the website's Website visits screen first. The key also needs the analytics:read scope; keys made before that scope existed do not have it, so add it with Edit.

What about the public endpoints?

GET /api/v1/plans and GET /api/v1/changelog need no key; the website uses them to show prices and release notes.