API de Content Optimizer

El Content Optimizer scrapea una URL existente, analiza señales SEO + GEO contra la keyword objetivo y entrega 15–25 sugerencias concretas de mejora — desde reescrituras de headline hasta recomendaciones de FAQ schema. Mediante apply puedes materializar las sugerencias aceptadas directamente en un artículo optimizado.

Contexto del módulo: Content Optimizer · walkthrough: Optimizar contenido.

Endpoints

Iniciar análisis

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

curl -X POST "$BASE/content-optimizer/analyze" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "url":"https://example.com/blog/ai-coding",
    "keyword":"ai coding tools",
    "project_id":12,
    "language":"en"
  }'

Respuesta 202 Accepted:

{
  "id": 47,
  "status": "pending",
  "message": "Analysis dispatched"
}

El job tarda 10–20 segundos: ScraperAPI obtiene el HTML, Claude Sonnet 4.5 lo compara contra el Top-10 SERP de la keyword y contra las heurísticas GEO (entity coverage, citation worthiness, idoneidad para AI snippets).

Obtener detalle

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

Forma de la response:

{
  "id": 47,
  "status": "completed",
  "url": "https://example.com/blog/ai-coding",
  "keyword": "ai coding tools",
  "scraped_word_count": 1240,
  "current_score": 62,
  "potential_score": 84,
  "suggestions": [
    {
      "id": 311,
      "category": "headline",
      "priority": "high",
      "title": "H1 enthält Keyword nicht prominent",
      "before": "Coding mit AI: ein Überblick",
      "after": "Die besten AI Coding Tools 2026 (mit Benchmarks)",
      "rationale": "Top-3-SERP-Ergebnisse haben das Keyword in den ersten 3 Wörtern."
    }
  ]
}

suggestions[] está ordenado por priority (high → low) y se puede agrupar por category (headline, meta, intro, faq, internal_links, entities, schema, structure, cta).

Aplicar sugerencias

En lugar de devolver cada sugerencia manualmente al CMS de origen, puedes materializarlas como un artículo optimizado en Rankion — el artículo resultante aterriza en el AI Content Editor y desde allí se publica vía la API de Artículos.

curl -X POST "$BASE/content-optimizer/$ID/apply" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "suggestion_ids":[311, 312, 315, 318],
    "create_article":true
  }'

Response:

{
  "article_id": 92,
  "applied_count": 4,
  "score_before": 62,
  "score_after": 81
}

Ejemplo completo: Análisis → Top sugerencias → Apply

PID=12

# 1) Dispatchar análisis
ID=$(curl -s -X POST "$BASE/content-optimizer/analyze" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/blog/ai-coding","keyword":"ai coding tools","project_id":'$PID'}' \
  | jq -r .id)

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

# 3) Extraer Top-5 sugerencias high-priority
TOP=$(curl -s "$BASE/content-optimizer/$ID" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -c '[.suggestions[] | select(.priority=="high")][:5] | map(.id)')

# 4) Aplicar
curl -X POST "$BASE/content-optimizer/$ID/apply" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"suggestion_ids\":$TOP,\"create_article\":true}"

Notas y pitfalls

• Analyze es async. Aunque el endpoint devuelva 200/202, las sugerencias solo aparecen tras finalizar el job. Intervalo de polling: 3–5 s.
• url debe ser pública. ¿Detrás de un login? → ScraperAPI falla → status="failed" con detalle en error_message.
• Apply no es idempotente. Aplicar varias veces los mismos suggestion IDs crea varios artículos. Comprueba antes si article_id ya está fijado.
• Keyword es obligatoria. Sin keyword no hay base de comparación SERP → error de validación.

Relacionado: API de Artículos · Créditos · Content Optimizer · Optimizar contenido.