API de Artículos

La API de artículos es la parte más usada de la API de Rankion — un único artículo recorre típicamente Crear → Generar → Puntuar → Optimizar → Publicar, con Repurpose, Freshness Check e Internal Linking opcionales. Todos los endpoints viven bajo /v1/articles/... y están scope al team.

Documentación completa del módulo: AI Content Editor · guía con capturas: Tu primer artículo.

CRUD

Generación

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

Respuesta 202 Accepted:

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

Después haz polling a GET /v1/articles/{id} hasta processing_status == "ready". Variante standalone sin proyecto: POST /v1/generate/article (mismos créditos).

Scoring y optimización

La respuesta de scoring incluye sub-scores (legibilidad, cobertura de keyword, requisitos estructurales, señales GEO), una lista de sugerencias concretas de mejora y un score global de 0 a 100.

Repurpose

Genera variantes compactas para social/newsletter a partir del artículo original.

Sin format se generan todos los formatos (mismo precio de 3 créditos). Con format, solo el solicitado.

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

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

Publish

Publica el artículo a través de una integración CMS configurada (WordPress, Shopify, adaptador REST custom).

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

Response 202 con job ID. Estado luego vía GET /v1/articles/{id} (cms_publish_status). Una segunda llamada de publish con un job en vuelo → 409 Conflict (evita duplicados).

Versions

Cada paso generativo (Generate, Optimize, Restore) crea una versión inmutable. Así puedes hacer rollback o comparar.

Freshness

Detecta estadísticas/fechas/links obsoletos y propone updates — clave para la estabilidad SEO en contenido evergreen.

Internal Linking

Ejemplo completo: Crear → Generar → Puntuar → Publicar

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

# 1) Crear 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) Arrancar la generación (5 créditos, 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) Polling hasta ready
while [ "$(curl -s "$BASE/articles/$ART" \
  -H "Authorization: Bearer $TOKEN" | jq -r .data.processing_status)" != "ready" ]; do
  echo "Generating..."; sleep 5
done

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

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

# 6) Publicar vía 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) Verificar estado de publish
curl -s "$BASE/articles/$ART" -H "Authorization: Bearer $TOKEN" \
  | jq '{cms_publish_status, public_url}'

Notas y pitfalls

• Generate es async. Aunque el endpoint devuelva 200, el contenido solo está listo tras finalizar el job. Haz polling siempre.
• Score requiere contenido. Un POST /score sin content suficiente devuelve un error de validación, no un score 0 inútil.
• Publish es exclusivo. Mientras un job de publish corre, no puedes volver a publicar — 409. Comprueba primero el estado.
• Las versiones son inmutables. Un restore no sobrescribe la versión antigua, sino que crea una nueva versión con el contenido antiguo.

Relacionado: API de Proyectos · Créditos · AI Content Editor · Tu primer artículo.