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
/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
Keywords
Competitors
Backlinks
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.
| Endpoint | Parameters | Default / max | Returns |
|---|---|---|---|
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 |
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.