Raw Markdown · rankion-api-reference.md

Rankion.ai API Reference

Stand: 2026-11-07 · Version: v1 · 771 Endpoints

Single Source of Truth für die komplette REST-API. Diese Datei wird via CLAUDE.md auto-importiert und serviert /api-reference + /api-docs/markdown.

Vollständigkeits-Gate: Jeder /v1-Route MUSS hier eine Zeile haben — erzwungen durch php artisan api:doc-coverage (hart im Deploy: Pipeline-Stage test:static in .gitlab-ci.yml + server-seitig in deploy/release.sh [5/10] vor der OPcache-Aktivierung, analog zu schema:lint/mcp:catalog-coverage). Neuer Endpoint ohne Doku-Zeile ⇒ Deploy bricht ab. Skelett-Zeilen: php artisan api:doc-coverage --emit.

Authentifizierung

# Token im Frontend erstellen: /settings/api-tokens
TOKEN="<dein-sanctum-token>"
BASE="https://rankion.ai/api/v1"

curl -H "Authorization: Bearer $TOKEN" \
     -H "Accept: application/json" \
     "$BASE/projects"

Alle Endpoints sind Team-scoped via auth:sanctum Middleware. Cross-Team-Zugriff → 403.

Antwort-Formate

• 2xx Success — JSON
• 202 Accepted — Job dispatched (async). Response enthält keyword_id, article_id etc. zum Pollen.
• 400/422 Validation Error — {message, errors:{field:[reason]}}
• 403 IDOR / Team-Mismatch
• 402 Insufficient credits
• 404 Resource not found
• 409 Conflict (z.B. Article bereits am publishen)

Credit-Mechanik

Jobs/Aktionen mit credits:N Middleware prüfen vor dem Job-Dispatch, ob das Team-Guthaben N Credits deckt (sonst 402); gebucht wird im Job bzw. in der Aktion selbst. Bei cache=false Refresh (Explorer) prüft die Anfrage das Guthaben; die 50 Credits bucht der Hintergrund-Job einmal vor dem Anbieter-Abruf (ohne Guthaben kein Abruf, processing_status=failed; scheitert der Abruf endgültig, wird erstattet).

🎯 AI Visibility Tracking

Projekte

Freigaben (Cross-Team-Sharing)

Ein TrackingProject an einen anderen bestehenden Rankion-Nutzer (auch in einem anderen Team) mit Lese- UND Schreibzugriff freigeben. Läufe, die ein Gast startet, belasten das Eigentümer-Team. Auth ist pro Endpoint asymmetrisch (Eigentümer vs. Eingeladener) — siehe „Auth"-Spalte.

Keywords / Prompts

Prompt-Liste mit mehrdimensionalem Filter — GET /tracking-projects/{id}/prompts akzeptiert: ?search= (Volltextsuche auf prompt_text, MariaDB-FULLTEXT Boolean-Mode: mehrere Wörter = UND, +pflicht -ausschluss "exakte phrase"; Substring-Fallback bei <3-Zeichen-Termen), ?tags[]= (Tag-IDs; OR innerhalb Dimension, AND zwischen Dimensionen), ?category[]= (string ODER array, back-compat), ?intent[]=, ?funnel[]=, ?persona[]=, ?language[]=, ?monitor_status[]=, ?volume_min=, ?active_only=1, ?per_page= (paginiert sonst flache Liste).

Prompt-Tagging (team-weite Tag-Taxonomie + Zuweisungen)

Alle Ressourcen team-gescoped (Fremd-Team → 404). 4 System-Dimensionen (topic/competitor/sub_intent/campaign) pro Team auto-geseedet.

Cited Sources

Insights

Zeitraum der drei Insights-Endpunkte low-hanging-fruit, platform-gap, potential-hero (seit 21.09.2026, dieselben Regeln wie der Zeitraum-Knopf der Oberfläche, SSOT App\Support\AiVisibilityZeitraum):

• days=N (Standard 30) heißt wie bisher „N Tage zurück bis heute", also N+1 Kalendertage einschließlich heute (days=7 am 21.09. = 14.09. bis 21.09.). Werte außerhalb 1–365 werden begrenzt.
• from + to (beide YYYY-MM-DD, nur zusammen) statt days: ganze Kalendertage, beide eingeschlossen, höchstens 365 Tage, nicht in der Zukunft. Ein from vor dem Fenster wird auf den frühesten erlaubten Tag (heute − 364) angehoben, ein to nach heute auf heute; liegt der ganze Zeitraum außerhalb, bleibt ein einzelner Tag am Rand des Fensters.
• Jede solche Kürzung steht als range_adjusted: true in der Antwort. days in der Antwort ist die Stufe bzw. bei freiem Zeitraum die Zahl der Kalendertage.
• 422 mit Feldfehler: nur eines der beiden Daten, kein gültiges Datum, from nach to, days keine Ganzzahl.

Brand-Accuracy (Faktencheck)

Surface der Phase-0-Fact-Check-Engine: jeder LlmResponseClaim-Befund (Abweichung zwischen LLM-Aussage und vouchter Wahrheitsquelle) wird hier gelistet, aufgelöst und re-verifiziert. Alle Routen team-/share-scoped; {claim} ist nested-IDOR-validiert (Claim muss zum {id}-Projekt gehören → sonst 404). Seed/Refresh crawlen NUR die Eigen-Domains des Projekts (SSRF-restricted). Kosten-amplifizierende Routen: throttle:5,1.

Reality Check (AI Visibility Index)

Live Prompt Check (ad-hoc Multi-LLM-Fan-out)

User-Prompt geht parallel an ausgewählte LLMs (ChatGPT, Perplexity, Claude, Gemini, Copilot, Grok) je mit/ohne Web-Search. Live-Card-Grid in der UI, persistente Runs, Sentiment + Brand-Extract pro Antwort.

Status-Lifecycle: pending → running → completed | partial | failed. Polling alle 3-5s. Web-Search-Support: chatgpt, perplexity, claude, gemini. Copilot/Grok ignorieren das Flag. google_ai_mode ist IMMER grounded (Google AI Mode via DataForSEO) und läuft genau 1× pro Prompt — kein with/without-search-Doppel, kein Reality-Check-Blind-Pass. Skills: prompt-check.{list-runs,get-run,create-run,export-run} — Chatbot-fähig via Agentic-Skill-Index.

📝 Articles

CRUD

