API

Content-Audits-API

Komplette Site auditen — Pages, Empfehlungen, JSON-Export.

Die Content-Audits-API führt einen vollständigen Site-Audit durch: crawlt eine Domain, scoret jede Page nach Content-Qualität, Keyword-Coverage, technischen SEO-Signalen und liefert priorisierte Empfehlungen pro URL. Im Gegensatz zum Page Deep Audit (Single-URL, Vision-basiert) deckt der Content-Audit die ganze Site flächig ab. Alle Endpoints liegen unter /v1/... und sind team-scoped.

Modul-Kontext: Content Audit.

Endpoints

Method	Endpoint	Beschreibung	Credits
GET	`/v1/content-audits`	Alle Audits des Teams (paginated)	—
POST	`/v1/content-audits`	Neuen Audit starten — Body: `{project_id, max_pages?, exclude_paths?}` → 202	10
GET	`/v1/content-audits/{id}`	Audit-Header + Aggregat-Scores + Page-Liste (paginated)	—
GET	`/v1/content-audits/{id}/pages`	Alle Pages des Audits (`?score_lt=&category=&sort=`)	—
GET	`/v1/content-audits/{id}/export`	JSON-Export des kompletten Audits inklusive aller Pages und Empfehlungen	—
GET	`/v1/content-audit-pages/{id}`	Einzelne Page mit Empfehlungen, Score-Breakdown, Issue-Liste	—
PATCH	`/v1/content-audit-pages/{id}/solved`	Page als gelöst markieren — Body: `{solved:bool, note?}`	—

Audit starten

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

curl -X POST "$BASE/content-audits" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "project_id":12,
    "max_pages":200,
    "exclude_paths":["/tag/","/author/","/wp-admin/"]
  }'

Response 202 Accepted:

{
  "id": 5,
  "status": "pending",
  "message": "Content audit dispatched"
}

Der Crawl läuft asynchron — Faustregel: 200 Pages ~ 5–8 Minuten. max_pages ist hart, der Crawler stoppt bei Erreichen.

Audit-Header

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

Response:

{
  "id": 5,
  "project_id": 12,
  "status": "completed",
  "started_at": "2026-04-30T10:12:00Z",
  "completed_at": "2026-04-30T10:18:42Z",
  "pages_crawled": 187,
  "pages_failed": 3,
  "avg_score": 64,
  "score_distribution": {
    "0-40": 12,
    "40-60": 38,
    "60-80": 91,
    "80-100": 46
  },
  "top_issues": [
    { "category": "missing_meta_description", "count": 47 },
    { "category": "thin_content", "count": 23 }
  ],
  "credits_used": 10
}

Pages mit Filter

# Alle Pages mit Score < 40 (kritisch)
curl "$BASE/content-audits/$ID/pages?score_lt=40&sort=score_asc" \
  -H "Authorization: Bearer $TOKEN"

# Alle Pages mit Issue-Kategorie "thin_content"
curl "$BASE/content-audits/$ID/pages?category=thin_content" \
  -H "Authorization: Bearer $TOKEN"

Page-Detail

curl "$BASE/content-audit-pages/$PAGE_ID" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "id": 412,
  "audit_id": 5,
  "url": "https://example.com/blog/old-post",
  "score": 38,
  "score_breakdown": {
    "content_quality": 42,
    "keyword_coverage": 28,
    "technical_seo": 51,
    "freshness": 22
  },
  "issues": [
    {
      "category": "thin_content",
      "severity": "high",
      "message": "Nur 320 Wörter — Top-Rankings für dieses Keyword haben Ø 1.800",
      "fix_suggestion": "Auf 1.500+ Wörter erweitern, FAQ-Sektion ergänzen"
    }
  ],
  "solved": false
}

Pages als gelöst markieren

Nachdem du eine Page gefixt hast (z.B. via Artikel-API → optimize), markiere sie als gelöst — sie verschwindet dann aus offenen Issue-Listen, bleibt aber im Audit-Verlauf.

curl -X PATCH "$BASE/content-audit-pages/$PAGE_ID/solved" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"solved":true,"note":"Inhalt erweitert auf 1850 Wörter, FAQ ergänzt."}'

JSON-Export

Für externe Reports oder Backup:

curl "$BASE/content-audits/$ID/export" \
  -H "Authorization: Bearer $TOKEN" -o audit-5.json

Der Export enthält alle Pages mit kompletten Empfehlungen und Score-Breakdowns — geeignet als Input für Excel-Pivot oder als Briefing-Material.

Komplettes Beispiel: Audit → kritische Pages → Optimieren

PID=12

# 1) Audit starten
ID=$(curl -s -X POST "$BASE/content-audits" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"project_id":'$PID',"max_pages":200}' | jq -r .id)

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

# 3) Top-10 kritische Pages
curl -s "$BASE/content-audits/$ID/pages?score_lt=40&sort=score_asc&per_page=10" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '.data[] | "\(.score)\t\(.url)"'

# 4) Eine Page durch den Content-Optimizer fahren
URL="https://example.com/blog/old-post"
curl -s -X POST "$BASE/content-optimizer/analyze" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"url\":\"$URL\",\"keyword\":\"…\",\"project_id\":$PID}"

Hinweise & Pitfalls

max_pages schützt vor Credit-Burst. Default ist konservativ — bei großen Sites bewusst hochsetzen, sonst werden nur Top-Level-Pages gecrawlt.
exclude_paths ist substring-basiert. /tag/ matcht alle URLs mit /tag/ im Path.
Re-Audit überschreibt nicht. Jeder Audit ist ein eigener Snapshot. Vergleich = zwei Audits laufen lassen, beide IDs exportieren, diff'en.
Solved markieren ist optional. Hilft aber bei Re-Audit-Comparisons (Solved-Pages werden visuell als "ehemals kritisch" markiert).

Verwandt: Projekte-API · Content-Optimizer-API · Content Audit · Page Deep Audit.

Letzte Aktualisierung: 1. Mai 2026