Artikel-API

Die Artikel-API ist der meistgenutzte Teil der Rankion-API — ein einziger Artikel durchläuft typischerweise Anlegen → Generieren → Scoren → Optimieren → Publishen, optional plus Repurpose, Freshness-Check und Internal-Linking. Alle Endpoints liegen unter /v1/articles/... und sind team-scoped.

Volle Kontext-Doku zum Modul: AI Content Editor · Anleitung mit Screenshots: Erster Artikel.

CRUD

Generierung

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,
    "tone": "expert",
    "language": "de",
    "style_profile_id": 3,
    "content_goal_id": 2
  }'

Antwort 202 Accepted:

{
  "article_id": 88,
  "status": "pending",
  "message": "Generation dispatched"
}

Dann GET /v1/articles/{id} pollen bis processing_status == "ready". Standalone-Variante ohne Projekt: POST /v1/generate/article (gleiche Credits).

Scoring & Optimieren

Score-Antwort enthält Sub-Scores (Readability, Keyword-Coverage, Strukturanforderungen, GEO-Signale), eine Liste konkreter Verbesserungs-Vorschläge und einen Gesamt-Score 0–100.

Repurpose

Generiert kompakte Varianten für Social/Newsletter aus dem Original-Artikel.

Ohne format werden alle Formate generiert (gleicher Preis von 3 Credits). Mit format nur das angeforderte.

# Alle Formate
curl -X POST "$BASE/articles/$ART/repurpose" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{}'

# Nur LinkedIn
curl -X POST "$BASE/articles/$ART/repurpose" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"format":"linkedin"}'

Publish

Veröffentlicht den Artikel über eine konfigurierte CMS-Integration (WordPress, Shopify, custom REST-Adapter).

curl -X POST "$BASE/articles/$ART/publish" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"cms_integration_id":1}'

Response 202 mit Job-ID. Status danach via GET /v1/articles/{id} (cms_publish_status). Zweiter Publish-Call während ein Job in flight ist → 409 Conflict (verhindert Duplikate).

Versions

Jeder generative Schritt (Generate, Optimize, Restore) erzeugt eine immutable Version. Damit kannst du rollbacken oder vergleichen.

Freshness

Erkennt veraltete Statistiken/Jahreszahlen/Links und schlägt Updates vor — wichtig für SEO-Stabilität bei Evergreen-Inhalten.

Internal Linking

Komplettes Beispiel: Anlegen → Generieren → Scoren → Publishen

TOKEN="$RANKION_API_TOKEN"
BASE="https://rankion.ai/api/v1"
PID=12   # bestehendes Projekt

# 1) Stub anlegen
ART=$(curl -s -X POST "$BASE/projects/$PID/articles" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"AI Coding Tools 2026","status":"draft"}' \
  | jq -r .data.id)

# 2) Generierung starten (5 Credits, async)
curl -s -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,"language":"en"}'

# 3) Pollen bis ready
while [ "$(curl -s "$BASE/articles/$ART" \
  -H "Authorization: Bearer $TOKEN" | jq -r .data.processing_status)" != "ready" ]; do
  echo "Generating..."; sleep 5
done

# 4) Score rechnen
curl -s -X POST "$BASE/articles/$ART/score" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.scores'

# 5) Optional: Repurpose für LinkedIn
curl -s -X POST "$BASE/articles/$ART/repurpose" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"format":"linkedin"}'

# 6) Publishen via CMS-Integration ID 1
curl -s -X POST "$BASE/articles/$ART/publish" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"cms_integration_id":1}'

# 7) Publish-Status prüfen
curl -s "$BASE/articles/$ART" -H "Authorization: Bearer $TOKEN" \
  | jq '{cms_publish_status, public_url}'

Hinweise & Pitfalls

• Generate ist async. Auch wenn der Endpoint 200 zurückgibt — der Inhalt steht erst nach Job-Abschluss. Immer pollen.
• Score braucht Inhalt. POST /score ohne ausreichend content liefert eine Validation-Fehlermeldung statt einem nutzlosen 0-Score.
• Publish ist exclusive. Während ein Publish-Job läuft, kannst du nicht erneut publishen — 409. Erst Status checken.
• Versions sind unveränderlich. Restoring überschreibt nicht die alte Version, sondern legt eine neue Version mit altem Content an.

Verwandt: Projekte-API · Credits · AI Content Editor · Erster Artikel.