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/. 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 example2026-.07- 20T10:00:00+00:00 - Language: add
?locale=tato any address. If that language isn't turned on, you get your default language, andmeta.localetells you which one you got. - Rate limits per address: reads 120 a minute,
viewandshare30 a minute,unlock5 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.
| Visibility | In lists | By exact slug |
|---|---|---|
| Public | Yes | The full article |
| Password Protected | No | A locked stub, and the full article after unlock |
| Private | No | 404 |
| Members Only | No | 404 |
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.
| Method | Path | Returns |
|---|---|---|
| GET | /api/ | Articles, in pages. Takes the filters below. |
| GET | /api/ | Articles marked Featured. |
| GET | /api/ | Newest first. Doesn't lift pinned articles. |
| GET | /api/ | Most read, all time. |
| GET | /api/ | Most read recently. ?days= from 1 to 90, 7 by default. |
| GET | /api/ | One article. Add ?type= (see below) and ?with_blocks=1 for the body's block structure. |
| GET | /api/ | The editor's picks first, then articles with the same tags and category. |
| GET | /api/ | Every active category, flat, with post_count. Nest them yourself with parent_id and depth. |
| GET | /api//api/ | One category, and its articles. |
| GET | /api//api/ | Active tags, most used first, and a tag's articles. |
| GET | /api//api//api/ | 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:
| Parameter | What it does |
|---|---|
category, tag, author | A slug. author matches the byline or a co-author credit. An unknown slug matches nothing. |
descendants | With category, include its sub-categories. |
type | A content type code: blog_, blog_ctype_news, blog_, blog_ or blog_ctype_doc. |
featured, sticky | 1 or 0. |
q | Searches titles, subtitles, excerpts and slugs, in every language. |
sort | recent, oldest, popular or title. The default order puts pinned articles first, then newest. |
per_page, page | 12 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
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
{
"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
| Key | Missing when | Do this |
|---|---|---|
seo | SEO is off, or holds nothing for this article | Build the page's head tags from title, excerpt and featured_image. |
comments | Always, in Blog 2.4.1 | Treat 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, andpost_countoncategoriesonly.
Views and shares
| Method | Path | Returns |
|---|---|---|
| POST | /api/ | { unique, views }. Add ?type= as for reads. |
| POST | /api/ | { shares }. 422 Sharing is turned off for this article. when Allow sharing is off. |
- Send
viewonce per page view, and don't try to skip repeats yourself. Your Laramin counts every read inviews, and counts each visitor once a day inunique_views. - A visitor is recognized by the IP address and browser of the request, which are hashed and never stored as they are. Send
viewfrom 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.
popularranks on all-time unique views.trendingcounts reads in the recent window.
Password-protected articles
Opening a protected article returns a 200 with a locked stub, not a 401:
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
{ "id": 12, "slug": "...", "content_type": "...", "title": "...",
"published_at": "...", "locale": "en", "is_locked": true }Show a password box, then send it:
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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 articleSend 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_atsays 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.
Thanks. That helps us decide what to write next.
Thanks for telling us what was missing.
You already answered for this article today. Thanks.
We got a lot of answers from your network just now. Try again in a few minutes.
We couldn't send that. Check your connection and try again.
Links in this article
Printed from help.laramin.in. The online article may have changed since.