API de Content Audits

La API de Content Audits ejecuta una auditoría completa de site: crawlea un dominio, puntúa cada page por calidad de contenido, cobertura de keyword, señales SEO técnicas y devuelve recomendaciones priorizadas por URL. A diferencia del Page Deep Audit (single-URL, basado en Vision), el Content Audit cubre toda la site horizontalmente. Todos los endpoints viven bajo /v1/... y están scope al team.

Contexto del módulo: Content Audit.

Endpoints

Iniciar auditoría

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

El crawl corre asíncronamente — regla aproximada: 200 pages ~ 5–8 minutos. max_pages es duro, el crawler para al alcanzarlo.

Cabecera de la auditoría

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 con filtro

# Todas las pages con score < 40 (críticas)
curl "$BASE/content-audits/$ID/pages?score_lt=40&sort=score_asc" \
  -H "Authorization: Bearer $TOKEN"

# Todas las pages con categoría de issue "thin_content"
curl "$BASE/content-audits/$ID/pages?category=thin_content" \
  -H "Authorization: Bearer $TOKEN"

Detalle de page

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
}

Marcar pages como resueltas

Tras arreglar una page (p. ej. vía la API de Artículos → optimize), márcala como resuelta — desaparece de las listas de issues abiertos pero permanece en el histórico de la auditoría.

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

Para reportes externos o backup:

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

El export contiene todas las pages con recomendaciones completas y breakdowns de score — apto como input para Excel pivots o material de briefing.

Ejemplo completo: Audit → pages críticas → optimizar

PID=12

# 1) Iniciar 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) Polling hasta completed
while [ "$(curl -s "$BASE/content-audits/$ID" \
  -H "Authorization: Bearer $TOKEN" | jq -r .status)" != "completed" ]; do
  sleep 30
done

# 3) Top-10 pages críticas
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) Pasar una page por el 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}"

Notas y pitfalls

• max_pages protege de un burst de créditos. El default es conservador — en sites grandes súbelo a propósito, si no, solo se crawlean pages top-level.
• exclude_paths es por substring. /tag/ matchea cualquier URL con /tag/ en el path.
• Re-audit no sobrescribe. Cada audit es un snapshot propio. Comparación = corre dos audits, exporta ambos IDs y haz un diff.
• Marcar como solved es opcional. Pero ayuda en comparaciones re-audit (las pages solved se marcan visualmente como «antes críticas»).

Relacionado: API de Proyectos · API de Content Optimizer · Content Audit · Page Deep Audit.