API

API de Content Intelligence

Reportes agregados sobre score, freshness y linking por proyecto — una sola API.

La API de Content Intelligence es el endpoint colector para todo lo que mide calidad de contenido a nivel proyecto: score promedio, artículos obsoletos, orphan pages, cobertura de Style Profiles y el estado actual de internal linking. En lugar de lanzar una llamada por subsistema, un único GET te da una imagen consolidada — perfecto para dashboards y herramientas externas de reporting.

Contexto del módulo: Content Freshness · Internal Linking · Storylines.

Endpoint Overview

Method	Endpoint	Descripción	Créditos
GET	`/v1/content-intelligence?project_id={id}`	Reporte agregado de todos los subsistemas de contenido del proyecto	—
GET	`/v1/content-freshness?project_id={id}`	Lista de freshness a nivel proyecto (qué artículos están obsoletos)	—

curl "$BASE/content-intelligence?project_id=12" \
  -H "Authorization: Bearer $TOKEN" | jq

Response (recortada):

{
  "data": {
    "project_id": 12,
    "articles": {"total": 142, "avg_score": 78, "below_60": 9},
    "freshness": {"checked": 120, "stale": 14, "last_run_at": "2026-04-29T09:00:00Z"},
    "linking": {"orphans": 3, "suggestions_open": 27},
    "style_profiles": {"active": 2, "coverage_pct": 91}
  }
}

Storylines

Las Storylines agrupan artículos relacionados en un topic cluster con pillar content común.

Method	Endpoint	Descripción
GET	`/v1/projects/{project}/storylines`	Lista de todas las storylines
POST	`/v1/projects/{project}/storylines`	Crear nueva storyline
GET	`/v1/storylines/{id}`	Detalle con artículos asociados
PUT	`/v1/storylines/{id}`	Update
DELETE	`/v1/storylines/{id}`	Eliminar

Style Profiles

Definen tonalidad, brand voice y reglas de redacción que Generate/Optimize aplican.

Method	Endpoint	Descripción	Créditos
GET	`/v1/projects/{project}/style-profiles`	Lista (incluye además `source_type`, `source_url`, `pending_review`, `scraped_pages`, `failure_reason`, `reviewed_at`)	—
POST	`/v1/projects/{project}/style-profiles`	Crear manualmente	—
GET	`/v1/style-profiles/{id}`	Detalle (mismos campos adicionales)	—
PUT	`/v1/style-profiles/{id}`	Actualizar (si `pending_review=true`, se pone implícitamente a `false` y se registra `reviewed_at`)	—
DELETE	`/v1/style-profiles/{id}`	Eliminar	—
POST	`/v1/projects/{project}/style-profiles/from-url`	Iniciar análisis de estilo por URL en segundo plano. HTTP 202 → `{ data: { id, status: "pending", source_url, message } }`	25
GET	`/v1/style-profiles/{id}/scrape-status`	Estado del job → `{ status, source_url, scraped_pages, failure_reason, pending_review }`	—
POST	`/v1/style-profiles/{id}/accept`	Aceptar perfil (`pending_review=false`, `reviewed_at=now()`). Respuesta: `{ data: <StyleProfile> }`	—
POST	`/v1/style-profiles/{id}/discard`	Descartar (soft-delete). Solo si `pending_review=true`, si no 422. Respuesta: `{ deleted: true }`	—

Knowledge Base

Contexto adicional (PDFs, textos, URLs) que la generación toma como source.

Method	Endpoint	Descripción
GET	`/v1/projects/{project}/knowledge-base`	Todas las entradas
POST	`/v1/projects/{project}/knowledge-base`	Añadir entrada
DELETE	`/v1/knowledge-base/{id}`	Eliminar

Link Lists

Whitelists/blacklists para internal link generation.

Method	Endpoint
GET	`/v1/projects/{project}/link-lists`
POST	`/v1/projects/{project}/link-lists`
DELETE	`/v1/link-lists/{id}`

Orphan Scans

Encuentra artículos sin internal links entrantes (problema SEO).

Method	Endpoint	Descripción
POST	`/v1/projects/{project}/orphan-scans/discover`	Dispatchar scan (async)
POST	`/v1/orphan-scans/{id}/start`	Reiniciar
GET	`/v1/orphan-scans/{id}`	Status + summary
GET	`/v1/orphan-scans/{id}/pages`	Lista de páginas huérfanas
DELETE	`/v1/orphan-scans/{id}`	Eliminar

SCAN=$(curl -s -X POST "$BASE/projects/12/orphan-scans/discover" \
  -H "Authorization: Bearer $TOKEN" | jq -r .data.id)

# Polling hasta status == "completed"
curl -s "$BASE/orphan-scans/$SCAN" -H "Authorization: Bearer $TOKEN" \
  | jq '{status, orphans_found}'

curl -s "$BASE/orphan-scans/$SCAN/pages" \
  -H "Authorization: Bearer $TOKEN" | jq '.data[].url'

Notas

El endpoint Overview cachea internamente 60 s — los reportes cargan rápido, pero los valores pueden ir hasta un minuto por detrás.
freshness.stale solo cuenta artículos con freshness check finalizado. Los artículos sin un check ejecutado nunca no aparecen en la cuota stale — ver API de Artículos para POST /articles/{id}/freshness/check.
Los Orphan Scans son async, pero baratos (sin coste en créditos) e idempotentes por proyecto — los discovers paralelos se deduplican en servidor.
Los Style Profiles surten efecto en el siguiente run de Generate/Optimize, no retroactivamente sobre contenido existente.

Relacionado: API de Artículos · Content Freshness · Internal Linking · Storylines.

Letzte Aktualisierung: 7 de mayo de 2026