Postream

Cargando el índice…

Documentación: Visión general de la API

Visión general de la API

Una API REST de solo lectura para que cada sitio busque sus propios posts publicados.

La API pública entrega los posts publicados de un sitio. Cada clave pertenece a un sitio y solo ve los posts de ese sitio.

  • Base: https://<api>/public/v1 (en desarrollo, http://localhost:4060/public/v1).
  • Autenticación: Authorization: Bearer sk_... en el servidor o Bearer pk_... en el navegador. Mira Autenticación.
  • Formato: JSON. Los errores siempre como { "statusCode": 404, "code": "NOT_FOUND" }, con códigos estables.

Dos rutas

Cada endpoint existe en dos rutas, con el mismo contenido:

RutaSitioClavesCaché
/public/v1/sites/{siteId}/…En la URL (el siteId aparece en el panel, en API pública)Solo secreta; la publicable recibe 403 KEY_KIND_NOT_ALLOWEDPública, guardada en el borde de Cloudflare y purgada cuando el post cambia
/public/v1/…El de la claveSecreta o publicableprivate, no-cache: solo el blog y el navegador guardan

Recomendado: la ruta por sitio, llamada desde el servidor del blog con la clave secreta. Una clave de otro sitio en esa ruta responde 404 NOT_FOUND. Mira Caché.

Endpoints

MétodoRutaQué hace
GET/postsLista los posts publicados, paginados.
GET/posts/:slugUn post con el cuerpo, por slug.

También están /authors, /authors/:slug, /categories, /site y /sitemap, que usa el kit de SEO.

Qué aparece

Solo versiones de post con estado publicado, fecha de publicación ya pasada y slug definido. Un post programado aparece solo cuando llega la hora; uno despublicado desaparece al instante.

En todas las respuestas

  • ETag y Cache-Control: revalida con If-None-Match y recibe 304.
  • RateLimit-* en la ruta por clave: cuántas solicitudes quedan en la ventana.
  • CORS solo en la ruta por clave, para los dominios permitidos del sitio.

Primera prueba

curl -H "Authorization: Bearer $POSTREAM_API_KEY" \
  "https://api.postream.blog/public/v1/sites/$POSTREAM_SITE_ID/posts?perPage=5"