Content-Optimizer-API

Der Content Optimizer scrapet eine bestehende URL, analysiert SEO + GEO-Signale gegen das Ziel-Keyword und liefert 15–25 konkrete Verbesserungsvorschläge — von Headline-Rewrites bis FAQ-Schema-Empfehlungen. Über apply lassen sich akzeptierte Vorschläge direkt in einen optimierten Artikel materialisieren.

Modul-Kontext: Content Optimizer · Walkthrough: Content optimieren.

Endpoints

Analyse starten

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

curl -X POST "$BASE/content-optimizer/analyze" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "url":"https://example.com/blog/ai-coding",
    "keyword":"ai coding tools",
    "project_id":12,
    "language":"en"
  }'

Antwort 202 Accepted:

{
  "id": 47,
  "status": "pending",
  "message": "Analysis dispatched"
}

Der Job läuft 10–20 Sekunden: ScraperAPI holt das HTML, Claude Sonnet 4.5 vergleicht es gegen Top-10-SERP für das Keyword und gegen die GEO-Heuristiken (Entity-Coverage, Citation-Worthiness, AI-Snippet-Tauglichkeit).

Detail abrufen

curl "$BASE/content-optimizer/$ID" \
  -H "Authorization: Bearer $TOKEN"

Response-Shape:

{
  "id": 47,
  "status": "completed",
  "url": "https://example.com/blog/ai-coding",
  "keyword": "ai coding tools",
  "scraped_word_count": 1240,
  "current_score": 62,
  "potential_score": 84,
  "suggestions": [
    {
      "id": 311,
      "category": "headline",
      "priority": "high",
      "title": "H1 enthält Keyword nicht prominent",
      "before": "Coding mit AI: ein Überblick",
      "after": "Die besten AI Coding Tools 2026 (mit Benchmarks)",
      "rationale": "Top-3-SERP-Ergebnisse haben das Keyword in den ersten 3 Wörtern."
    }
  ]
}

suggestions[] ist sortiert nach priority (high → low) und gruppierbar nach category (headline, meta, intro, faq, internal_links, entities, schema, structure, cta).

Vorschläge anwenden

Statt jeden Vorschlag manuell ins Source-CMS zurückzuspielen kannst du sie als optimierten Artikel in Rankion materialisieren — der entstehende Artikel landet im AI Content Editor und kann von dort über die Artikel-API gepublished werden.

curl -X POST "$BASE/content-optimizer/$ID/apply" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "suggestion_ids":[311, 312, 315, 318],
    "create_article":true
  }'

Response:

{
  "article_id": 92,
  "applied_count": 4,
  "score_before": 62,
  "score_after": 81
}

Komplettes Beispiel: Analyse → Top-Suggestions → Apply

PID=12

# 1) Analyse dispatchen
ID=$(curl -s -X POST "$BASE/content-optimizer/analyze" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/blog/ai-coding","keyword":"ai coding tools","project_id":'$PID'}' \
  | jq -r .id)

# 2) Pollen bis completed
while [ "$(curl -s "$BASE/content-optimizer/$ID" \
  -H "Authorization: Bearer $TOKEN" | jq -r .status)" != "completed" ]; do
  sleep 3
done

# 3) Top-5 high-priority Suggestions extrahieren
TOP=$(curl -s "$BASE/content-optimizer/$ID" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -c '[.suggestions[] | select(.priority=="high")][:5] | map(.id)')

# 4) Anwenden
curl -X POST "$BASE/content-optimizer/$ID/apply" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"suggestion_ids\":$TOP,\"create_article\":true}"

Hinweise & Pitfalls

• Analyze ist async. Auch wenn der Endpoint 200/202 zurückgibt — Vorschläge stehen erst nach Job-Abschluss. Polling-Intervall: 3–5 s.
• url muss öffentlich erreichbar sein. Hinter einem Login? → ScraperAPI failt → status="failed" mit Hinweis im error_message.
• Apply ist nicht idempotent. Mehrfaches Anwenden derselben Suggestion-IDs erstellt mehrere Artikel. Vorher prüfen ob article_id schon gesetzt ist.
• Keyword ist Pflicht. Ohne keyword keine SERP-Vergleichs-Basis → Validation-Error.

Verwandt: Artikel-API · Credits · Content Optimizer · Content optimieren.