API Content Audits

L'API Content Audits effectue un audit complet de site : crawle un domaine, score chaque page selon la qualité de contenu, la couverture mot-clé, les signaux SEO techniques et fournit des recommandations priorisées par URL. Contrairement au Page Deep Audit (URL unique, basé Vision), le Content Audit couvre tout le site en surface. Tous les endpoints sont sous /v1/... et team-scoped.

Contexte du module : Content Audit.

Endpoints

Démarrer un audit

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/"]
  }'

Réponse 202 Accepted :

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

Le crawl tourne en async — règle empirique : 200 pages ~ 5 à 8 minutes. max_pages est strict, le crawler s'arrête à l'atteinte.

En-tête d'audit

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

Réponse :

{
  "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 avec filtre

# Toutes les pages avec score < 40 (critiques)
curl "$BASE/content-audits/$ID/pages?score_lt=40&sort=score_asc" \
  -H "Authorization: Bearer $TOKEN"

# Toutes les pages avec catégorie d'issue "thin_content"
curl "$BASE/content-audits/$ID/pages?category=thin_content" \
  -H "Authorization: Bearer $TOKEN"

Détail de page

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

Réponse :

{
  "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
}

Marquer des pages comme résolues

Après avoir corrigé une page (par ex. via API Articles → optimize), marque-la comme résolue — elle disparaît alors des listes d'issues ouvertes mais reste dans l'historique de l'audit.

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."}'

Export JSON

Pour des rapports externes ou un backup :

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

L'export contient toutes les pages avec leurs recommandations complètes et ventilations de score — adapté comme input pour pivot Excel ou matériel de briefing.

Exemple complet : audit → pages critiques → optimisation

PID=12

# 1) Démarrer l'audit
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) Poller jusqu'à completed
while [ "$(curl -s "$BASE/content-audits/$ID" \
  -H "Authorization: Bearer $TOKEN" | jq -r .status)" != "completed" ]; do
  sleep 30
done

# 3) Top-10 pages critiques
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) Faire passer une page par le Content Optimizer
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}"

Notes & pièges

• max_pages protège des bursts de crédits. Le défaut est conservateur — sur de gros sites, il faut volontairement le monter, sinon seules les pages top-level sont crawlées.
• exclude_paths est basé sur substring. /tag/ matche toutes les URLs avec /tag/ dans le path.
• Un re-audit n'écrase pas. Chaque audit est un snapshot autonome. Comparaison = lancer deux audits, exporter les deux IDs, faire un diff.
• Marquer comme résolu est optionnel. Mais utile pour les comparaisons re-audit (les pages résolues sont marquées visuellement comme « anciennement critiques »).

Voir aussi : API Projets · API Content Optimizer · Content Audit · Page Deep Audit.