Postream

Loading the index…

Docs: List posts

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

ParameterDefaultDescription
pageinteger1Page, starting at 1.
perPageinteger20Items 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 }
}
  • id is the post's: translations share the same id.
  • translations lists the other published versions, useful for hreflang.
  • author is whoever signs the version (the author chosen in the panel or the site's default author); null only 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"