REST API v1: API-Schlüssel, Authentifizierung und Endpunkte

Die REST API v1 ermöglicht es Ihnen, den Großteil der Aktionen aus dem Panel per Code auszuführen: Websites auflisten, Crawls starten, Probleme abrufen, KI-Fixes öffnen und Pixel-Regeln, Keywords, Inhalte, Backlinks, Outreach, Mitbewerber sowie Social-Media-Beiträge verwalten. Schlüssel gehören zu einer Organisation; ein Schlüssel sieht nur die Daten seiner eigenen Organisation. Der MCP-Server ruft dieselben Endpunkte auf.

#Voraussetzungen

• Nur der Inhaber oder ein Admin der Organisation kann Schlüssel erstellen und widerrufen. Andere Rollen sehen den Reiter API-Schlüssel nicht.
• Der API-Zugriff ist in den Plänen Pro und Agency enthalten. Falls Ihr Plan diesen nicht beinhaltet, zeigt der Reiter einen Hinweis mit dem Link Pläne ansehen; Sie können eventuell weiterhin einen Schlüssel erstellen, Anfragen geben jedoch 403 plan_required zurück.

#API-Schlüssel erstellen

1. Öffnen Sie Einstellungen → Profil → API-Schlüssel.
2. Beschreiben Sie unter Schlüsselname, wofür der Schlüssel verwendet wird (mindestens 2 Zeichen, z. B. "CI").
3. Falls der Schlüssel Crawls starten oder Fixes, Regeln, Keywords oder Inhalte erstellen muss, aktivieren Sie Schreib-Berechtigung (write scope). Lassen Sie die Option deaktiviert für einen Schlüssel mit reinem Lesezugriff.
4. Klicken Sie auf Schlüssel erstellen.
5. Kopieren Sie den Schlüssel, der mit sa_live_ beginnt, sofort über Schlüssel kopieren. Er wird nie wieder angezeigt; die Liste speichert nur seinen Präfix.

Verbindungen, die KI-Apps über OAuth einrichten, erscheinen nicht in dieser Liste; sie befinden sich in der Liste Verbundene Assistenten auf der Seite KI-Assistenten verbinden.

#Authentifizierung und Basis-URL

• Basis-URL: https://seoasist.com/api/v1
• Header: Authorization: Bearer sa_live_…
• Ein ?api_key=sa_live_… Query-Parameter wird ebenfalls akzeptiert. Da Schlüssel in URLs leicht in Logdateien landen, sollten Sie dies nur zu Testzwecken nutzen.

Berechtigungen (Scopes): Ein read-Schlüssel kann jeden GET-Endpunkt aufrufen. Die write-Berechtigung schaltet POST-, PATCH- und DELETE-Anfragen frei. Eine Schreibanfrage mit einem Nur-Lese-Schlüssel gibt 403 zurück.

Limits: Maximal 240 Anfragen pro Minute pro Organisation und maximal 30 KI-Fixes pro Stunde (POST /sites/{id}/fixes). Darüber hinaus erhalten Sie 429 rate_limited.

curl -H "Authorization: Bearer sa_live_..." \
  https://seoasist.com/api/v1/sites

#Response-Envelope

Jede erfolgreiche JSON-Antwort sieht wie folgt aus:

{ "ok": true, "data": {}, "ms": 42 }

data enthält das Ergebnis des Endpunkts und ms ist die Antwortzeit in Millisekunden. Die einzige Ausnahme ist llms.txt, das reinen Text (text/plain) zurückgibt. Fehler liefern { "ok": false, "error": "<code>", "message": "…" }.

#Endpunkte

Alle Pfade beziehen sich auf die Basis-URL. {id} ist eine Website-ID, die Sie über GET /sites erhalten.

#Konto und Websites

#Probleme, Fixes und Regeln

#Keywords und Inhalte

#Backlinks, Outreach und Mitbewerber

#Überwachung und KI

#Organisation

Inhalts-Statuswerte: idea, planned, generating, draft, review, approved, scheduled, published, failed, archived. Regel-kind-Werte: title, meta_description, canonical, robots, h1, img_alt, og, json_ld, hreflang, redirect, lang, attr, link, meta. matchType: exact, prefix, regex, all.

#Beispiele

Einen KI-Fix starten:

curl -X POST https://seoasist.com/api/v1/sites/SITE_ID/fixes \
  -H "Authorization: Bearer sa_live_..." \
  -H "Content-Type: application/json" \
  -d '{"issueCode":"missing_meta_description"}'

Keywords zum Tracking hinzufügen:

curl -X POST https://seoasist.com/api/v1/sites/SITE_ID/keywords \
  -H "Authorization: Bearer sa_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keywords":["seo tool","site audit"]}'

Aufgaben wie Crawls und Fixes werden in eine Warteschlange eingereiht. Verfolgen Sie das Ergebnis über den passenden GET-Endpunkt (/sites/{id}, /sites/{id}/fixes).

#Fehlercodes

#FAQ

#Ich habe meinen Schlüssel verloren. Kann ich ihn wieder ansehen?

Nein. Schlüssel werden nur als Hash gespeichert. Widerrufen Sie den alten Schlüssel und erstellen Sie einen neuen.

#Kann ich denselben Schlüssel in einem MCP-Client verwenden?

Ja. Es gibt zwei Wege:

• Remote MCP (ohne Installation, empfohlen): https://seoasist.com/api/mcp. Fügen Sie diese URL als Connector in claude.ai, Claude Desktop, ChatGPT, Cursor oder VS Code hinzu; es öffnet sich eine SEOAsist-Anmeldung, Sie wählen die Organisation sowie die Berechtigungen aus und müssen keinen Schlüssel kopieren. Schritt-für-Schritt-Anleitungen und Ein-Klick-Installationslinks finden Sie im Panel unter Einstellungen → Integrationen → KI-Assistenten verbinden. Führen Sie in Claude Code claude mcp add --transport http seoasist https://seoasist.com/api/mcp aus und melden Sie sich beim ersten Aufruf mit /mcp an. Wo sich kein Anmeldefenster öffnen kann (Server, CI), senden Sie den API-Schlüssel mit --header "Authorization: Bearer sa_live_...".
• Lokal (stdio): Die Ansicht MCP-Server im Reiter API-Schlüssel bietet eine fertige Konfiguration für Claude Desktop, Claude Code und Cursor; Sie tragen den Schlüssel in die Variable SEOASIST_API_KEY ein.

Nach der Verbindung erscheinen die vorgefertigten Befehle seo_round, content_from_gap, backlink_outreach, agent_tasks und weekly_report im Befehlsmenü der KI-App. MCP-Tools rufen dieselben Endpunkte auf; Schreib-Tools benötigen einen Schlüssel mit Schreib-Berechtigung. Seiten-Überarbeitungen (page_update) können über die API nicht live veröffentlicht werden; es werden nur Blog-Beiträge veröffentlicht. Alle Tools, Berechtigungen und Fehlercodes finden Sie in der MCP-Referenz; die Einrichtung pro App wird unter KI verbinden beschrieben.

#Kann ich die API direkt aus dem Browser aufrufen?

Die API liefert einen Access-Control-Allow-Origin: * Header zurück. Dennoch sollten Sie einen Schlüssel niemals in eine öffentliche Seite einbetten; jeder, der den Schlüssel sieht, kann auf die Daten Ihrer Organisation zugreifen.