GET/v1/blogs/{subdomain}/posts

List published posts

Returns a paginated list of published posts for the given blog. Results can be filtered by tag slug or a full-text search query, and sorted by any supported field. Only posts with status `PUBLISHED` are returned — drafts and scheduled posts are never included. Posts with `accessMode: PAID` are included in the listing but their full content is only accessible via the single-post endpoint for authenticated subscribers.

Parameters

Name	In	Type	Description
`subdomain`*	path	`string`	Subdomain of the blog (e.g. `alice` for `alice.writizzy.com`)
`page`	query	`integer (int32)` default: `0`	Zero-based page index
`limit`	query	`integer (int32)` default: `20`	Number of posts per page. Clamped to a maximum of 1000.
`tag`	query	`string`	Filter posts by tag slug. Use the `slug` field from the Tags endpoint.
`search`	query	`string`	Full-text search query applied to post titles and content excerpts
`sort`	query	`string` default: `publishedAt`	Field to sort by. Supported values: `publishedAt`, `updatedAt`, `title`, `claps`.
`order`	query	`string` default: `desc`	Sort direction: `asc` for ascending, `desc` for descending.

Responses

200Paginated list of posts returned successfully

postsobject[]required

Posts on the current page

idstringrequired

Unique post identifier

titlestringrequired

Post title

slugstringrequired

URL-safe slug used to fetch the full post via GET /posts/{slug}

excerptstringoptional

Short excerpt or teaser text, if provided by the author

publishedAtstring (date)optional

Date the post was published (ISO 8601 date). Null if the post is not yet published.

updatedAtstring (date-time)required

Date and time the post was last updated (ISO 8601 datetime)

coverImageUrlstringoptional

URL of the post cover image

urlstringrequired

Canonical public URL of the post

accessModestringrequired

Content access mode: FREE (visible to all readers) or PAID (requires an active paid subscription)

clapsinteger (int64)required

Total number of claps / reactions the post has received

tagsobject[]required

Tags associated with this post

namestringrequired

Human-readable tag name

slugstringrequired

URL-safe slug — use as the `tag` query parameter when filtering posts

authorsobject[]required

Authors credited on this post

namestringrequired

Display name of the author

avatarUrlstringoptional

URL of the author's avatar image

shortBiostringoptional

Short one-line biography suitable for bylines

pageinteger (int32)required

Zero-based current page index

limitinteger (int32)required

Maximum number of posts per page as requested

totalinteger (int64)required

Total number of matching posts across all pages

totalPagesinteger (int32)required

Total number of pages available

Code example

GET/v1/blogs/{subdomain}/posts

curl -X GET \
  -H "Accept: application/json" \
  "http://localhost:8080/v1/blogs/<subdomain>/posts"

GET/v1/blogs/{subdomain}/posts

curl -X GET \
  -H "Accept: application/json" \
  "http://localhost:8080/v1/blogs/<subdomain>/posts"