Postream

Loading the index…

Docs: API overview

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 or Bearer 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:

RouteSiteKeysCache
/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_ALLOWEDPublic, kept at the Cloudflare edge and purged when the post changes
/public/v1/…The key's siteSecret or publishableprivate, 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

MethodPathWhat it does
GET/postsLists the published posts, paginated.
GET/posts/:slugOne 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

  • ETag and Cache-Control: revalidate with If-None-Match and get 304.
  • 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"