In this section · 1 article

Blog public API reference

The public addresses your website reads published articles, categories, tags and authors from, with filters, languages, payloads, view and share counting, and the password unlock for protected articles.

Applies to
Blog 2.3 and later
Who can do this
Developer
On this page

Overview

Blog serves published articles to your website from your Laramin at /api/v1/public/blog/. These addresses need no sign-in or API key. They're rate-limited, and reads are cached briefly.

  • Responses use Laramin's standard envelope: { success, message, data, meta }. Errors carry { success: false, message, error: { code, type }, errors? }.
  • Names are snake_case. Dates are ISO 8601, for example 2026-07-20T10:00:00+00:00.
  • Language: add ?locale=ta to any address. If that language isn't turned on, you get your default language, and meta.locale tells you which one you got.
  • Rate limits per address: reads 120 a minute, view and share 30 a minute, unlock 5 a minute.

What's served

Every list serves only articles that are Published, whose Published date has passed, that haven't expired, and whose Visibility is Public.

VisibilityIn listsBy exact slug
PublicYesThe full article
Password ProtectedNoA locked stub, and the full article after unlock
PrivateNo404
Members OnlyNo404

A draft, a private article, an expired one and a slug that never existed all return the same 404.

Categories, tags and authors are served only while their Status is Active.

Reads

All GET.

MethodPathReturns
GET
/api/v1/public/blog/posts
Articles, in pages. Takes the filters below.
GET
/api/v1/public/blog/posts/featured
Articles marked Featured.
GET
/api/v1/public/blog/posts/recent
Newest first. Doesn't lift pinned articles.
GET
/api/v1/public/blog/posts/popular
Most read, all time.
GET
/api/v1/public/blog/posts/trending
Most read recently. ?days= from 1 to 90, 7 by default.
GET
/api/v1/public/blog/posts/{slug}
One article. Add ?type= (see below) and ?with_blocks=1 for the body's block structure.
GET
/api/v1/public/blog/posts/{slug}/related
The editor's picks first, then articles with the same tags and category.
GET
/api/v1/public/blog/categories
Every active category, flat, with post_count. Nest them yourself with parent_id and depth.
GET
/api/v1/public/blog/categories/{slug}
/api/v1/public/blog/categories/{slug}/posts
One category, and its articles.
GET
/api/v1/public/blog/tags
/api/v1/public/blog/tags/{slug}/posts
Active tags, most used first, and a tag's articles.
GET
/api/v1/public/blog/authors
/api/v1/public/blog/authors/{slug}
/api/v1/public/blog/authors/{slug}/posts
Active authors, one author, and their articles.

The four curated lists take ?limit=, 5 by default and 24 at most.

Filters

posts and every …/posts address take:

ParameterWhat it does
category, tag, authorA slug. author matches the byline or a co-author credit. An unknown slug matches nothing.
descendantsWith category, include its sub-categories.
typeA content type code: blog_ctype_article, blog_ctype_news, blog_ctype_knowledge_base, blog_ctype_release_note or blog_ctype_doc.
featured, sticky1 or 0.
qSearches titles, subtitles, excerpts and slugs, in every language.
sortrecent, oldest, popular or title. The default order puts pinned articles first, then newest.
per_page, page12 per page by default. More than 50 gets 50.

On a …/{slug}/posts address, an unknown slug in the path is a 404, and the path wins over a conflicting parameter.

Tip: A slug is unique only within its content type, so a News item and an Article can share one. Always send ?type= when you open an article by slug. Your website knows it from the URL prefix it routed on. Without it, the oldest match wins.

Payloads

Article in a list

JSON
{
  "id": 12, "slug": "spring-price-update", "content_type": "blog_ctype_article",
  "title": "Spring price update", "subtitle": null, "excerpt": "What changes in March.",
  "featured_image": "https://admin.example.com/storage/...", "thumbnail_image": null,
  "published_at": "2026-07-20T10:00:00+00:00",
  "reading_time": 4, "word_count": 820,
  "is_featured": false, "is_sticky": false, "locale": "en",
  "category": { }, "author": { }, "tags": [ ],
  "stats": { "views": 1204, "unique_views": 980, "shares": 31 }
}

Replace the highlighted values with your own.

Lists never carry the body.

One article

Everything above, plus is_locked, cover_image, banner_image, content_html, co_authors (each author with a role), media (the gallery: kind, url, provider, caption, alt_text, sort_order), allow_comments, allow_sharing and updated_at. With ?with_blocks=1, also blocks, the body as stored, about doubling the size.

content_html is cleaned on your Laramin and safe to render.

Keys that may be missing

KeyMissing whenDo this
seoSEO is off, or holds nothing for this articleBuild the page's head tags from title, excerpt and featured_image.
commentsAlways, in Blog 2.4.1Treat as no comments. Don't show a comment form.

A missing seo key is different from "seo": null. Don't render an empty title.

Author and category

  • Author: name, slug, avatar, bio, designation, is_guest, social_links. The email is never published.
  • Category: id, name, slug, description, icon, color, cover_image, parent_id, depth, and post_count on categories only.

Views and shares

MethodPathReturns
POST
/api/v1/public/blog/posts/{slug}/view
{ unique, views }. Add ?type= as for reads.
POST
/api/v1/public/blog/posts/{slug}/share
{ shares }. 422 Sharing is turned off for this article. when Allow sharing is off.
  • Send view once per page view, and don't try to skip repeats yourself. Your Laramin counts every read in views, and counts each visitor once a day in unique_views.
  • A visitor is recognized by the IP address and browser of the request, which are hashed and never stored as they are. Send view from the reader's browser. If your server sends it, every reader looks like the same visitor, and all of them share one rate limit.
  • Only articles served in lists are counted. Password-protected and private articles aren't.
  • popular ranks on all-time unique views. trending counts reads in the recent window.

Password-protected articles

Opening a protected article returns a 200 with a locked stub, not a 401:

JSON
{ "id": 12, "slug": "...", "content_type": "...", "title": "...",
  "published_at": "...", "locale": "en", "is_locked": true }

Show a password box, then send it:

Plain text
POST posts/{slug}/unlock    { "password": "..." }
  200  { unlock_token, expires_at, header: "X-Blog-Unlock", post: { the full article } }
  403  wrong password
  422  the article has no password
  404  no such article

Send the token on later reads of that article, in the X-Blog-Unlock header, not in the address. The token:

  • opens only the article it was issued for,
  • expires after 12 hours (expires_at says when),
  • stops working when an editor changes the password.

Whenever is_locked comes back true, show the password box again.

Not available in Blog 2.4.1

  • Members Only articles can't be served: there's no reader sign-in.
  • Comments aren't collected or served.
  • Likes aren't counted.
  • Articles, categories and tags are read-only here. Nothing can be written except views, shares and unlocks.

For search titles, descriptions, the sitemap, feeds and redirects, read the SEO add-on's public addresses as well. See How the SEO add-on works.