Docs
GET/v1/blogs/{subdomain}/posts

List posts

Returns a paginated list of 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 published posts are returned unless status asks for another state, which requires a write-scoped key.

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

subdomainpathstringrequired
Subdomain of the blog (e.g. alice for alice.writizzy.com)
pagequeryinteger (int32)optional
Zero-based page index
Default0
limitqueryinteger (int32)optional
Number of posts per page. Clamped to a maximum of 1000.
Default20
tagquerystringoptional
Filter posts by tag slug. Use the slug field from the Tags endpoint.
searchquerystringoptional
Full-text search query applied to post titles and content excerpts
sortquerystringoptional
Field to sort by. Supported values: publishedAt, updatedAt, title, claps.
DefaultpublishedAt
orderquerystringoptional
Sort direction: asc for ascending, desc for descending.
Defaultdesc
statusquerystringoptional
Publication state to read. Defaults to PUBLISHED. ALL returns posts in any state. Any value other than PUBLISHED requires a write-scoped API key.
DefaultPUBLISHEDOne ofPUBLISHEDDRAFTIN_REVIEWSCHEDULEDALL

Responses

200
Paginated list of posts returned successfully
postsobject[]required
Posts on the current page
14 properties
idstringrequired
Unique post identifier
titlestringrequired
Post title
slugstringrequired
URL-safe slug used to fetch the full post via GET /posts/{slug}
statusstringrequired
Publication state
One ofDRAFTIN_REVIEWSCHEDULEDPUBLISHED
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
2 properties
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
3 properties
namestringrequired
Display name of the author
avatarUrlstringoptional
URL of the author's avatar image
shortBiostringoptional
Short one-line biography suitable for bylines
canonicalUrlstringoptional
URL of the original version of this article, when it was first published elsewhere (Medium, dev.to, a personal blog...). Not to be confused with url, which is this post's own address on this blog. Null when this post is the original.
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" \
  "https://api.writizzy.com/v1/blogs/<subdomain>/posts"