Zum Hauptinhalt springen

Produktionsadresse und erster Aufruf

Melden Sie sich in der App unter https://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.
  1. Ö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.
  2. Kopieren Sie den vollständigen Schlüssel sofort; er wird nur einmal angezeigt. Der später sichtbare Präfix reicht zur Anmeldung nicht aus.
  3. Wählen Sie ein Beispiel. Bei cURL geben Sie den Schlüssel auf Nachfrage ein. Für JavaScript oder Go setzen Sie SORANK_API_KEY in 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 Sie http://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.
Die Antwort enthält die freigegebenen Websites unter 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 mit https://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 Generierung getQuotas. 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.
  • listProfiles liefert nur berechtigte Websites.
  • Ein nicht abgeschlossenes Onboarding ergibt 403 onboarding_required.
  • Eine Website ohne gültiges Abonnement ergibt 402 subscription_required, mit details.reason (paused, past_due, incomplete oder inactive), sofern bekannt.
Schließen Sie das Onboarding ab oder aktualisieren Sie das Abonnement unter Einstellungen → Abrechnung. Ihr bestehender Schlüssel funktioniert ab der nächsten Anfrage wieder.

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): listProducts blättert mit einem Cursor durch den Produktkatalog. Beginnen Sie nach 409 product_catalog_cursor_stale wieder 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. start und end (YYYY-MM-DD) sind Pflicht. Jeder Aufruf liest live bei Google und hat ein niedrigeres Ratenlimit. Verbinden Sie Google zuerst in Sorank; sonst erhalten Sie 409 gsc_not_connected oder 409 ga_not_connected und bei verlorenem Zugriff 403 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): getSettings liefert die Website, das Business-Briefing mit seiner revision, Wettbewerber, Artikel-Standards, Bilder und den YouTube-Kanal.

Einstellungen ändern

Mit settings: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 Sie getCapabilities, bevor Sie CMS-Ziel oder Kategorie wählen.
Die separate API-Referenz enthält alle Operationen, Felder, Antworten und Fehler.

Status und Wiederholungen

Jede Änderung benötigt einen eindeutigen Idempotency-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_scope oder 403 onboarding_required; 402 subscription_required oder 402 insufficient_quota.
  • 404 not_found: Die Ressource fehlt oder ist für diese Zugangsdaten nicht zugänglich.
  • 409: ein Konflikt wie idempotency_conflict; 429 rate_limited: Warten Sie Retry-After ab.
  • 503 auth_state_unavailable: Der Zugriff bleibt verweigert, bis der Autorisierungsstatus wieder verfügbar ist; versuchen Sie es später erneut.
Die Referenz der öffentlichen API listet die Codes jeder Operation. Geben Sie dem Support code und request_id, niemals Ihr Token. Für Assistenten lesen Sie den MCP-Leitfaden.