API overview
A read-only REST API for each site to fetch its own published posts.
The public API delivers the published posts of one site. Each key belongs to a site and only sees that site's posts.
- Base:
https://<api>/public/v1(in development,http://localhost:4060/public/v1). - Authentication:
Authorization: Bearer sk_...on the server orBearer pk_...in the browser. See Authentication. - Format: JSON. Errors always as
{ "statusCode": 404, "code": "NOT_FOUND" }, with stable codes.
Two routes
Each endpoint exists on two routes, with the same content:
| Route | Site | Keys | Cache |
|---|---|---|---|
/public/v1/sites/{siteId}/… | In the URL (the siteId shows in the panel, under Public API) | Secret only; the publishable key gets 403 KEY_KIND_NOT_ALLOWED | Public, kept at the Cloudflare edge and purged when the post changes |
/public/v1/… | The key's site | Secret or publishable | private, no-cache: only the blog and the browser store it |
Recommended: the per-site route, called from the blog's server with the secret key. A key from another site on this route answers 404 NOT_FOUND. See Cache.
Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /posts | Lists the published posts, paginated. |
GET | /posts/:slug | One post with its body, by slug. |
There are also /authors, /authors/:slug, /categories, /site and /sitemap, used by the SEO kit.
What shows up
Only post versions with published status, a publication date already in the past and a slug set. A scheduled post shows up on its own when the time comes; an unpublished one disappears right away.
In every response
ETagandCache-Control: revalidate withIf-None-Matchand get304.RateLimit-*on the key route: how many requests are left in the window.- CORS only on the key route, for the site's allowed domains.
First test
curl -H "Authorization: Bearer $POSTREAM_API_KEY" \
"https://api.postream.blog/public/v1/sites/$POSTREAM_SITE_ID/posts?perPage=5"