List posts
The site's published posts, newest to oldest, paginated and without the body.
GET/public/v1/sites/{siteId}/posts
GET/public/v1/posts
The first is the per-site route (secret key only, kept at the edge); the second is the key route (secret or publishable). See Two routes. The "Try it" panel uses the key route, with a publishable key.
Parameters
| Parameter | Default | Description |
|---|---|---|
pageinteger | 1 | Page, starting at 1. |
perPageinteger | 20 | Items per page, from 1 to 100. |
localestring | — | Language (pt-BR, en-US, es), among those enabled on the site. Without it, all languages come back. |
tagstring | — | Only posts with this tag (exact match). |
An invalid or repeated parameter answers 400 BAD_USER_INPUT; a locale outside the site's languages answers 400 LOCALE_NOT_ENABLED.
Response
Order: publication date, newest to oldest. List items do not carry the body; to get it, fetch the post.
{
"data": [
{
"id": "7c0e…",
"locale": "en-US",
"slug": "managing-many-blogs",
"title": "Managing many blogs",
"excerpt": "…",
"tags": ["blogs"],
"seo": {
"metaTitle": "Managing many blogs without losing your voice",
"metaDescription": "…",
"og": { "title": "Managing many blogs without losing your voice", "description": "…", "type": "article" }
},
"translations": [{ "locale": "pt-BR", "slug": "como-gerir-varios-blogs", "title": "Como gerir vários blogs" }],
"author": null,
"publishedAt": "2026-10-20T12:00:00.000Z",
"updatedAt": "2026-10-20T12:00:00.000Z"
}
],
"pagination": { "page": 1, "perPage": 20, "total": 1, "totalPages": 1 }
}idis the post's: translations share the sameid.translationslists the other published versions, useful forhreflang.authoris whoever signs the version (the author chosen in the panel or the site's default author);nullonly when there is none.
Pagination
Ask for page=2, page=3… up to pagination.totalPages. A page beyond the last one comes back with an empty data, not an error.
On the per-site route, build the query in the canonical form (?locale= before &tag=, no page=1): that is the URL Postream purges when a post changes.
Examples
From the server, with the secret key:
curl -H "Authorization: Bearer $POSTREAM_API_KEY" \
"https://api.postream.blog/public/v1/sites/$POSTREAM_SITE_ID/posts?locale=en-US&perPage=5"const res = await fetch(`https://api.postream.blog/public/v1/sites/${process.env.POSTREAM_SITE_ID}/posts?locale=en-US&perPage=5`, {
headers: { Authorization: `Bearer ${process.env.POSTREAM_API_KEY}` },
});
const { data, pagination } = await res.json();export default async function Blog() {
const res = await fetch(`${process.env.POSTREAM_API_URL}/sites/${process.env.POSTREAM_SITE_ID}/posts?locale=en-US`, {
headers: { Authorization: `Bearer ${process.env.POSTREAM_API_KEY}` },
next: { revalidate: 300 },
});
const { data } = await res.json();
return (
<ul>
{data.map((post: { slug: string; title: string }) => (
<li key={post.slug}>
<a href={`/blog/${post.slug}`}>{post.title}</a>
</li>
))}
</ul>
);
}