Produktionsadresse und erster Aufruf
Melden Sie sich in der App unterhttps://app.sorank.com an. Ihre Schlüssel verwalten Sie unter https://app.sorank.com/settings/api; die REST-Basisadresse lautet https://app.sorank.com/api/public/v1. Sie müssen keinen API-Server erstellen.
- Öffnen Sie Einstellungen → API-Zugriff und erstellen Sie einen Schlüssel mit Namen, mindestens einer Website, Websites anzeigen (
profiles:read) und Ablaufdatum. Wählen Sie zusätzlich Kontingente anzeigen (quotas:read) für den zweiten Aufruf. - Kopieren Sie den vollständigen Schlüssel sofort; er wird nur einmal angezeigt. Der später sichtbare Präfix reicht zur Anmeldung nicht aus.
- Wählen Sie ein Beispiel. Bei cURL geben Sie den Schlüssel auf Nachfrage ein. Für JavaScript oder Go setzen Sie
SORANK_API_KEYin der Umgebung des Serverprozesses. Der HTML-Tab enthält auch einen lokalen Node.js-Server: Starten Sie ihn mit dem Schlüssel in seiner Umgebung und öffnen Siehttp://127.0.0.1:3100. Der Schlüssel gehört niemals in HTML oder Browser-JavaScript. Ergänzen Sie vor einem Einsatz außerhalb dieser lokalen Demo die Anmeldung Ihrer Anwendung.
- cURL
- HTML
- JavaScript
- Go
data. Verwenden Sie eine data[].id als profile_id für weitere Aufrufe. Ist die Liste leer, prüfen Sie die Website-Auswahl und Ihre Zugriffsrechte. Die Beispiele für cURL, JavaScript und Go lesen mit quotas:read auch das Kontingent des ersten Profils.
Die öffentliche API-Referenz in der Entwicklernavigation enthält alle Pfade, erforderlichen Scopes und Antwortformate.
Authentifizieren
Erstellen Sie für Skripte unter Einstellungen → API-Zugriff einen persönlichen API-Schlüssel oder autorisieren Sie einen OAuth-Client mit PKCE S256. Begrenzen Sie Profile und Scopes auf das Nötige. Senden Sie das Token als Bearer-Token. Browser-Cookies und Supabase-Token gelten hier nicht. Für Anwendungen im Namen eines Nutzers beginnen Sie mithttps://app.sorank.com/.well-known/oauth-protected-resource/api/public/v1 und https://app.sorank.com/.well-known/oauth-authorization-server. Ermitteln Sie die angegebenen OAuth-Endpunkte, registrieren Sie bei Bedarf einen öffentlichen Client und verwenden Sie Authorization Code mit PKCE S256, benötigten Scopes und der exakten Ressource https://app.sorank.com/api/public/v1. Ein MCP OAuth-Token gilt nicht für REST.
Berechtigungen und Kontingent
Prüfen Sie vor der GenerierunggetQuotas. Das Beispiel benötigt profiles:read, quotas:read, calendar:read, calendar:write, articles:read, articles:generate und articles:publish. Für das Erstellen eines Kalenders sind auch Generierungs- und Veröffentlichungsrechte nötig. App, REST und MCP teilen sich das Kontingent; weitere Schlüssel erhöhen es nicht.
Die Leseberechtigungen Produkte anzeigen (products:read), Analysen anzeigen (analytics:read), KI-Sichtbarkeit anzeigen (geo:read) und Einstellungen anzeigen (settings:read) verbrauchen nie Kontingent. Einstellungen bearbeiten (settings:write) ändert dieselben Einstellungen wie die App; erteilen Sie sie nur, wenn eine Integration diese ändern soll.
Voraussetzungen prüfen
Die API ist verfügbar, sobald Sie das Onboarding in Sorank abgeschlossen haben und die Website ein gültiges Abonnement hat. Ein Agentur-Mitarbeiter nutzt das Abonnement des Website-Inhabers. Sorank prüft dies beim Erstellen eines Schlüssels oder beim Bestätigen einer OAuth-Verbindung und erneut bei jeder Anfrage.listProfilesliefert nur berechtigte Websites.- Ein nicht abgeschlossenes Onboarding ergibt
403 onboarding_required. - Eine Website ohne gültiges Abonnement ergibt
402 subscription_required, mitdetails.reason(paused,past_due,incompleteoderinactive), sofern bekannt.
Produkte, Analysen, KI-Sichtbarkeit und Einstellungen lesen
Diese Lesezugriffe liefern, was Ihnen die Sorank-App anzeigt. Sie starten nie eine Analyse, Synchronisierung oder Generierung.- Produkte (
products:read):listProductsblättert mit einem Cursor durch den Produktkatalog. Beginnen Sie nach409 product_catalog_cursor_stalewieder mit der ersten Seite. - Analysen (
analytics:read): Leistung, Suchanfragen, Seiten, Länder und Geräte aus der Search Console sowie Google-Analytics-Traffic von KI-Assistenten.startundend(YYYY-MM-DD) sind Pflicht. Jeder Aufruf liest live bei Google und hat ein niedrigeres Ratenlimit. Verbinden Sie Google zuerst in Sorank; sonst erhalten Sie409 gsc_not_connectedoder409 ga_not_connectedund bei verlorenem Zugriff403 google_access_lost. - KI-Sichtbarkeit (
geo:read): GEO-Statistiken, Entwicklung der Erwähnungen, Zeitverlauf der Zitate, zitierende Quellen und die in einer Analyse zitierten Wettbewerber. - Einstellungen (
settings:read):getSettingsliefert die Website, das Business-Briefing mit seinerrevision, Wettbewerber, Artikel-Standards, Bilder und den YouTube-Kanal.
Einstellungen ändern
Mitsettings:write können Sie Firmenname, Markenfarbe und Markt ändern, das Business-Briefing und die Wettbewerberliste ersetzen, die Artikel-Standards des Kalenders, den Bildmodus und die Titelbilder ändern sowie den YouTube-Kanal verbinden, pausieren oder trennen. Die Website-URL lässt sich über die API nicht ändern (400 field_not_writable).
Jede Änderung erfordert einen Idempotency-Key. Die Antwort enthält die resultierenden Einstellungen, einen Beleg und eine Liste effects mit den im Hintergrund gestarteten Vorgängen, wie in der App: geo_questions_regeneration_queued, backlink_refresh_queued, calendar_slots_shifted, image_gallery_analysis_queued, youtube_sync_queued oder youtube_purge_queued.
Senden Sie zum Ersetzen des Business-Briefings die in getSettings gelesene expected_revision. Hat sich das Briefing inzwischen geändert, erhalten Sie 409 business_brief_revision_conflict: Lesen Sie die Einstellungen erneut, bevor Sie es wiederholen.
Einen REST-Ablauf ausprobieren
Dieses erweiterte Beispiel erstellt Inhalte und kann Kontingent verbrauchen. Ersetzen Sie UUIDs, Daten, Idempotenzschlüssel und den Beispielschlüssel. Kalenderdaten richten sich nach der angegebenen IANA-Zeitzone. Prüfen SiegetCapabilities, bevor Sie CMS-Ziel oder Kategorie wählen.
Status und Wiederholungen
Jede Änderung benötigt einen eindeutigenIdempotency-Key. Verwenden Sie denselben Schlüssel, wenn Sie denselben Befehl wiederholen. Lesen Sie data.receipt.operation_id und fragen Sie getOperation ab, bis succeeded, failed oder verification_pending erreicht ist. Ein angenommener Beleg bedeutet nicht, dass die Veröffentlichung abgeschlossen ist. Ein Artikel-Generierungsauftrag liefert 202 mit einem bereits succeeded Beleg; verfolgen Sie jeden in selection.accepted_ids aufgeführten Artikel mit getArticle. Die Berechtigung wird bei jeder Abfrage erneut geprüft, ein Widerruf wirkt sofort.
Fehler behandeln
Jeder Fehler hat in REST und MCP dieselbe Form:{"error": {"code", "message", "request_id", "retryable", "details"}}. Richten Sie Ihre Logik nach code, nicht nach der Meldung. Wiederholen Sie nur, wenn retryable den Wert true hat, und warten Sie Retry-After ab, falls vorhanden.
401 invalid_credential: ungültige, abgelaufene oder widerrufene Zugangsdaten.403 missing_scopeoder403 onboarding_required;402 subscription_requiredoder402 insufficient_quota.404 not_found: Die Ressource fehlt oder ist für diese Zugangsdaten nicht zugänglich.409: ein Konflikt wieidempotency_conflict;429 rate_limited: Warten SieRetry-Afterab.503 auth_state_unavailable: Der Zugriff bleibt verweigert, bis der Autorisierungsstatus wieder verfügbar ist; versuchen Sie es später erneut.
code und request_id, niemals Ihr Token.
Für Assistenten lesen Sie den MCP-Leitfaden.
