API Articles

L'API Articles est la partie la plus utilisée de l'API Rankion — un article unique passe typiquement par Création → Génération → Scoring → Optimisation → Publication, éventuellement avec Repurpose, Freshness-Check et maillage interne. Tous les endpoints sont sous /v1/articles/... et team-scoped.

Documentation contextuelle complète du module : AI Content Editor · Tutoriel illustré : Premier article.

CRUD

Génération

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

Réponse 202 Accepted :

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

Ensuite, polle GET /v1/articles/{id} jusqu'à processing_status == "ready". Variante standalone sans projet : POST /v1/generate/article (mêmes crédits).

Scoring & optimisation

La réponse de score contient des sous-scores (lisibilité, couverture mot-clé, exigences de structure, signaux GEO), une liste de suggestions concrètes d'amélioration et un score global 0–100.

Repurpose

Génère des variantes compactes pour le social/newsletter à partir de l'article original.

Sans format, tous les formats sont générés (même prix de 3 crédits). Avec format, seul celui demandé.

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

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

Publish

Publie l'article via une intégration CMS configurée (WordPress, Shopify, adaptateur REST custom).

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

Réponse 202 avec ID de job. Statut ensuite via GET /v1/articles/{id} (cms_publish_status). Un second appel publish pendant qu'un job est en vol → 409 Conflict (empêche les doublons).

Versions

Chaque étape générative (Generate, Optimize, Restore) crée une version immuable. Cela te permet de rollback ou de comparer.

Freshness

Détecte les statistiques/années/liens obsolètes et propose des mises à jour — important pour la stabilité SEO des contenus evergreen.

Maillage interne

Exemple complet : créer → générer → scorer → publier

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

# 1) Créer le stub
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) Démarrer la génération (5 crédits, 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) Poller jusqu'à ready
while [ "$(curl -s "$BASE/articles/$ART" \
  -H "Authorization: Bearer $TOKEN" | jq -r .data.processing_status)" != "ready" ]; do
  echo "Generating..."; sleep 5
done

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

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

# 6) Publier via l'intégration CMS 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) Vérifier le statut publish
curl -s "$BASE/articles/$ART" -H "Authorization: Bearer $TOKEN" \
  | jq '{cms_publish_status, public_url}'

Notes & pièges

• Generate est async. Même si l'endpoint renvoie 200 — le contenu n'est disponible qu'après la fin du job. Toujours poller.
• Score nécessite du contenu. POST /score sans content suffisant renvoie une erreur de validation plutôt qu'un score 0 inutile.
• Publish est exclusif. Tant qu'un job publish tourne, tu ne peux pas re-publier — 409. Vérifie d'abord le statut.
• Les versions sont immuables. Restorer n'écrase pas l'ancienne version, mais crée une nouvelle version avec l'ancien contenu.

Voir aussi : API Projets · Crédits · AI Content Editor · Premier article.