API

AI-Visibility-Tracking-API

Tracking-Projekte erstellen, Runs starten, Scores plus Cited Sources abfragen.

Die Tracking-API ist der API-Layer rund um das Modul AI Visibility Tracking — sie misst, wie deine Marke in ChatGPT, Perplexity, Claude, Gemini und Co. erscheint. Alle Endpoints liegen unter /v1/... und sind team-scoped via auth:sanctum.

UI-Kontext: AI-Visibility tracken · Modul-Doku: AI Visibility Tracking.

Projekte (Wizard + Runtime)

Tracking-Projekte werden über einen 5-stufigen Wizard angelegt: Analyse dispatchen → Status pollen → Aktivieren → Run starten → Scores lesen. Der Wizard ist atomic — die activate-Aktion legt Keywords, Prompts, Competitors gemeinsam an und schaltet das Projekt scharf.

Method	Endpoint	Beschreibung	Credits
GET	`/v1/tracking-projects`	Alle Team-Projekte	—
POST	`/v1/tracking-projects/analyze`	Wizard Step 1+2: Domain/Keyword analysieren — Body: `{mode:"domain"\|"keyword", domain?, keyword?, name?, language?, country?}` → 202 + `project_id`	—
GET	`/v1/tracking-projects/{id}`	Detail mit KPIs	—
PUT	`/v1/tracking-projects/{id}`	Settings: `{name?, brand_name?, brand_aliases[], tracking_frequency?, llm_platforms[], track_aio?, reality_check_enabled?}`	—
GET	`/v1/tracking-projects/{id}/analysis-status`	Wizard-Polling: `{analysis_status, analysis_phase, suggested_keywords, suggested_competitors, suggested_prompts}`	—
POST	`/v1/tracking-projects/{id}/activate`	Wizard Step 5 atomic — Body: `{keywords[], competitors[], prompts[], platforms[], frequency, with_search?, reality_check_enabled?, personas[]}`	—
POST	`/v1/tracking-projects/{id}/run`	Tracking-Run starten (async)	—
GET	`/v1/tracking-projects/{id}/runs`	Run-Historie (`?limit=&offset=`)	—

Keywords + Prompts

Method	Endpoint	Beschreibung
GET	`/v1/tracking-projects/{id}/keywords`	`?active_only=true`
POST	`/v1/tracking-projects/{id}/keywords`	Body: `{keyword, language?, country?, is_active?}`
PUT/DELETE	`/v1/tracking-keywords/{id}`	Update / Löschen
GET	`/v1/tracking-projects/{id}/prompts`	Liste
POST	`/v1/tracking-projects/{id}/prompts`	Body: `{prompt_text, prompt_category?, persona_label?, commercial_intent?}`
PUT/DELETE	`/v1/tracking-prompts/{id}`	Update / Löschen
POST	`/v1/tracking-projects/{id}/prompts/import`	CSV/Excel-Bulk — multipart `file`, optional `mapping[col]=index`

Cited Sources (Outreach-Pipeline)

Method	Endpoint	Beschreibung
GET	`/v1/tracking-projects/{id}/cited-sources`	`?domain=&outreach_status=&is_own_domain=`
GET	`/v1/tracking-projects/{id}/cited-sources/export`	CSV-Stream — `?from=&to=&status=&platform=&search=&sort=`
POST	`/v1/tracking-projects/{id}/cited-sources/analyze`	Citation-Analyse dispatchen — Body optional `{source_ids:[]}` → 202
PATCH	`/v1/tracking-projects/{id}/cited-sources/{source_id}`	Body: `{outreach_status?, notes?}` (`neu`, `anfrage_gestellt`, `verlinkt`, `abgelehnt`, `ignoriert`)

Insights & Scores

Method	Endpoint	Beschreibung	Credits
GET	`/v1/tracking-projects/{id}/scores`	Score-Historie (`?from=&to=`)	—
GET	`/v1/tracking-projects/{id}/platform-breakdown`	Score je LLM-Plattform	—
GET	`/v1/tracking-projects/{id}/insights/low-hanging-fruit`	`?days=30&min_possibility=60&limit=5`	—
GET	`/v1/tracking-projects/{id}/insights/platform-gap`	`?days=30`	—
POST	`/v1/tracking-projects/{id}/insights/platform-gap/{platform}/diagnose`	Async Root-Cause	1
GET	`/v1/tracking-projects/{id}/insights/potential-hero`	Prompts mit Hero-Potenzial	—
POST	`/v1/tracking-projects/{id}/prompts/{prompt}/generate-brief`	Content-Brief via Claude	3
POST	`/v1/tracking-projects/{id}/brand-aliases`	Body: `{alias}`	—

Reality Check (AVI)

Der AI Visibility Index aggregiert 6 Dimensionen (Awareness, Recommendation, Trust, Coverage, Sentiment, Competitive-Edge) zu einem Score 0–100.

Method	Endpoint	Beschreibung
GET	`/v1/tracking-projects/{id}/avi`	Neuester AVI mit Tier (red/yellow/green) + Recommendations
GET	`/v1/tracking-projects/{id}/dimensions`	6-Dim-Scores pro Plattform
POST	`/v1/tracking-projects/{id}/reality-check-report`	PDF-Generierung async
GET	`/v1/tracking-projects/{id}/reality-check-report/status`	`{status, progress?, download_url?}`

Komplettes Beispiel: Wizard → Run → Scores

TOKEN="$RANKION_API_TOKEN"
BASE="https://rankion.ai/api/v1"

# 1) Analyse starten
PID=$(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"}' \
  | 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 Activate
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
  }'

# 4) Ersten Run dispatchen
curl -X POST "$BASE/tracking-projects/$PID/run" \
  -H "Authorization: Bearer $TOKEN"

# 5) Scores lesen (wenn Run completed)
curl "$BASE/tracking-projects/$PID/scores?from=2026-01-01" \
  -H "Authorization: Bearer $TOKEN"

# 6) AVI + Recommendations
curl "$BASE/tracking-projects/$PID/avi" \
  -H "Authorization: Bearer $TOKEN"

Hinweise & Pitfalls

Activate ist atomic. Erst nach activate ist status=active und Runs lassen sich starten — vorher 409.
AVI braucht einen Run. GET /avi ohne abgeschlossenen Run liefert 404.
Cited-Source-Analyse standardmäßig batched. Ohne source_ids werden alle bisher unanalyzed Sources verarbeitet.
Reality-Check-Report ist optional. Nur dispatchen wenn reality_check_enabled=true im Projekt — sonst Validation-Error.

Verwandt: Projekte-API · Credits · AI Visibility Tracking · AI-Visibility tracken.

Letzte Aktualisierung: 1. Mai 2026