Website-Import (Plan-Hub #32)

Scannt die Projekt-Domain nach vorhandenen Blog-Artikeln (Sitemap + RSS-Autodiscovery + Blog-Pfad-Heuristik, JSON-LD datePublished/ dateModified wo vorhanden) und importiert eine ausgewählte Teilmenge als Article (source='imported', imported_at, import_source_url). Vorschau+Auswahl-Workflow — kein automatischer Voll-Import.

Aktionen

Versions

Zitat-Prüfung

Artikel-Export

Freshness

Internal Linking

Standalone

CMS-Integrations

🛬 Landingpages

Phase-1-REST-Slice: Polling einer laufenden Bulk-Generierung (read-only, team-gescopt, 0 Credits). Idiom/Anti-Patterns: siehe docs/modules/landingpage-generator.md → „Workflow (GEO-Optimizer-Perspektive)".

🔍 SEO Suite

Rank Tracker (Phase 1)

Keyword Explorer (Phase 2)

Keyword Gap (Phase 3)

Site Audit (Phase 4)

Issues — response fields. Each item in GET /site-audit/{crawl}/issues returns: {id, site_crawl_id, page_id, url, issue_type, severity, message, context, fix_priority, status, has_ai_brief, ai_brief_generated_at}. The url field is sourced from the crawl page (eager-loaded) and is null if the page row was deleted.

Grouped view — GET /site-audit/{crawl}/issues?group_by=type. Additive aggregation (mirrors the UI's grouped Probleme-tab): one row per (issue_type, severity) — {data:[{type, label, severity, total, open, fixed, dismissed}]}, sorted by severity rank (critical→notice) then total desc. label is the human-readable name (IssueTypeLabeler). Respects the severity and issue_type query filters (status is NOT pre-filtered — the counts expose the open/fixed/dismissed split). No pagination, no trend (trend is UI-only). group_by accepts only type (else 422). Without the param the per-issue shape above is unchanged.

Bulk-mark — PATCH /site-audit/{crawl}/issues/bulk. Throttle: 30/min. Body:

{
  "filter": {
    "issue_type": "missing_alt_text",
    "severity": "high",
    "status": "open"
  },
  "new_status": "fixed"
}

All filter.* fields are optional. filter.status is the FROM-state to match (only flip rows currently in this status). new_status is required and must be one of open|dismissed|fixed. Response: {data:{affected:int, new_status}, meta:{applied_filter:{...}}}.

Single-Mark — PATCH /site-audit/issues/{id}. Single-Issue-Status ändern. Body: {"status":"fixed"|"dismissed"|"open"}. Returns {id, status}. Idiom: NACH JEDEM angewendeten Fix MUSS der API-Caller diesen Endpoint mit status=fixed aufrufen — sonst bleiben Issues im Dashboard fälschlich als „open", und die „seit letztem Crawl behoben"-Vergleichsmetrik der nächsten Crawl-Iteration wird wertlos. Team-scope via Parent-Crawl.

Crawl-Summary Response — GET /site-audit/{crawl} returns {data: {id, status, pages_crawled, pages_failed, total_issues, crawl_depth, max_pages, credits_used, tracking_project_id, started_at, completed_at, bridge_dispatched_at, bridge_completed_at, created_at, error_code, error_message, error_text, deep_link}}. Fehlergrund seit Plan-Hub #92: error_code ist die maschinenlesbare Klasse (timeout, worker_restart, url_unreachable, host_invalid, sitemap_empty, aborted_by_user, unknown), error_message der gekappte Rohtext (max. 500 Zeichen), error_text die Fassung für Menschen — dieselbe Quelle, die die Detailseite zeigt. Alle drei sind null, solange der Lauf läuft oder sauber durchlief. Bridge-Timestamps seit 2026-05-14: bridge_dispatched_at zeigt „Grounding-Batch dispatched, Issues kommen noch", bridge_completed_at zeigt „alle grounding_*-Issues final". Caller-Polling-Condition: data.status='completed' && data.bridge_completed_at != null.

Abbruch — POST /site-audit/{crawl}/abort. Bricht einen Lauf im Status queued oder running ab; 0 Credits. Antwort {message, crawl_id, status:'aborted'}. 409 wenn der Lauf bereits beendet ist, 404 bei fremdem Team. Der Abbruch hält: der Crawler prüft den Status zwischen zwei Seiten und beendet sich, statt ihn danach mit completed zu überschreiben — anders als die beiden älteren Abbruch-Muster des Projekts, die nur ein DB-Flag setzen. Verbrauchte Credits werden nicht erstattet (Erstattung: Plan-Hub #93).

Auto-Grounding-Bridge. When a crawl completes, the system automatically dispatches an async Grounding-Audit batch (Grounding Page Standard v1.5, E-E-A-T, People-First) over up to the first 100 crawled pages. When that batch finishes, structured findings are imported as SiteCrawlIssue rows with issue_type prefix grounding_*. No extra credits charged — the bridge runs piggyback on the crawl. Idempotent: re-running the same crawl will not duplicate grounding_* issues (dedup by (site_crawl_id, issue_type, site_crawl_page_id)).

Format grounding_<framework>_<category>_<code>. Typical codes (15 detector rules in v1.5-gp framework):

• grounding_v1_5_gp_h1_entity_only — H1 not pure entity name
• grounding_v1_5_gp_lead_single_sentence_definition — lead is not a 1-sentence definition
• grounding_v1_5_gp_lead_retrieval_sentence — missing retrieval-stabilization sentence
• grounding_v1_5_gp_h2_entity_prefix, grounding_v1_5_gp_disambiguation_block
• grounding_v1_5_gp_human_notice, grounding_v1_5_gp_timestamps_visible
• grounding_v1_5_gp_anchors_stable_ids, grounding_v1_5_gp_facts_dl_grid
• grounding_v1_5_gp_jsonld_present, grounding_v1_5_gp_jsonld_faq_when_html_faq
• grounding_v1_5_gp_head_canonical_absolute, grounding_v1_5_gp_eeat_author_bio_schema
• grounding_v1_5_gp_faq_entity_repeated, grounding_v1_5_gp_volatile_dated_sourced

Filter via GET .../issues?issue_type=grounding_v1_5_gp_h1_entity_only. Bulk-mark via filter:{issue_type:"grounding_v1_5_gp_eeat_author_bio_schema"}.

Backlinks (Phase 5 + Phase 6 DFS-Erweiterungen)

Backlinks by Domain (one-shot lookup, ohne Projekt-Setup)

Schneller Lookup für eine Domain ohne sie als Projekt anlegen zu müssen — z.B. Konkurrenz-Recherche, AI-Agent-Calls. {domain} darf Buchstaben/Ziffern/./- enthalten, alles andere → 404.

Geändertes Verhalten seit 19.09.2026 (Plan #261). Die lesenden by-domain-Endpunkte liefern Kennzahlen nur noch, wenn das eigene Team für die Domain berechtigt ist: entweder es hat sie selbst abgerufen (Zeile in backlink_lookups, entsteht durch POST …/pull) oder es trackt sie in einem eigenen Projekt. Sonst: 404 — bewusst nicht 403, damit die Antwort nicht verrät, ob die Domain bekannt ist.

Vorher gab es diese Prüfung nicht: die Backlink-Tabellen sind teamübergreifend geteilt (Kostenersparnis), weshalb jeder Token die Kennzahlen jeder Domain lesen konnte, die irgendein anderes Team je gezogen hatte.

Was das für bestehende Aufrufe heißt: Der übliche Ablauf POST …/pull → warten → GET … funktioniert unverändert; der Pull legt die Berechtigung jetzt selbst an. Ein GET auf eine Domain, die nie abgerufen und nicht getrackt wird, antwortet ab sofort mit 404 statt mit Daten. Nicht betroffen: POST …/pull, …/enrich-spam-scores und die beiden link-gap/competitor-overlap-Starter.

Backlinks Subscription

🐍 Sandbox (Chat Python-Analyse)

Ad-hoc-Datenanalyse: LLM-generierter Python-Code läuft in einer doppelt-gesicherten Sandbox (bubblewrap + systemd-run, kein Netz/FS/Env, 256 MB RAM, ~20 s Hard-Kill). Die Plattform exportiert die angeforderten Datasets team-korrekt als JSON nach data/<type>.json; das Script hat NIE DB-/Netz-/Env-Zugang. Nur Python-Stdlib. Letztes Mittel — wenn ein Endpoint die Frage beantwortet (insb. Link-Gap), diesen nutzen, nicht die Sandbox.

Request (POST /sandbox/runs):

{
  "script": "import json; d=json.load(open('data/backlink_refdomains.json'))['rows']; print(sum(1 for r in d if r['toxic_severity']=='high'))",
  "datasets": [ { "type": "backlink_refdomains", "domain": "example.com", "limit": 2000 } ],
  "session_id": 123
}

Response (202): { "id": 42, "status": "pending" } — dann GET /sandbox/runs/42 bis status ∈ {completed, failed, timeout}; das Ergebnis steht in stdout.

Dataset-Katalog (je Run ≤ 5 Datasets, ≤ 10 MB/Dataset; jede Datei = Envelope {type, params, count, truncated, rows[]}):

Limits: Script ≤ 20 KB, stdout/stderr je ≤ 64 KB (Rest abgeschnitten + markiert). Stdlib-only: json, csv, statistics, collections, math, re, itertools, functools.

🛠 Keywords (Research & Expansion)

GET /projects/{project}/keywords liefert pro Keyword zusätzlich source (deep|quick|import|ai_search — nur auf Recherche-Wurzeln; einzelne via POST angelegte Keywords bleiben ohne source) und parent_keyword_id; Filter ?research_id={id} liefert nur die Keywords einer Recherche.

POST /projects/{project}/keywords/import — Keyword-Liste importieren (async, 202). Body: {name?, rows: [{keyword, search_volume?, cpc?, difficulty?, intent?}], cluster?} (max. 2000 Rows, Dedupe case-insensitive). cluster=true holt die Google-Top-10 je Keyword und fasst Keywords mit ≥50 % SERP-Überschneidung zu Clustern zusammen — Credits: 10 je angefangene 100 Keywords (402 bei zu wenig Guthaben). Response: {research_id, keywords_received, cluster, credits_charged, status_url, results_csv_url}.

POST /projects/{project}/keywords/import/csv — CSV-Datei-Variante: multipart file (csv/txt/xlsx/xls, max 1 MB / 2000 Rows), optional name, cluster. Spalten-Mapping auto-erkannt über Header (de/en: keyword/suchbegriff/term, volumen/search_volume, cpc, difficulty/schwierigkeit, intent), Zahlen locale-aware („1.200" → 1200). Explizites Mapping: mapping[<feld>]=<spalten-index> (0-basiert; Felder: keyword, search_volume, cpc, difficulty, intent) überschreibt die Auto-Erkennung pro Feld — nicht angegebene Felder bleiben auto-erkannt. has_header=false für Dateien ohne Header-Zeile (Zeile 1 zählt dann als Daten; mapping[keyword] ist Pflicht). Keine Keyword-Spalte → 422 no_keyword_column + detected_headers. Response wie oben, zusätzlich skipped + detected_mapping (= effektives Mapping). research_id ist die Batch-ID.

POST /projects/{project}/keywords/ai-research — KI-Recherche mit Unternehmenskontext starten (async, 202). Body: {limit?} (1–50, Standard 30). Kein Saatbegriff — das ist der Unterschied zu POST /keywords/research: die Begriffe leitet eine OpenAI-Websuche aus dem Projekt-Stammsatz ab (Branche, Marke, Zielgruppen, Leistungen, Website). Response: {status: queued, research_id, source: "ai_search", credits, status_url}. Die KI liefert KEINE Suchvolumen — die Zahlen holt anschliessend dieselbe DataForSEO-Messung wie beim Schnell-Pfad, die Werte sind also gemessen, nicht geschaetzt. Je Vorschlag wird die Belegadresse gespeichert (source_urls); ein leeres Array heisst „erhoben, aber ohne Beleg", null heisst „nie erhoben". Fortschritt ueber status_url (derselbe Polling-Endpunkt wie beim Import). 5 Credits, beim Start reserviert und bei einem Fehlschlag zurückgebucht — ein Ausfall kostet also nichts, aber das Guthaben ist während des Laufs gebunden. Reicht es nicht: 402 insufficient_credits. Läuft für das Projekt bereits eine KI-Recherche, wird ein zweiter Start abgewiesen.

GET /keyword-researches/{id}/status — Batch-Polling: {status: queued|processing| clustering|completed|failed, is_finished, progress_percent, keywords_processed, keywords_pending, keywords_total, clusters_count, clustered_keywords, error_message, results_csv_url}. progress_percent (0–100, eine Nachkommastelle) = Anteil der Keywords mit abgeschlossenem SERP-Fetch (der zeitfressende Teil); während des finalen Clusterings gecappt auf 99, exakt 100 nur bei is_finished=true. Backoff 30s empfohlen.

GET /keyword-researches/{id}/results.csv — Cluster-Ergebnis als maschinenlesbare CSV (erst bei completed, sonst 409). Komma-separiert, UTF-8, snake_case-Header: cluster_id,cluster_role,cluster_main_keyword,cluster_size,keyword,search_volume,cpc, difficulty,intent,article_titles — cluster_role ∈ main|sub|solo, jede Zeile trägt cluster_id + cluster_main_keyword (selbsterklärend für LLM-Weiterverarbeitung). Sortierung: größte Cluster zuerst, im Cluster main → subs nach Volumen.

GET /projects/{project}/keyword-researches — Recherche-Historie (Wurzeln mit source, processing_status, keywords_count), paginiert.

✍️ Content Intelligence

Storylines

Interview-Mode (Artikel aus einem Interview)

Karte #10150. Ziel nennen, KI-Fragen vorschlagen lassen, Fragen anpassen, je Frage tippen oder ein Audio hochladen, dann den Artikel erzeugen. Fragen und Antworten gehen als Briefing in GenerateArticleJob. Alle asynchronen Laeufe antworten 202; Guthaben fehlt → 402 (insufficient_credits), fachlicher Abbruch → 422 / 409 (interview_error). Modul-Doku: docs/modules/article-interview.md.

Style Profiles

Knowledge Base

Link Lists

Orphan Scans

Kosten: ceil(zu crawlende Seiten / 10) Credits, abgebucht beim Start; discover liefert genau diesen Betrag als estimated_credits. Ein zweiter Start desselben Scans antwortet 422 und bucht nicht; zu wenig Guthaben ergibt 402 mit required und balance.

Overview

📅 Calendar & Images

Calendar

Project Images (legacy per-project listing)

Image Gallery (permanent, team-scoped)

Cross-Team-IDs liefern 404 (nicht 403, kein Existenz-Leak).

Dateien (Nicht-Bild-Chat-Dateien, team-scoped)

Komplement zur Image Gallery: alles mit mime_type ≠ image/* (agent-generierte xlsx/csv/md + User-Uploads). Cross-Team- ODER Bild-id liefert 404. Liste zeigt nur lebende Dateien (expires_at IS NULL OR >= now). Items: {id, original_name, type_label, size_bytes, mime_type, session{id,title}, expires_at, expires_in_days, pinned, is_favorite, tags, download_url}.

🤖 AI Tools

Agentic Chat — Master Agent als Endpoint

Body:

• message (string, required, max 10k): User-Anfrage in natürlicher Sprache
• session_id (int, optional): bestehende Session fortführen

Query-Parameter:

• wait_for_final (bool, default true): bei wait_and_recheck-Handoff (z.B. asynchroner DataForSEO-Pull) pollt der Endpoint serverseitig bis zur finalen Resume-Antwort (max ~480 s). Auf false setzen um sofort die Placeholder-Nachricht zu erhalten.

Response 200: {session_id, message_id, text, tool_calls, iterations, credits_used, duration_ms, resumed}

resumed: true heißt: der Master-Agent hat mid-turn wait_and_recheck getriggert und der Endpoint hat erfolgreich auf den Resume-Turn gewartet. Der text ist dann die finale Antwort, nicht der Wartehinweis.

Hinweise:

• Synchron — komplette Loops können 5–10 min dauern (PHP-FPM 600 s Hardlimit, Client-Timeout entsprechend setzen)
• Triple-scoped (team_id + user_id + id) gegen IDOR
• Spart externen Clients die Orchestrierung der 12+ Meta-Tools — der Master-Agent wählt + ruft selbst auf
• Iterations-Cap 150, Wall-Clock-Cap 25 min, No-Progress-Detector 8 — alle env-overridable, alle münden bei Hit in einen tools-disabled Summarize-Call statt einer harten Fehlermeldung
• Companion Claude Code Skill: rankion-agent

AI Scanner / Detection

Humanizer

Content Optimizer

Async-Vertrag (Subsystem B P0.3 — fixed 2026-05-09):

POST /v1/content-optimizer/analyze returns 202 mit:

{
  "message": "Content optimization started",
  "id": 6,
  "optimization_id": 6,
  "poll_url": "/api/v1/content-optimizer/6"
}

Plus Header Location: /api/v1/content-optimizer/6.

Polling-Pfad: GET /api/v1/content-optimizer/6 (canonical) — der Pfad /optimizations/6 funktioniert auch (Alias-Route, weil das Field heisst optimization_id). Caller können beides.

optimization_id bleibt für Kompatibilität, aber neue Caller sollten id lesen.

🥊 Competitor Analysis

📊 Content Audits (Phase 4 — site-wide content scanner)

Site-wide content-quality crawler. Walks a domain (sitemap-discovered), scores each page on SEO (0–100), content quality (0–100), word count, and emits issues[] = {type:error|warning|info, category, message} plus recommendations[]. Distinct from /site-audit — this module is the content-quality angle, /site-audit is the crawl/issue/grounding angle.

Audits-listing — filters on GET /content-audits. Query params:

• tracking_project_id=<int> — filtert auf Audits eines Tracking-Projects (FK→tracking_projects.id).
• source_url=<string> — exact-match auf die Audit-URL (Audit ist 1:1 mit URL gescoped).
• status=running|completed|failed
• type=full|quick (UI-Pfade sitemap/single werden nicht über die API gestartet).
• project_id → 422 (Variante 1 Rename 2026-05-10) — Migration-Hint im Response. tracking_project_id ist die kanonische FK, parallel zum /grounding-Pattern.

Listing-Schema (data[].keys): id, tracking_project_id, source_url, type, status, total_pages, avg_seo_score, total_issues, created_at. Detail-Schema (/content-audits/{id}) enthält zusätzlich team_id, user_id, project_id (legacy), tracking_project_id, summary, ….

POST-Body akzeptiert: {source_url, type?:full|quick, tracking_project_id?}. project_id → 422 mit Migration-Hint. tracking_project_id wird via exists:tracking_projects,id validiert und persistiert.

Pages-listing — filters on GET /content-audits/{id}/pages. Query params:

• status=open|solved — open is the canonical alias for is_solved=false. Anything other than solved resolves to open.
• priority=critical|high|medium|low
• min_seo_score=0..100, max_seo_score=0..100
• issue_type=<string> — matches any issues[].type value (canonical severity buckets are error, warning, info). Implemented as JSON-LIKE on the serialized issues column.
• sort= one of url|title|seo_score|content_quality_score|word_count|priority|is_solved, dir=asc|desc, per_page= (default 50).

Response shape: {progress:{total, solved, open, percent}, pages:{data:[…], current_page, last_page, …}}.

Audit-over-time compare — GET /content-audits/{id}/compare. Read-only, 0 credits, runs no new crawl (pure read of the persisted summary + page issues). Compares {id} (current) against a baseline:

• against=<int> — explicit baseline audit id (team-scoped; 422 if not found / foreign team).
• omitted → the most recent prior completed audit of the same source_url.
• No prior audit → 200 with baseline: null and null trend deltas (never 404/500).

Response shape: {current, baseline, trend:{avg_seo_score_delta, avg_quality_score_delta, total_issues_delta, by_type_delta:{error,warning,info}}, issues:{new:[…], fixed:[…], persistent:[…], by_type_delta}}. Deltas = current − baseline. Issue identity is normalized (url + type + message-core, numbers/brackets stripped) so a re-measured count is not flagged as "new".

Single-page refresh — POST /content-audit-pages/{id}/refresh. 1 credit (credits-auto:1, SSOT config/credits.php flat content_audit_refresh_page). Async re-crawl of one page: sets row status=pending, dispatches RefreshAuditPageJob, returns 202 {page_id, status:queued}. Guarded on the parent audit being completed (else 422) so a mid-flight batch crawl can't re-grab the page. Throttle: 30/min. Poll GET /content-audit-pages/{id} for the pending→processed transition.

Bulk-mark — PATCH /content-audits/{id}/pages/bulk. Throttle: 30/min. Body:

{
  "filter": {
    "priority": "low",
    "status": "open",
    "min_seo_score": 0,
    "max_seo_score": 50,
    "issue_type": "error"
  },
  "is_solved": true
}

All filter.* fields are optional. filter.status is the FROM-state to match (only flips rows currently in this state). is_solved is required and is the new state to write. Response: {data:{affected:int, is_solved:bool}, meta:{applied_filter:{…}}}. Team-scoped via audit.team_id — cross-team access returns 403.

filter.project_id → 422 (Variante 1 Rename 2026-05-10): Pages haben keinen Project-FK; das Projekt ergibt sich aus dem Parent-Audit. Vorher wurde filter.project_id stumm gedroppt — was Mass-Updates über alle Pages des Audits zog statt nur über die eines Projekts. Jetzt 422 mit klarem Hint.

🧑‍🤝‍🧑 Community (Mitglieder)

Nur für Administratoren. Die Kette ist auth:sanctum plus admin — ein gewöhnlicher Kunden-Token bekommt 403. Grund: ein Community-Mitglied gehört keinem Team an, es gibt also nichts zu scopen; ohne das Admin-Gate bekäme jeder Token Klarnamen und Mailadressen aller Mitglieder. Dieselbe Bauart wie /v1/outbound/*.

Community-Forum (Plan-Hub #116, Position 16)

Lesen ist offen (Drosselung 60/min, wie der Stufen-Katalog), Schreiben und die Meldungen brauchen auth:sanctum plus Admin (120/min). Der Grund für die Trennung: dieselben Inhalte stehen ohne Anmeldung im Web — sie hinter einen Schlüssel zu stellen verbirgt nichts und nimmt der Auffindbarkeit in KI-Antworten die Quelle. Schreiben geht dagegen nur über das Team, weil ein Community-Mitglied gar keinen API-Schlüssel besitzt (eigener Guard, keine Token-Fähigkeit am Model); member_id sagt, in wessen Namen geschrieben wird.

Verborgene Themen und Antworten erscheinen nirgends — was die Moderation weggenommen hat, bleibt auch hier weg. Und es gibt keine Mailadressen: die Meldungs-Liste sagt nur, OB ein Melder erreichbar ist, nicht wie.

Kennwort und remember_token verlassen die Schnittstelle nie (im Model als $hidden, zusätzlich durch eine ausdrückliche Feldliste im Controller).

Die Mitgliederzeile trägt seit Plan-Hub #115 zusätzlich membership (plan_id, plan_label, status, ends_at, stripe_subscription_id) und team_id. Die Feldliste im Controller ist eine ausdrückliche Aufzählung — ein neues Feld am Model erscheint dort nicht von selbst.

Community — Skills und Videothek (Plan-Hub #118, Position 11)

Lesend ohne Token, Drosselung 60/min — dieselbe Begründung wie beim Forum darüber: die Übersichten stehen ohne Anmeldung im Web.

read_access steht in jeder Antwort, auch in den Listen. Ein Aufrufer soll unterscheiden können zwischen »dieser Eintrag hat keinen Volltext« und »dieser Volltext ist mir verschlossen« — sonst sieht ein PRO-Eintrag aus wie ein leerer.

Die Grenze des Zugriffsschutzes bei Videos steht in docs/modules/community.md: ein nicht gelisteter Videoverweis ist kein Schutz, wer die Kennung hat, sieht das Video. Für PRO-Inhalte gehört zusätzlich die Domänen-Sperre beim Videodienst gesetzt.

Community — Stufen-Katalog (OFFEN, ohne Token)

Die dritte Routengruppe dieses Bereichs und die einzige ohne Riegel (Plan-Hub #115, Position 14). Das ist kein Versehen: die Stufen und ihre Preise stehen ohnehin auf der öffentlichen Kaufseite unter /community/mitgliedschaft. Sie hinter einem Token zu verstecken schützte nichts und machte den Katalog für ein Fremdsystem unbrauchbar, das einen Preis anzeigen will. Gedrosselt auf 60 Anfragen je Minute — offen heißt nicht unbegrenzt.

Die Stripe-Kennungen (stripe_product_id, stripe_price_id) verlassen diese Endpunkte nicht: sie sind keine Geheimnisse, gehören aber nicht in eine Preisliste. price_eur ist bewusst eine Zeichenkette — als Zahl serialisiert macht JSON aus 35.00 die 35 und aus 35.50 die 35.5, und ein Feld, dessen Typ zwischen ganzzahlig und gebrochen wechselt, ist für ein Fremdsystem eine Fehlerquelle. Die tragende Wahrheit ist ohnehin price_cents.

👥 Community Monitor

Kanonisch seit 03.09.2026 (Plan-Hub #114): /v1/community-monitor/*. Der Wortstamm community gehört seither der öffentlichen Community mit eigener Mitgliederverwaltung. Die alten Adressen bleiben als Zweitname bestehen und antworten unverändert — kein Fremdsystem muss umgestellt werden.

📈 Site Monitor

🚀 Automation

Bulk Generations

Autopilot

Auto-publish quality gate (TODO-059): when settings.auto_publish=true, each run scores the generated content with the deterministic GEOScorerService and only publishes (and pushes to a connected CMS) if total_score >= settings.min_geo_score (default config('autopilot.min_geo_score')=70). Below threshold → kept as a draft + a skipped_low_score run row; never published. Each run records exactly one row (success/skipped_no_credits/skipped_no_keyword/skipped_low_score/failed). Credit per article = FeatureCost::article(word_count); the gate scoring itself is free.

Pipelines

🏗 Projects & Settings

POST /projects Body: {name, domain?, language?, description?, country?, additional_countries[]?, primary_cms_integration_id?} — country ist der einzelne Primärwert (projects.country, unverändert). additional_countries[] (max 10, je ISO-3166-1 alpha-2) legt/nutzt pro Land ein setup-Tracking-Gerüst (tracking_projects+tracking_keywords-Platzhalterzeile) an, siehe docs/modules/tracking-projects.md. Antwort trägt dann zusätzlich additional_markets: {registered[], skipped[], reason} — reason ist no_domain (Projekt ohne Domain) oder active_tracking_project (Domain hat bereits aktives Tracking, kein Platzhalter wird angelegt); das Feld fehlt ganz, wenn keine additional_countries gesendet wurden. Projektlimit des Tarifs (Karte #10952): ist max_projects erreicht, entsteht kein neues Projekt — 422 {error:"project_limit_exceeded", message, limit{max,used,free,needed,demo_zentrale}}, dieselbe Form wie bei /projects/bulk. limit.demo_zentrale (bool, Karte #11402) ist true, wenn das aktuelle Team die Demo-Zentrale ist: dort entstehen nie Projekte (max = 0), ein Tarifwechsel hilft also nicht, nur das jeweilige Demo-Team. Eine schon vorhandene Domain im Team liefert weiterhin 200 mit dem bestehenden Projekt (Idempotenz), auch am Limit. Bestehende Projekte bleiben über dem Limit voll nutzbar.

POST /projects/bulk (Karte #10919, FB-183) Body: {urls[] (1–100), language?} — legt je gültiger URL ein Projekt im aktuellen Team an (Name = Domain). Schreibweise wie beim Einzelanlegen (DomainNormalizer): mit/ohne https:// und www. ergibt dieselbe Domain. Antwort {created[{line,input,domain,id}], duplicates[{line,input,domain,reason,project_id?}], invalid[{line,input}], limit{max,used,free,needed,demo_zentrale}, limit_exceeded}; reason ist existing_project (gibt es im Team schon) oder repeated_line (steht weiter oben in der Liste). 201, wenn mindestens eines entstand, sonst 200. Projektlimit des Tarifs (config/pricing.php max_projects) gilt für die ganze Liste: passt sie nicht vollständig, entsteht keines — 422 {error:"project_limit_exceeded", message, limit, data}, limit.free nennt, wie viele noch passen (max/free = null bei unbegrenztem Tarif). limit.demo_zentrale (bool, Karte #11402) ist true im Heimatteam der Demo: dort entsteht nie ein Projekt, die message nennt die Demo-Zentrale statt des Tarifs. Keine Credits.

primary_cms_integration_id (Karte #7398 P#228) setzt das Standard-CMS für neue Artikel des Projekts; PUT /projects/{id} nimmt dasselbe Feld, ausdrückliches null löscht die Zuordnung. Die Regel trägt bewusst kein exists — sie prüfte nur, DASS die Zeile da ist, nicht wem sie gehört. Eine Kennung aus einem fremden Team wird verworfen, nicht abgewiesen: das Projekt entsteht, nur ohne das fremde CMS. Dieselbe Nachprüfung benutzen beide Dialoge (CmsIntegration::bestaetigteWahl()).

🎯 Action Center

Projektfilter (Plan #272): GET /action-center/todos?project_id=<id> liefert die Aufgaben dieses Projekts plus alle Aufgaben ohne Projektbezug — die gelten dem ganzen Team und dürfen beim Umschalten nicht verschwinden. Jede Zeile trägt project_id; null heißt »ohne Projektbezug«. Das Projekt muss dem eigenen Team gehören (sonst 422) und für den Nutzer sichtbar sein (sonst 403) — dieselben zwei Fragen, die auch der Projektumschalter der Oberfläche stellt. Ohne den Parameter ändert sich nichts.

Maßnahmen (K#9294, Eigentümer-Entscheid 15.10.2026): GET /action-center/todos lässt vom Kunden eingetragene Maßnahmen (Todo-Art massnahme, siehe /tracking-projects/{id}/measures) standardmäßig weg — sie sind keine Aufgaben. Nur mit ?kind=massnahme kommen sie, und dann ausschließlich sie: ohne status in jedem Status (eine Maßnahme ist als completed gespeichert), beschränkt auf Tracking-Projekte, die der Nutzer sehen darf (Projektrechte inklusive). Einzelabruf und Aktionen auf eine Maßnahme verlangen die Projektrechte auf ihrem Tracking-Projekt (sonst 404); POST …/move auf eine Maßnahme antwortet 422.

Chancen (Plan #246): GET /action-center/opportunities erkennt live mit denselben Detektoren wie die To-dos, speichert nichts und verschickt keine Alarm-Mail. Antwort data[] = {group, count, items[]} und meta.total; ein Item zeigt nur, wenn sein deep_link auf eine registrierte Route führt und deren Modul für das Team aktiv und nicht admin-gesperrt ist. ?group= mit unbekanntem Wert ergibt 422.

Admin-Modulsperre: Für Nicht-Admins liefert GET /action-center/todos keine To-dos zu einem plattformweit gesperrten Modul (Modulschlüssel oder Zielroute); Einzelabruf und Aktionen auf ein solches To-do antworten mit 404, POST /action-center/todos mit 422. Globale Admins sind ausgenommen.

🔌 Matomo Integration

Die eigene Matomo-Instanz des Teams als Traffic-Quelle. Das Token wird nur geschrieben und nie zurückgegeben (token_set). base_url nimmt nur https an, sonst 422. Fehlerform und Abläufe: docs/modules/integrations-matomo.md.

🔌 Google Integrations

Eigener Google-Zugang je Team (K#11090): GET /google/oauth-client liefert configured, client_id, client_secret_set (nur ob ein Schlüssel hinterlegt ist — der Schlüssel selbst verlässt den Server nie, auch nicht maskiert), active_source (team | shared | none: welcher Zugang beim nächsten »Mit Google verbinden« gilt), redirect_uris.analytics / redirect_uris.reviews (in der Google Cloud Console einzutragen) und updated_at. Lesen darf jedes Teammitglied. PUT (client_id Pflicht, Form ….apps.googleusercontent.com; client_secret Pflicht bei neuem Zugang oder neuer Client-ID, sonst leer = behalten) und DELETE verlangen manage settings (Eigentümer/Administrator), sonst 403; Formfehler 422 mit Feldname. PUT ist auf 10 Aufrufe je Minute gedrosselt. Nach DELETE oder einer neuen Client-ID müssen Verbindungen, die über den alten Team-Zugang liefen, neu verbunden werden.

/google/gsc/properties/{p}/insights/rebuild fuehrt die abgerufenen Search-Console-Zahlen in einen Auswertungs-Stapel ueber, damit die Insight-Karten auf /search-console greifen; ohne diesen Schritt laeuft der Abruf gruen und die Seite bleibt leer. Nimmt optional window_days (1–480, Vorgabe 90). Antwortet 202 mit property_id, window_days und batch_id — letzteres ist null, solange noch nie abgeglichen wurde, denn der Stapel entsteht im Hintergrund-Job. 422, wenn die Property mit keinem Projekt verknuepft ist: dann ruft Rankion gar keine Zahlen ab (analytics:gsc-pull-due waehlt nur verknuepfte Properties), und die Auswertung waere leer. Derselbe Abgleich laeuft taeglich um 04:30 von selbst (analytics:gsc-rebuild-insights, abschaltbar ueber config/analytics.php).

Die Zahlen liest man danach ueber /search-console und /search-console/{id}. Deren row_counts traegt neben queries/pages/daily auch queries_gesamt, pages_gesamt, deckel und gedeckelt: greift der Deckel, umfasst die Auswertung nur die impressionsstaerksten Zeilen, und gedeckelt sagt genau das. source unterscheidet upload von gsc_api.

/google/ga4/properties/{p}/metrics nimmt ?from=&to=&dimension=daily|page|event|ai_source|ai_source_traffic. ai_source liefert die Sitzungen je KI-Quelle (source = Slug aus App\Support\AiReferrerSources: chatgpt, perplexity, gemini, copilot, claude, grok, other_ai; other = Summe aller uebrigen Quellen, der Nenner fuer den Anteil). ai_source_traffic (Karte #9248) liefert dieselben KI-Sitzungen je Quelle UND Verkehrsart: Zeilen {source, traffic_type, sessions, engaged_sessions, conversions, revenue} mit traffic_type = organic, paid oder unknown (bezahlt = GA4-Medium passt auf ^(.*cp.*|ppc|retargeting|paid.*)$; unknown = Daten von vor der Trennung oder Medium (not set)). other fehlt hier; die Summe je Quelle entspricht ai_source.

⭐ Review Sources

📰 Blog (Admin)

💾 Rankion OS

💳 Account / Meta

Demo-Teams (Vertriebs-Demo-Konsole)

Nur für einen Demo-Login (Mitglied mindestens eines Teams mit is_demo), sonst 403. Jedes {team} wird gegen die EIGENEN Demo-Teams des Logins aufgelöst; ein fremdes oder ein Kundenteam antwortet 404. Schreibende Aufrufe: Throttle 20/min. Modul-Doku: docs/modules/demo-einrichtung.md.

🧾 Rechnungsdaten

Team-Rechnungsprofil (Firmenanschrift, USt-IdNr. oder Steuernummer, Rechnungsempfänger, abweichende Anschrift, PO-Referenz). Wird beim Schreiben nach Stripe gesynct.

Workflow (GEO-Optimizer-Perspektive)

Use-Case: Vor dem ersten Checkout das Rechnungsprofil setzen, damit Stripe-Rechnungen korrekte Firmenanschrift + USt-IdNr. (Reverse-Charge) tragen.

Idiom: GET /billing/profile (Ist-Stand lesen) → PUT /billing/profile (vollständiges Profil schreiben, 422 bei ungültigem USt-ID-Format/fehlenden Pflichtfeldern) → der PUT synct synchron nach Stripe; vat_id_status (Stripe-Echo) erscheint beim nächsten GET. Single-Resource (kein Bulk, kein Polling).

Anti-Patterns: Kein wiederholtes PUT in Schleife (jeder PUT triggert einen Stripe-Sync). USt-ID nicht selbst „verifizieren" — das macht Stripe; nur den vat_id_status lesen.

Cross-Module: /billing (Checkout/Invoices) liest dasselbe Profil; InvoiceMail geht an billing_email ?? owner. Modul-Doc: docs/modules/billing.md.

🤝 Partnerprogramm »Kunden empfehlen«

Beitritt, Stammdaten, Zahlen, Provisionen und Abrechnungen des eigenen Kontos, dazu die Admin-Endpunkte des Programms (Karte #7423, Plan #199). Kein Partnerpfad trägt eine Partner-Id — ein fremder Partner ist über diese Endpunkte nicht ansprechbar; der einzige Pfad mit Id (Abrechnungs-PDF) antwortet für eine fremde Abrechnung 404. Admin-Endpunkte: nur globale Admins (is_admin), sonst 403. Solange der Programmschalter affiliate.enabled aus ist (Standard), sind die Endpunkte nicht registriert: 404, auch ohne Anmeldung; sie fehlen dann auch in openapi-v1.yaml. Die IBAN ist schreibbar, aber nie lesbar — auch nicht für Admins: Antworten tragen nur iban_masked (DE89 **** 3000); die volle IBAN einer offenen Auszahlung steht nur auf der Adminseite und in deren CSV, nicht in der API.

Workflow (GEO-Optimizer-Perspektive)

Use-Case: Eine Agentur, die rankion ihren Kunden empfiehlt, tritt per API bei und bekommt ihren Partnerlink für Newsletter und Angebote.

Idiom: GET /affiliate (Vorbelegung lesen) → POST /affiliate mit Stammdaten, Bankverbindung und beiden Zustimmungen → link aus der Antwort teilen. Änderungen per PUT /affiliate/profile. Monatlich GET /affiliate/stats?period=monat für den Bericht an den Kunden, GET /affiliate/statements und das PDF für die eigene Buchhaltung.

Anti-Patterns: Die IBAN nicht zurücklesen wollen — sie kommt nur maskiert. Kein PUT in Schleife: eine geänderte EU-USt-IdNr. löst je Aufruf eine Abfrage beim BZSt aus. Kein Polling von /affiliate/stats im Minutentakt — die Zahlen ändern sich mit Klicks und Zahlungen, nicht live; einmal täglich genügt. POST /admin/affiliate-statements/run ist für den Nachholfall gedacht, der Zeitplaner läuft am 28. von selbst.

Cross-Module: Die Vorbelegung kommt aus /billing/profile. Modul-Doc: docs/modules/referrals.md (nicht öffentlich ausgeliefert).

👥 Team-Mitglieder

Mitglieder-Verwaltung + Einladungen eines Teams. Alle Endpoints team-scoped auf currentTeam() des Token-Users; Gate manage members (Owner/Admin). Delegiert an TeamMembershipService (Single-Source der Mutationen). Fremdes-Team-Member/-Einladung → 404; Service-Regelverletzung (z. B. Owner ändern, sich selbst entfernen, Plan-Rolle, Sitzplatz-Limit) → 422 mit message.

Workflow (GEO-Optimizer-Perspektive)

Use-Case: Team-Sitzplätze verwalten — Kollegen mit passender Rolle einladen, Rollen anpassen, ausgeschiedene Mitglieder entfernen.

Idiom: GET /team/members + GET /team/invitations (Ist-Stand) → POST /team/invitations {email, role} (einladen; 422 bei Limit/Plan-Rolle) → nach Annahme erscheint die Person in /team/members, die Einladung verschwindet aus /team/invitations → PATCH /team/members/{user} für spätere Rollen-Änderungen, DELETE zum Entfernen. Single-Resource, kein Bulk, kein Polling (Annahme passiert async durch den Eingeladenen via Accept-Link).

Anti-Patterns: Keine Owner-Rolle per PATCH/POST vergeben (nur via Ownership-Transfer). Nicht wiederholt dieselbe E-Mail einladen — offene Einladungen sind idempotent (dieselbe Einladung wird wiederverwendet, kein Duplikat). Rolle nicht aus einem hardcoded Set wählen — nur Rollen aus RoleOptions::forTeam() (plan-abhängig) sind gültig, sonst 422.

Cross-Module: Rollen/Permissions stammen aus TeamRole + HasTeamPermissions::canDo(); UI-Pendant ist die Team-Settings-Surface. Modul-Doc: docs/modules/team-members.md.

Agentur-Branding (White-Label-Berichte)

Logo, Primärfarbe und Anzeigename des Teams für Reality-Check- und Site-Monitor-Berichte. Team-scoped auf currentTeam(); 403 ohne Plan-Merkmal white_label (Team::hasFeature), Schreiben zusätzlich nur mit manage settings. Antwort aller vier Endpunkte: {data: {white_label, name, color, report_color, has_logo}} — report_color ist die im Bericht gedruckte Farbe (zu helle Farben werden auf 4,5:1 gegen Weiß abgedunkelt, Farbton bleibt).

Workflow (GEO-Optimizer-Perspektive)

Use-Case: Eine Agentur gibt Berichte unter eigener Marke an ihre Kunden weiter.

Idiom: GET /team/branding (prüft das Plan-Merkmal) → PUT /team/branding {name, color} → POST /team/branding/logo → der nächste erzeugte Bericht trägt das Branding. Kein Polling.

Anti-Patterns: Kein SVG hochladen. Branding nicht je Bericht umsetzen — es ist ein Teamwert.

Cross-Module: gelesen von ai-reality-check und site-monitor über App\Support\AgenturBranding::fuerBericht(). Modul-Doc: docs/modules/agentur-branding.md.

🔬 Page-Deep-Audit (Vision + KI-Render)

Auditiert eine einzelne Landingpage: ein Desktop-Screenshot, Lighthouse-Metriken (Mobile und Desktop), Claude-Multimodal-Vision-Analyse plus optional EIN gpt-image-2 KI-Render der optimierten Variante (Tablet- und Mobile-Renders seit 28.05.2026 entfernt) und optional ein Entwurfsturnier (3 Stufen zu je 2 Entwürfen). Authentifizierung: Authorization: Bearer <token>, alle Endpoints team-scoped.

Pipeline-Status: pending → scraping → screenshotting → analyzing → completed. Der Desktop-KI-Render läuft in einem separaten Background-Job nach completed; ideal_screenshot_url füllt sich anschließend.

Polling-Pattern:

# 1) Audit starten
ID=$(curl -s -X POST $BASE/page-audit \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/landing"}' | jq -r '.id')

# 2) Pollen bis completed + Desktop-Ideal-Render fertig (Hauptflow ~1-2 min, Desktop-Render +2-3 min)
while true; do
  R=$(curl -s -H "Authorization: Bearer $TOKEN" $BASE/page-audit/$ID)
  STATUS=$(echo "$R" | jq -r '.status')
  IDEAL=$(echo "$R" | jq -r '.ideal_screenshot_url // "null"')
  echo "$STATUS desktop_ideal=$([ "$IDEAL" = null ] && echo no || echo yes)"
  [ "$STATUS" = completed ] && [ "$IDEAL" != null ] && break
  sleep 30
done

Response-Shape (GET /page-audit/{id} nach completed):

{
  "id": 10,
  "tracking_project_id": null,
  "url": "https://www.example.com/landing",
  "status": "completed",
  "error_message": null,
  "screenshot_url":         "https://rankion.ai/storage/page-audits/10/screenshot.png",
  "ideal_screenshot_url":   "https://rankion.ai/storage/page-audits/10/ideal.png",
  "lighthouse": {
    "performance": 78, "seo": 92, "accessibility": 88, "best_practices": 83,
    "strategies": {
      "mobile":  { "performance": 78, "seo": 92, "accessibility": 88, "best_practices": 83, "core_web_vitals": { "lcp": 2500, "cls": 0.01 } },
      "desktop": { "performance": 94, "seo": 92, "accessibility": 88, "best_practices": 83, "core_web_vitals": { "lcp": 900, "cls": 0.0 } }
    }
  },
  "analysis": {
    "user_intent": "1-Satz Search-Intent",
    "persona_fit": 75,
    "trust_score": 72,
    "layout_score": 68,
    "cta_score": 65,
    "problem_solution_clarity": 70,
    "above_the_fold_quality": 60,
    "mobile_friendliness_visual": 80,
    "personas": [
      { "name": "...", "who": "...", "primary_motivation": "...",
        "pain_points": ["..."], "goals": ["..."],
        "fit_score": 75, "fit_reason": "..." }
    ],
    "critical_issues": [
      { "severity": "high|medium|low", "title": "...", "explanation": "...", "evidence": "..." }
    ],
    "improvement_suggestions": [
      { "area": "headline|cta|trust|layout|copy|visuals|forms|navigation|seo|accessibility",
        "priority": "high|medium|low",
        "title": "...", "description": "...", "example": "before/after micro-copy" }
    ],
    "summary": "3-5 Satz Executive-Summary",
    "headline_rewrite": "stärkerer H1-Vorschlag oder null"
  },
  "gpt_image_used": true,
  "credits_used": 75,
  "started_at": "2026-04-27T19:28:58Z",
  "completed_at": "2026-04-27T19:30:22Z"
}

Lighthouse-Felder: die flachen Felder (performance, seo, accessibility, best_practices, core_web_vitals, full_report) sind der Mobile-Wert und bleiben der zugesagte Vertrag; strategies.mobile / strategies.desktop kamen am 22.09.2026 additiv dazu. Scheitert ausgerechnet die Mobile-Messung, während Desktop gelingt, sind die flachen Felder vorhanden und null — nie fehlend. Scheitern beide, ist lighthouse wie bisher null. GET /page-audits (Liste) gibt die Models roh heraus: dort heißt dasselbe Feld lighthouse_data.

Status-Codes: 202 (gestartet), 200 (Detail/List), 403 (Cross-Team / Cross-Project), 404 (Audit nicht gefunden), 422 (Validation: url Pflicht, max 500 Zeichen).

Use-Cases:

• Iterative Optimierung: analysis.improvement_suggestions (sortiert nach priority) lesen → Änderungen am Source-Page anwenden → Re-Audit → Score-Diff vergleichen.
• A/B Variant-Generation: ideal_screenshot_url (Desktop+Mobile) als Visual-Reference in den Design-Pipeline-Iteration füttern.
• Persona-driven Copy: analysis.personas[].pain_points + goals → gezielte Headline-/CTA-Varianten schreiben → re-audit.
• Headline-Drop-In: analysis.headline_rewrite ist ein validierter Headline-Replacement — kann direkt in den Live-Page übernommen werden.

📑 Reports & Cross-Module Correlation

Auto-Generator für Tracking-Project-Reports (Markdown-Output via GenerateTrackingProjectReportJob) und ein Cross-Modul-Korrelations-Endpoint, der Site-Audit, Rank-Tracker, Backlinks und AVI verknüpft. Authentifizierung: Authorization: Bearer <token>, alle Endpoints team-scoped.

Reports

Status-Werte: pending → generating → completed (oder failed).

Polling-Pattern:

# 1) Report dispatchen
RID=$(curl -s -X POST $BASE/tracking-projects/$PID/generate-report \
  -H "Authorization: Bearer $TOKEN" | jq -r '.report_id')

# 2) Pollen bis completed
while true; do
  S=$(curl -s -H "Authorization: Bearer $TOKEN" $BASE/reports/$RID | jq -r '.status')
  echo "Status: $S"
  [ "$S" = completed ] && break
  [ "$S" = failed ] && exit 1
  sleep 5
done

# 3) Markdown extrahieren
curl -s -H "Authorization: Bearer $TOKEN" $BASE/reports/$RID | jq -r '.markdown_content' > report.md

Response — POST /tracking-projects/{id}/generate-report (202):

{
  "report_id": 42,
  "tracking_project_id": 7,
  "status": "pending",
  "status_endpoint": "/v1/reports/42",
  "message": "Report dispatched"
}

Response — GET /tracking-projects/{id}/reports (200):

{
  "data": [
    {
      "id": 42,
      "tracking_project_id": 7,
      "team_id": 3,
      "user_id": 12,
      "status": "completed",
      "credits_used": 10,
      "generated_at": "2026-04-27T18:14:22+00:00",
      "created_at": "2026-04-27T18:13:40+00:00",
      "updated_at": "2026-04-27T18:14:22+00:00"
    }
  ]
}

Response — GET /reports/{id} (200):

{
  "id": 42,
  "tracking_project_id": 7,
  "team_id": 3,
  "user_id": 12,
  "status": "completed",
  "markdown_content": "# Tracking-Report Project XY\n\n## Executive Summary\n…",
  "summary_json": {
    "headline_kpis": { "avi_score": 64, "delta_30d": "+8", "top10_keywords": 14 },
    "wins": [ "..." ],
    "risks": [ "..." ]
  },
  "credits_used": 10,
  "error_message": null,
  "generated_at": "2026-04-27T18:14:22+00:00",
  "created_at": "2026-04-27T18:13:40+00:00",
  "updated_at": "2026-04-27T18:14:22+00:00"
}

Status-Codes: 202 (Report dispatched), 200 (List/Detail), 403 (Cross-Team / Cross-Project), 404 (Report/Project nicht gefunden), 429 (Rate-Limit: max 1 / 30 Min).

Cross-Module Correlation

Aggregiert drei Korrelations-Datenpunkte für einen TrackingProject in einem Roundtrip — Risk-Map (Site-Audit × Rank-Tracker), Backlinks-Velocity × AVI-Trend (Pearson, 30d), Smart-Todos.

Response — GET /tracking-projects/{id}/correlation (200):

{
  "data": {
    "site_audit_ranking_risks": [
      {
        "keyword_id": 91,
        "keyword": "best crm",
        "search_volume": 4400,
        "position": 5,
        "url": "https://example.com/best-crm",
        "issues_count": 7,
        "critical_count": 2,
        "medium_count": 3,
        "risk_score": 8.4,
        "issues": [
          { "type": "missing_h1", "severity": "critical", "message": "..." }
        ]
      }
    ],
    "backlinks_av_correlation": {
      "correlation_coefficient": 0.612,
      "days_with_data": 14,
      "velocity_total_30d": 23,
      "avi_data_points_30d": 18,
      "backlink_events_30d": 41,
      "observation": "Moderat positive Korrelation: Backlink-Velocity beeinflusst AVI."
    },
    "smart_todos": [
      {
        "priority_score": 84,
        "estimated_impact": "medium",
        "title": "Page-Issues fixen die Top-Ranking gefährden",
        "why": "URL …/best-crm rankt für \"best crm\" auf Position 5 — hat aber 7 Site-Audit-Issues (missing_h1, ...).",
        "reference_type": "tracking_keyword",
        "reference_id": 91,
        "url": "https://example.com/best-crm",
        "keyword": "best crm",
        "position": 5,
        "risk_score": 8.4
      }
    ]
  }
}

Status-Codes: 200 (Erfolg), 403 (Cross-Team / Cross-Project), 404 (Project nicht gefunden).

Beispiele (curl)

Wizard-Flow komplett über API

# 1) Analyse starten
RESP=$(curl -s -X POST $BASE/tracking-projects/analyze \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"mode":"domain","domain":"example.com","language":"de","country":"DE"}')
PID=$(echo $RESP | jq -r .project_id)

# 2) Polling bis completed
while [ "$(curl -s $BASE/tracking-projects/$PID/analysis-status \
  -H "Authorization: Bearer $TOKEN" | jq -r .analysis_status)" != "completed" ]; do
  sleep 3
done

# 3) Atomic Aktivierung
curl -X POST $BASE/tracking-projects/$PID/activate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "keywords":["best crm","crm software"],
    "competitors":[{"domain":"hubspot.com"}],
    "prompts":[{"prompt":"What is the best CRM?","category":"recommendation"}],
    "platforms":["chatgpt","perplexity"],
    "frequency":"weekly",
    "with_search":true,
    "reality_check_enabled":true
  }'

Keyword Explorer mit allen Daten

curl "$BASE/explorer/176007?include=related,questions" \
  -H "Authorization: Bearer $TOKEN"
# returns: keyword, search_volume, kd_score, parent_topic, traffic_potential,
# serp_urls, monthly_searches[12], related[90], questions[11], cache_hit

Article generieren + publishen

# Generate
curl -X POST $BASE/articles/$ART/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"keyword":"AI coding tools","article_type":"blog","target_length":1500}'

# Publish to WordPress (CMS-ID 1 vorausgesetzt)
curl -X POST $BASE/articles/$ART/publish \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"cms_integration_id":1}'

Cited-Sources Outreach

# Liste mit Filter
curl "$BASE/tracking-projects/$PID/cited-sources?outreach_status=neu" \
  -H "Authorization: Bearer $TOKEN"

# Status updaten
curl -X PATCH $BASE/tracking-projects/$PID/cited-sources/$SID \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"outreach_status":"anfrage_gestellt","notes":"E-Mail an redaktion@..."}'

# CSV-Export
curl "$BASE/tracking-projects/$PID/cited-sources/export?from=2026-01-01" \
  -H "Authorization: Bearer $TOKEN" -o sources.csv

Konventionen

• Async Jobs: Endpoints mit credits:N und/oder Job-Dispatch geben 202 Accepted mit Job-ID. Polling via Detail-Endpoint bis processing_status == 'ready'.
• Cache-Bust: Endpoints die intern cachen unterstützen ?cache=false (z.B. Explorer). 50 Credits, einmal gebucht vom Job vor dem Anbieter-Abruf, erstattet bei endgültigem Fehlschlag.
• Filter via Query: ?from=&to=&status=&platform=&search=&sort=&limit=&page=.
• Pagination: ?per_page=N&page=N. Response: {data:[], meta:{total, per_page, current_page, last_page}}.
• Includes: Wo unterstützt: ?include=related,questions (kommagetrennt) inlined Sub-Resources statt separater Roundtrips.

Routes-Generierung

Diese Datei spiegelt routes/api.php. Die maschinenlesbare SSOT der /v1-Route-Liste ist docs/API_ROUTES.generated.json — pro Endpoint method, uri (doc-Stil, ohne api-Prefix), name, action (Controller@method | Closure) und der aus der Middleware geparste credits + credits_mode (gate = credits:N, auto = credits-auto:N). Sortiert nach (uri, method), diff-stabil.

# Manifest (neu) generieren — nach jeder Route-Änderung ausführen + committen:
php artisan api:generate

# CI-Gate: prüft (ohne zu schreiben), ob das committete Manifest aktuell ist.
# Exit 1 + Diff-Summary bei Drift:
php artisan api:generate --check

# Schnellzählung der Live-/v1-Endpoints (Fallback):
php artisan route:list | grep "api/v1" | wc -l

Quelle: App\Services\Api\RouteIntrospector (spiegelt exakt ApiDocsController::countV1Endpoints()). Der Parity-Test tests/Feature/Docs/ApiDocParityTest.php erzwingt: (1) Introspector-Count == Controller-Count, (2) committetes Manifest aktuell (sonst „Run php artisan api:generate"), (3) jede /v1-Route ist in dieser Datei dokumentiert ODER auf der expliziten KNOWN_UNDOCUMENTED-Baseline (fängt neue undokumentierte Routen), (4) jede in dieser Datei genannte /v1-Pfad-Referenz löst auf eine echte Route auf, (5) Modul-Doc-Freshness (README-Link↔Datei-Parität + Soft-Check der /api/v1-Referenzen in docs/modules/*.md).

Frontend-Doku-Link

Live-Tabellen mit Beispielen: https://rankion.ai/settings/api-documentation

Chat Shares

Public-share API for AI chat sessions. Owner creates a share link from /api/v1/chat-shares, recipient views it via /share/{token} (public, noindex). All endpoints require auth:sanctum and team-scoping.

POST /v1/chat-shares

Body:

• session_id (required, integer): id of an AiChatSession owned by the authenticated user
• title (optional, string)
• expires_at (optional, ISO datetime, must be future)
• password (optional, string min 4)
• max_views (optional, integer min 1)
• Content toggles (optional, boolean):
  • show_user_messages (default true)
  • show_assistant_messages (default true)
  • show_tool_results (default false — recipients see only inputs+outputs, not the tool-call cards)
  • show_reasoning_steps (default false)
  • show_uploaded_files (default true)
  • At least ONE toggle must be true, else 422.

Response 201:

{
  "data": {
    "id": 1, "token": "<40 chars>",
    "url": "https://rankion.ai/share/<token>",
    "title": "...", "session_id": 42,
    "expires_at": "...", "frozen_at": null,
    "has_password": false, "max_views": null,
    "view_count": 0, "unique_viewer_count": 0,
    "last_viewed_at": null, "revoked_at": null,
    "status": "active",
    "show_user_messages": true,
    "created_at": "..."
  }
}

PATCH /v1/chat-shares/{id}

Same fields as POST plus freeze: bool (true = freeze content snapshot, false = back to live).

DELETE /v1/chat-shares/{id}

Soft revoke. Sets revoked_at. Public access returns 410. Row stays in DB until daily prune job (90 days post-revoke by default, configurable via CHAT_SHARES_RETENTION_DAYS).

Public route (NOT exposed via API)

GET /share/{token} — public, no auth, returns HTML. noindex enforced via meta + X-Robots-Tag header + robots.txt disallow. POST /share/{token}/unlock — password-form submission; throttle 5/min. Sets path-scoped httpOnly cookie on success. GET /share/{token}/print — clean print-CSS variant of the share view.

Agentic Plans

Read-only API for the agentic-superpowers Brainstorm → Plan → Execute pipeline. Plans are created/mutated EXCLUSIVELY by the master agent's pipeline tools (build_plan, complete_step, fail_step, skip_step, complete_plan, clarify_intent); the HTTP API exposes only inspection. All endpoints require auth:sanctum and team-scoping (Policy: view only — no update/delete exposed).

Plan response shape

{
  "data": {
    "id": 12, "session_id": 42, "goal": "Konkurrenz-Analyse example.com",
    "brainstorm_summary": null, "strategy": "linear",
    "status": "executing",
    "current_step_id": 35,
    "total_steps": 4, "completed_steps": 1, "failed_steps": 0,
    "started_at": "2026-05-01T08:30:00Z", "completed_at": null,
    "total_tool_calls": 9, "total_credits_used": 5,
    "created_at": "2026-05-01T08:29:55Z"
  }
}

Step response shape

{
  "data": [
    {
      "id": 35, "step_index": 0,
      "label": "Top-10 SERP-Konkurrenten ermitteln",
      "description": "...",
      "complexity": "trivial", "assigned_agent": null,
      "status": "completed", "retry_count": 0, "last_error": null,
      "output_summary": "10 Konkurrenten: ahrefs.com, semrush.com, ...",
      "output_data": { "competitors": ["ahrefs.com", "..."] },
      "tool_calls_made": 1, "credits_used": 1, "latency_ms": 3120,
      "subagent_session_id": null,
      "started_at": "...", "completed_at": "..."
    }
  ]
}

status values: pending | in_progress | completed | failed | skipped (steps); planning | executing | completed | failed | aborted (plans). assigned_agent values: null (master itself) | master | analyze | explore | research | action (Subagent-Persona).

📜 OpenAPI 3.1 Spec + Error-Code-Vokabular (Subsystem D)

Maschinenlesbarer Vertrag für Subsystem A + C — fixed 2026-05-09.

GET /api/v1/openapi.yaml

OpenAPI 3.1.0 Spec (public, kein Auth nötig). 5-min CDN-Cache. Generiert TypeScript/Python/PHP-SDKs aus z.B. openapi-generator-cli:

npx @openapitools/openapi-generator-cli generate \
  -i https://rankion.ai/api/v1/openapi.yaml \
  -g typescript-fetch \
  -o ./rankion-sdk-ts

Schema-Coverage:

• Subsystem A — /grounding/analyze, /audits/{id}, /audits, /batch, /batches/{id}, /batches/{id}/results.ndjson, /sitemap-audit
• Subsystem B — /content-optimizer/{id} (canonical + alias)
• Subsystem C — /agentic/chat, /agentic/sessions/{session}
• Reusable schemas: GroundingAudit, GroundingBatch, Finding, Tier, StructuredError, AgenticChatRequest/Response, AgenticSessionStatus

Andere Endpoints sind weiterhin nur in dieser Markdown-Reference dokumentiert; eine vollständige OpenAPI-Export-Phase ist auf der Roadmap.

Error-Code-Vokabular (kanonisch)

Alle code Werte aus dem error: {code, ...} Envelope (Subsystem A + C):

Rate-Limit-Headers

Jeder Endpoint mit throttle:N,M Middleware liefert auf erfolgreiche Responses:

• X-RateLimit-Limit: N (Anfragen pro Window)
• X-RateLimit-Remaining: <int> (verbleibend im aktuellen Window)
• X-RateLimit-Reset: <epoch> (Unix-Timestamp wann Counter resettet)

Bei 429: zusätzlich Retry-After: <seconds>. Counters per Sanctum-Token, nicht per IP.

Throttle-Werte pro Endpoint stehen in der Endpoint-Tabelle der jeweiligen Sektion (oben). Aktuelle Werte:

• /grounding/analyze: 30/min · /grounding/batch, /sitemap-audit: 5/min · /grounding/audits/{id}, /batches/{id}: 120/min · /grounding/audits (Liste): 60/min · /grounding/batches/{id}/results.ndjson: 30/min · /agentic/sessions/{session}: 120/min · /agentic/chat: kein expliziter Throttle (Cap durch interne max_iterations + Anthropic-Token-Limits).

🤖 Master-Agent Härtung (Subsystem C)

Drei Härtungen am /api/v1/agentic/chat Flow für robustere programmatische Caller — fixed 2026-05-09.

P1.4 — Strukturierter context_overflow Error

Wenn der Agent das 1M-Token-Kontext-Limit hittet, returnt /agentic/chat jetzt HTTP 422 mit strukturiertem Error-Envelope statt 200+German-Text:

{
  "session_id": 1201,
  "error": {
    "code": "context_overflow",
    "limit_tokens": 1000000,
    "used_tokens": 1042000,
    "suggested_action": "split_request",
    "max_urls_per_call": 1
  },
  "text": "⚠️ Diese Anfrage ist zu komplex geworden …"
}

Programmatischer Retry ohne String-Matching auf Deutsch. Bei Anthropic-API-Errors (5xx upstream) → HTTP 502 mit error.code = "anthropic_api_error".

P1.5 — tool_policy im Request

Restriktiere welche Tools der Master-Agent in einem Turn nutzen darf — ideal für Audit-Loops, die nur 1-Tool-Calls wollen ohne Token-Blow:

{
  "message": "Audit https://example.com",
  "tool_policy": {
    "allow": ["analyze_grounding_page"],
    "deny": ["web_scrape", "extract_from_urls"],
    "max_tool_calls": 1
  }
}

Server-side Enforcement: gesperrte Tools liefern Tool-Result {success:false, error:"tool X blocked by tool_policy.deny", policy_blocked:true} — der Agent ignoriert sie und liefert ein Teil-Resultat statt das Limit zu sprengen.

P1.6 — Async-Default + Polling-Endpoint

/agentic/chat blockiert standardmäßig NICHT mehr bis zum finalen Resume. Wenn der Agent mid-turn wait_and_recheck ausgelöst hat, returnt der Endpoint HTTP 202 sofort:

{
  "session_id": 1201,
  "agentic_status": "waiting",
  "eta_seconds": 120,
  "poll_url": "/api/v1/agentic/sessions/1201",
  "resumed": false,
  "text": "⏳ Ich warte auf Hintergrund-Daten…"
}

Caller polled dann GET /api/v1/agentic/sessions/{id}:

{
  "session_id": 1201,
  "agentic_status": "completed",
  "message_id": 4567,
  "text": "Audit fertig: Score 75/100…",
  "last_message_at": "2026-05-09T14:32:01+00:00",
  "is_terminal": true
}

agentic_status: null (idle) | running | waiting | awaiting_user | failed | completed. is_terminal=true heißt: keine weitere Hintergrund-Arbeit pending (awaiting_user ist NICHT terminal — es wartet auf eine User-Antwort).

Wartezustand mit Runde (Plan #305, 2026-09-22). POST /agentic/chat (202) und GET /agentic/sessions/{id} tragen zusätzlich:

{
  "waiting": { "until": "2026-09-22T08:31:10+02:00", "reason": "Optimizer-Run läuft", "round": 2, "max_rounds": 3 },
  "wait_limit_reached": false
}

waiting ist ein Objekt, solange die Session auf einen Hintergrundlauf wartet (agentic_status='waiting'), sonst null. round zählt die Warte-Runden in Folge (jede Runde ist ein eigener, berechneter Zug), max_rounds die Obergrenze (config('agentic.wait_and_recheck.max_consecutive_rounds'), Vorgabe 3). Ist sie erreicht, endet der Zug mit einer Standmeldung und wait_limit_reached=true — der Chat wartet nicht weiter, der Caller holt das Ergebnis über den Link im Text oder stellt die Frage später erneut.

Opt-in legacy blocking: POST /agentic/chat?wait_for_final=true → server polled bis 480s und liefert das finale Result inline (alte Verhalten).

Rückfragen / Bestätigungen über die API (ask_user_question, 2026-06-10)

Ruft der Agent das ask_user_question-Tool (oder ein Plan-Confirmation-Gate), pausiert die Loop mit agentic_status='awaiting_user'. POST /agentic/chat, GET /agentic/sessions/{id} und POST /agentic/sessions/{id}/answer-question hängen dann zusätzlich an:

{
  "agentic_status": "awaiting_user",
  "is_terminal": false,
  "awaiting_user": true,
  "pending_question": "Soll ich den teuren Voll-Pull starten (120 Credits)?",
  "pending_question_options": [
    {"label": "Ja, starten (Empfohlen)", "description": "Kostet 120 Credits"},
    {"label": "Nein, abbrechen", "description": ""}
  ],
  "answer_url": "/api/v1/agentic/sessions/1201/answer-question"
}

Antworten: POST /agentic/sessions/{id}/answer-question mit { "option_label": "Ja, starten (Empfohlen)" } → resumed die Loop synchron (Response-Shape = /agentic/chat; enthält erneut die awaiting_user-Felder, falls direkt eine Folge-Frage kommt). Damit funktionieren Rückfragen + Aktions-Bestätigungen via API genauso wie im Chat-UI. Die Entscheidung WANN der Agent fragt ist advisory (Tool-Beschreibung empfiehlt es bei >50-Credit-Ops) — kein erzwungener Gate.

🧭 Grounding Audit Pipeline (Subsystem A)

Async-Pipeline für LLM-Citation-Readiness-Audits über öffentliche URLs. Single + Bulk + Sitemap mit NDJSON-Stream und HMAC-signierten Webhook-Callbacks.

Frameworks:

• Grounding Page Standard v1.5 (Hanns Kronenberg, https://groundingpage.com/spec/de/) — 22 Page- + 4 Site-Root-Checks
• Google E-E-A-T (Search Quality Rater Guidelines + Helpful Content) — aktuell nur Master-Agent-Pfad, REST-Pipeline-Stub
• Google People-First + AI-Features (developers.google.com) — aktuell nur Master-Agent-Pfad, REST-Pipeline-Stub

Tier-Schwellen

Findings-Schema

Jedes Audit liefert findings[] mit Objekten: {id, severity (critical|high|medium|low|info), framework (v1.5|eeat|people-first), title, description, fix:{type, action, details}, spec_url}. Zusätzlich raw_text (Markdown) für UI-Render.

Webhook-Verifikation

Server POSTet zu callback_url mit Header X-Rankion-Signature: sha256=<hex> (HMAC-SHA256 über Body, Key = callback_secret) + X-Rankion-Webhook-Id: <uuid>. 4 Retries (60/300/1800/7200s) bei 5xx oder 429. Verifikation:

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $callbackSecret);
hash_equals($expected, $request->header('X-Rankion-Signature'));

Error-Codes (Subsystem A)

Beispiel — Single-URL Audit:

ID=$(curl -sX POST -H "Authorization: Bearer $RANKION_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"url":"https://example.com","frameworks":["v1.5"]}' \
     https://rankion.ai/api/v1/grounding/analyze | jq -r .audit_id)

# Poll
sleep 30
curl -H "Authorization: Bearer $RANKION_API_TOKEN" \
     https://rankion.ai/api/v1/grounding/audits/$ID

Beispiel — Sitemap-Batch:

curl -X POST -H "Authorization: Bearer $RANKION_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"sitemap_url":"https://example.com/sitemap.xml","filter":{"path_contains":"/blog","limit":50},"callback_url":"https://my-app/hook"}' \
     https://rankion.ai/api/v1/grounding/sitemap-audit

Knowledge-Base intern: docs/knowledge/grounding-pages-geo.md. Modul-Doku: docs/modules/grounding-audit.md.

🧬 GEO Criteria Catalog

Read-only Discovery-Endpoint für die GEO-/LLM-Citation-Kriterien — die Single Source of Truth (App\Support\Geo\GeoCriteriaRegistry), die den Grounding-Audit, den GEO-Content-Score, die Generierungs-Prompts (ContentGeneratorService — live) und die Off-Page-/Demand-Achse (OffPageReadinessScorer) speist. Lässt GEO-Optimizer-Agenten entdecken, welche Signale Rankion prüft, mit welchem Engine-Signal, welcher Evidenz-Stufe und an welchen Oberflächen (audit/score/prompt/offpage). Synchron, 0 Credits, kein Polling.

Response-Felder (/v1/geo-criteria):

• id — stabile Kriterien-ID, identisch mit der Grounding-Finding-ID bzw. dem GEO-Score-Breakdown-Key (gp.h1.entity_only, geo.evidence.citation_density, geo.offpage.brand_demand, …).
• engine_signal — referenziertes Engine-Capability-Matrix-Signal (config/engines.php).
• dimension — technical (Signal indexability/crawlability) oder content. Abgeleitet, nie driftend.
• evidence_tier — A/B Default-Hint. Der wirksame Tier eines konkreten Findings kommt aus /v1/grounding/audits/{id} (Laufzeit-Auflösung über die Engine Capability Matrix).
• shapes[] — Oberflächen, an denen das Kriterium teilnimmt: audit (Page- oder Site-Root-Detektor), score, prompt, offpage (Demand-Achse, geo.offpage.*).

Off-Page-Readiness (Demand-Achse)

GET /v1/tracking-projects/{id}/off-page-readiness — aggregierter Off-Page-Score eines Tracking-Projekts (gewichtetes Mittel über die data_available-Signale). Team-scoped: Fremd-Team → 403, unbekannte ID → 404. 0 Credits.

{
  "score": 87,
  "data_available": true,
  "components": {
    "geo.offpage.brand_demand":        { "score": 100, "data_available": true, "meta": { "brand_keyword": "rankion", "search_volume": 12000 }, "weight": 25 },
    "geo.offpage.third_party_mentions": { "score": 70,  "data_available": true, "meta": { "third_party_count_90d": 30, "window_days": 90 }, "weight": 20 },
    "geo.offpage.source_affinity":     { "score": 100, "data_available": true, "meta": { "distinct_third_party_types": 3, "has_wiki": true }, "weight": 15 }
  },
  "meta": { "tracking_project_id": 17, "credits": 0 }
}

• score ist int|null — null ⇒ noch keine Daten, NICHT 0. data_available unterscheidet beide Fälle; jedes components.* trägt sein eigenes data_available + meta.reason.
• Voraussetzungen für non-null Daten: brand_demand braucht brand_name + passendes Tracking-Keyword mit search_volume; third_party_mentions braucht aktivierten Community-Monitor (CommunityProject am selben Project); source_affinity braucht Citation-Historie (cited_sources).
• ID-Bridge: Der Scorer löst community_project_id (Drittseiten-Mentions) vs. tracking_project_id (Brand-Demand + Quellen-Affinität) pro Faktor auf — via CommunityProject.project_id == TrackingProject.project_id.
• v2-Envelope (Accept: application/vnd.rankion.v2+json): {data: {score, data_available, components}, meta}.

Read-only: Detector-/Factor-Objekte werden nie serialisiert — nur skalare Metadaten. Den Katalog einmal ziehen, dann damit Grounding-Audit (/v1/grounding/analyze), Content-Optimizer bzw. Off-Page-Readiness ansteuern.

Skill-Manifeste: grounding.geo-criteria, tracking.off-page-readiness. Modul-Doku: docs/modules/geo-criteria-catalog.md.

📚 Wiki

Public + internal wiki content. Markdown-Files in docs/wiki/ werden via php artisan wiki:sync (auto bei jedem Deploy) in die DB gespiegelt. Slug-Hierarchie via /: modules/backlinks. Wiki-interne Links via [[slug]] oder [[slug|Anzeigetext]].

Public-Reader: https://rankion.ai/wiki/{slug} — server-rendered HTML, Sidebar+TOC, /-Shortcut für Search-Focus. visibility: internal → 401 für anonyme User.

Master-Agent-Integration: query_wiki(query) Master-Tool returnt Top-3 mit vollen URLs — Trigger bei "wie geht X", "wie aktiviere ich Y", "was ist Z?".

🧠 Deep Insights (LLM Data Mining)

Tiefenanalyse über alle 6 Mining-Schichten (Atomisierung → Quellenscan → Cross-Pattern → Faktencheck → Forecast → Action). Liefert pro Projekt einen 9-Sektionen-Report (Executive Summary, Faktenfehler, Konsens-Narrative, Persona-Lücken, Outreach Top-50, Wettbewerbs-Co-Occurrence, Frühwarn-Radar, Source-Whitelist, 6-Wochen-Forecast). Voraussetzung: Atomisierung läuft (Layer 1 backfill); für Faktencheck zusätzlich Truth-Source mit human_reviewed=true.

Alle Endpoints Sanctum-authed mit Team-Scope-Check (tracking_projects.team_id === user.currentTeam->id, sonst 403).

Wöchentlicher Insights-Report: Jeden Sonntag 18:00 wird für alle Projekte der PDF-Report generiert und mit Highlights-Summary an den Team-Owner gemailt.

Live-Dashboard: https://rankion.ai/ai-visibility/{id}/insights — interaktive 9-Tab-Ansicht des gesamten Payloads.

🧬 Citation Causality (CCE)

Layer-7-Engine über tracking_cited_sources: extrahiert pro Citation strukturierte Dimensionen (Content-Format, Schema-Types, E-E-A-T-Signale, Pricing/FAQ-Indikatoren, Domain-Authority), vergleicht gegen Google-SERP-Top-10-Counterfactuals und produziert Lift-Scores als Hebel-Empfehlungen. Drei Tiers: per Project (Tier 1), Account (Tier 2), Admin Global (Tier 3).