Entwicklerdokumentation

REST-API

Eine Basis-URL, ein Bearer-Schlüssel, JSON rein und raus. Werte, Probleme, Korrekturen, Suchdaten und KI-Bereitschaft für jede Website, die Ihr Schlüssel abdeckt.

Basis-URL und Anmeldung

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

Maschinenlesbare Beschreibung jedes Endpunkts und jedes Webhook-Ereignisses: https://app.monoranks.com/api/v1/openapi.json (OpenAPI 3.1). Fügen Sie sie in Postman, Insomnia, Bruno oder einen Client-Generator ein.

Einen Workspace-Schlüssel erstellen Sie in der App unter Settings → Developer access → New key. Er gilt für alle Websites oder nur für die, die Sie anhaken. Ein Website-Schlüssel (mr_site_…) entsteht, wenn sich das WordPress-Plugin verbindet, und gilt für eine Website. Schlüssel werden nur einmal angezeigt. Siehe API-Schlüssel und Berechtigungen.

Endpunkte

Jeder Endpunkt hat eine eigene Seite mit Parametern, Anfrage und Antwort, Fehlern und einem curl-Beispiel. Alle Pfade beginnen mit der Basis-URL.

Die Beschreibungen kommen aus dem OpenAPI-Dokument und sind auf Englisch.

Websites und Werte

Audits und Probleme

Aktionen

Seiten

Google Analytics

Keywords

Wettbewerber

Outreach

KI-Sichtbarkeit

KI-Bereitschaft

Öffentlich, ohne Schlüssel

Blättern

Listen kommen seitenweise. Die Tabelle zeigt jeden Endpunkt, der blättert, womit er blättert und woran Sie sehen, dass mehr kommt.

EndpunktParameterStandard / max.Liefert
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

Fehler und Grenzen

Fehler sehen so aus: { "error": { "code": "…", "message": "…" } }. Der code bleibt stabil; die message sagt in Worten, was passiert ist.

Status Bedeutung
400 ein falscher Parameter oder Inhalt, zum Beispiel ein falscher Zeitraum (bad_period, period_too_long), ein Seitenbudget über dem Tarif (over_plan_limit), ein Filter, den die gespeicherten Daten nicht beantworten können (not_stored), eine Seite, die nicht geschrieben werden kann (not_a_wordpress_post), eine falsche Verlaufsanfrage (bad_limit, missing_page) eine falsche Outreach-Änderung (nothing_to_change, bad_status, bad_note, note_too_long) oder eine falsche Änderung an den Wettbewerbern (bad_action, bad_domain)
401 Schlüssel fehlt (missing_key), ist unbekannt oder widerrufen (invalid_key)
403 Scope fehlt (missing_scope), die Website gehört nicht zum Schlüssel (other_site), oder die Person hinter dem Schlüssel hat keinen Zugriff mehr (owner_left)
404 keine solche Website, kein solches Problem, keine solche Seite, kein solches Audit, kein solches Outreach-Ziel, kein solcher Wettbewerber (not_found) oder kein solcher Pfad (no_route)
409 etwas ist schon geplant oder läuft (already_queued, already_running), die Website hat keinen WordPress-Connector, der schreiben kann (wordpress_not_connected, wordpress_not_writable), oder Google Analytics ist nicht verbunden oder verweigert den Zugriff (ga4_not_connected, ga4_no_access)
429 Stundengrenze erreicht (rate_limited, 1.200 Anfragen pro Schlüssel und Stunde), das tägliche Budget für Geschwindigkeitstests ist aufgebraucht (budget_used), heute wurden schon 3 Audits gestartet (too_many_audits), Themen wurden in der letzten Minute zu oft berechnet, oder das API-Kontingent der GA4-Property ist aufgebraucht (ga4_quota)
502 Google Analytics hat nicht geantwortet (ga4_unavailable)
503 die API oder diese Funktion ist gerade abgeschaltet (api_disabled, feature_off)

Beispiel

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

Häufige Fragen

Gibt es ein SDK?

Noch nicht. Das OpenAPI-Dokument unter /api/v1/openapi.json funktioniert mit den üblichen Generatoren (openapi-generator, Kiota, oazapfts), wenn Sie typisierte Clients möchten.

Kann ich über die API Daten schreiben?

Es gibt einige Schreibvorgänge, jeder mit eigenem Scope: eine erneute Prüfung starten oder die Agentic-Browsing-Prüfung neu ausführen (issues:recheck), ein vollständiges Audit starten (audits:run) und neue SEO-Titel, Beschreibungen, Canonicals, eine llms.txt-Datei oder Regeln für KI-Crawler genehmigen, die MonoRanks dann über den WordPress-Connector schreibt (actions:apply). Jeder genehmigte Schreibvorgang lässt sich in der App 30 Tage lang rückgängig machen. Derselbe Scope setzt Status und Notiz eines Outreach-Ziels und wählt Wettbewerber aus, blendet sie aus oder fügt sie hinzu; beides ändert nichts an Ihrer Website. Alles andere ist nur lesend.

Warum meldet Umsatz pro Seite ga4_not_connected?

Der Endpunkt liest die eigene Google-Analytics-Property (GA4) der Website. Verbinden Sie zuerst Google Analytics auf dem Bildschirm „Website-Besuche“ der Website. Der Schlüssel braucht außerdem den Scope analytics:read; Schlüssel, die vor diesem Scope erstellt wurden, haben ihn nicht, also fügen Sie ihn mit Edit hinzu.

Was ist mit den öffentlichen Endpunkten?

GET /api/v1/plans und GET /api/v1/changelog brauchen keinen Schlüssel. Die Website nutzt sie, um Preise und Versionshinweise zu zeigen.