API de StoryFeed Media

Base URL y acceso

Todas las rutas documentadas acá cuelgan de https://api.storyfeedmedia.com/api/v1. El host storyfeedmedia.com sirve la API con el mismo path, así que ambos prefijos son intercambiables.

• No hay claves de API ni OAuth: la superficie es read-only y pública.
• Todas las respuestas llevan Access-Control-Allow-Origin: *.
• Cada respuesta incluye X-Request-Id (correlation ID) para soporte.
• El error siempre usa el mismo envelope (ver Errores).

# Primer request: última página del feed de un cliente
curl -s "https://api.storyfeedmedia.com/api/v1/feed?client=demo"

Endpoints

Feed

Historias ordenadas por publishedAt descendente. Las que no tienen fecha van al final.

Query params

Respuesta 200

{
  "items": [
    {
      "id": "a1b2c3",
      "slug": "el-futuro-del-periodismo-movil",
      "type": "article",
      "title": "El futuro del periodismo móvil",
      "excerpt": "Una mirada a los formatos que retienen...",
      "image": { "src": "https://cdn.ejemplo.com/foto.jpg", "alt": "Redacción" },
      "tags": ["tecnologia"],
      "theme": "portada",
      "section": "tecnologia",
      "publishedAt": "2026-11-08T10:00:00.000Z",
      "contentUrl": "https://medio.ejemplo.com/nota/..."
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjEwfQ",
  "hasMore": true,
  "publisher": { "name": "Diario Ejemplo", "logo": "https://medio.ejemplo.com/logo.png" }
}

Errores propios

Detalle por slug

Devuelve el objeto Story completo, incluido content cuando el artículo tiene body.

curl -s "https://api.storyfeedmedia.com/api/v1/story/el-futuro-del-periodismo-movil?client=demo"

content es HTML del artículo con URLs relativas ya resueltas a absolutas. excerpt y subtitle son resúmenes de hasta 280 caracteres; si coinciden con el cuerpo completo, se omiten.

Feeds por tema

Agrupa los datasets de varios clients bajo una definición de tema y los sirve como un feed único.

La respuesta usa el mismo contrato que /feed. Los clients sin contenido se saltean; si ninguno tiene stories, responde 200 con items: []. El orden se define por el bloque sort del tema (recency, round-robin o alternating).

Detalle dentro del tema

Busca el slug entre los clients del tema y devuelve la primera coincidencia, con content si existe.

Health

Sin dependencias externas: no consulta la base de datos.

{ "status": "ok", "uptimeSeconds": 123 }

Modelo Story

Contrato en shared/schema/story.schema.json. Campos requeridos: id, slug, type.

Los campos _adOverlayId y _adDetailId son internos del componente y no forman parte del contrato público.

Paginación y cursor

La paginación es por cursor, no por offset numérico. Pedí la primera página sin cursor; para la siguiente pasá el nextCursor de la respuesta.

# Página 1
curl -s "https://api.storyfeedmedia.com/api/v1/feed?client=demo"

# Página 2 — usar el nextCursor devuelto
curl -s "https://api.storyfeedmedia.com/api/v1/feed?client=demo&cursor=eyJvZmZzZXQiOjEwfQ"

• hasMore: false indica que no hay más páginas.
• El cursor es opaco: no lo parsees ni lo construyas a mano.
• El cursor codifica un offset sobre contenido real (Base64URL). Es una deuda técnica intencional: con escrituras concurrentes puede saltear o repetir items.
• Un cursor inválido responde 400 INVALID_CURSOR; pedí la primera página de nuevo.

Errores

Todas las respuestas de error comparten el mismo envelope:

{
  "error": {
    "code": "STORY_NOT_FOUND",
    "message": "Story not found",
    "status": 404,
    "requestId": "req-8f3a..."
  }
}

• requestId coincide con el header X-Request-Id.
• Los errores no se cachean con el ETag del recurso.
• Ante 429, respetá Retry-After y aplicá backoff.

Rate limits

Límites por IP + path, ventana de 15 minutos (salvo demos). Toda respuesta incluye RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset.

El bloqueo responde 429 con Retry-After. En producción, Cloudflare es la capa que aplica el límite efectivo.

Cache y ETag

Las respuestas de feed y detalle incluyen ETag débil y Cache-Control con max-age corto y s-maxage largo. Para revalidar, mandá If-None-Match: si nada cambió, la API responde 304 sin body.

curl -s -H 'If-None-Match: W/"abc123"' \
  "https://api.storyfeedmedia.com/api/v1/feed?client=demo"

La invalidación en producción es activa por Cache-Tag en cada escritura, no solo por TTL.

Recursos para agentes

El contrato humano vive en docs/api.md del repo. La especificación openapi.json es la fuente máquina.

Embed

El componente consume esta API. Un snippet mínimo:

<script src="https://storyfeedmedia.com/js/story-feed.min.js" defer></script>
<story-feed endpoint="https://api.storyfeedmedia.com/api/v1/feed"
            client="tu-medio"></story-feed>

Guía de integración y personalización: Configurador · Feeds RSS · Métricas GA4.