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 oBearer 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:
| Ruta | Sitio | Claves | Caché |
|---|---|---|---|
/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_ALLOWED | Pública, guardada en el borde de Cloudflare y purgada cuando el post cambia |
/public/v1/… | El de la clave | Secreta o publicable | private, 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étodo | Ruta | Qué hace |
|---|---|---|
GET | /posts | Lista los posts publicados, paginados. |
GET | /posts/:slug | Un 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
ETagyCache-Control: revalida conIf-None-Matchy recibe304.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"