News API
News posts are announcements for clients: they show at /news and on the client dashboard, with drafts, publish and expiry dates and pinned posts. Guest calls return only the posts clients can see. See Announcements for the user guide.
Admin calls need Module access on the News card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.
Admin calls
Section titled “Admin calls”get_list
Section titled “get_list”POST /api/admin/news/get_list
Lists every news post, drafts, scheduled and expired ones included. Pinned posts come first, then the newest by publish date (the created date when none is set).
Permission: View news (news.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer | Only the post with this id. |
status |
string | Only posts with this status: active or draft. |
search |
string | Text to find in the title, slug, description, section or content. |
section |
string | Text to find in the section name. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row is a post with the fields of admin/get, except that author is an empty array.
Example
Request parameters:
{ "status": "active", "per_page": 1}result:
{ "pages": 3, "page": 1, "per_page": 1, "total": 3, "list": [ { "id": 12, "title": "Planned maintenance on Saturday", "description": "Our servers get a kernel update on Saturday night.", "content": "<p>Our servers get a kernel update on Saturday night.</p>", "status": "active", "slug": "planned-maintenance-on-saturday", "image": null, "section": "Maintenance", "pinned": true, "publish_at": "2026-11-18 09:00:00", "published_at": null, "expires_at": "2026-11-23 00:00:00", "created_at": "2026-11-17 10:02:11", "updated_at": "2026-11-17 10:02:11", "author": [], "excerpt": null } ]}POST /api/admin/news/get
Returns one news post by id or slug, whatever its status or dates.
Permission: View news (news.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer | The post’s id. Give id or slug; id wins when both are given. |
slug |
string | The post’s slug, as in its URL. |
Returns: The post: id, title, description, content (HTML, with the <!--more--> marker removed), status (active or draft), slug, image, section, pinned (boolean), publish_at, published_at, expires_at, created_at, updated_at (dates or null), author (name of the staff member who last saved it, or an empty array) and excerpt (the content before <!--more-->, or null when the content has no marker).
Errors:
- ID or slug is required. (code 9999) when neither is given.
- News item not found. (code 9999)
Example
Request parameters:
{ "id": 12}result:
{ "id": 12, "title": "Planned maintenance on Saturday", "description": "Our servers get a kernel update on Saturday night.", "content": "<p>Our servers get a kernel update on Saturday night.</p><p>Websites stay online.</p>", "status": "active", "slug": "planned-maintenance-on-saturday", "image": null, "section": "Maintenance", "pinned": true, "publish_at": "2026-11-18 09:00:00", "published_at": null, "expires_at": "2026-11-23 00:00:00", "created_at": "2026-11-17 10:02:11", "updated_at": "2026-11-17 10:02:11", "author": { "name": "Jane Admin" }, "excerpt": "<p>Our servers get a kernel update on Saturday night.</p>"}update
Section titled “update”POST /api/admin/news/update
Changes a news post. A field you leave out keeps its current value.
Permission: Manage news (news.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The post’s id. |
title |
string | The title, up to 255 characters. It cannot be empty. |
slug |
string | The URL name. It is cleaned to lowercase letters, digits and hyphens and must be unique. Empty: made from the title. |
content |
string | The post’s HTML. Put <!--more--> where the excerpt ends. |
description |
string | The meta description. Empty: the first 125 characters of the content, without HTML. |
image |
string | An image URL, up to 255 characters. |
section |
string | A section name, up to 255 characters. |
status |
string | active (clients can see it) or draft. |
pinned |
boolean | Shows the post before the others. |
publish_at |
string | Date and time clients start to see it. Empty or null clears it (shown at once). |
expires_at |
string | Date and time clients stop seeing it. Empty or null clears it. |
created_at |
string | Changes the created date. |
Returns: true.
Errors:
- Post ID was not passed (code 9999)
- News item not found (code 9999)
- Post title was not passed (code 9999) when the title is empty.
- Keep the title, slug, image and section under 255 characters. (code 9999)
- You need to set unique slug. (code 9999) when another post has the slug.
- Enter a valid date. (code 9999)
The staff member who makes the call becomes the post’s author.
Example
Request parameters:
{ "id": 12, "pinned": false, "expires_at": "2026-11-25 00:00:00"}result:
truecreate
Section titled “create”POST /api/admin/news/create
Creates a news post.
Permission: Manage news (news.manage)
| Parameter | Type | Description |
|---|---|---|
title |
string, required | The title, up to 255 characters. |
slug |
string | The URL name, cleaned to lowercase letters, digits and hyphens; it must be unique. Leave it out to make one from the title (with -2, -3 added when it is taken). |
content |
string | The post’s HTML. Put <!--more--> where the excerpt ends. |
description |
string | The meta description. Empty: the first 125 characters of the content, without HTML. |
image |
string | An image URL, up to 255 characters. |
section |
string | A section name, up to 255 characters. |
status |
string | active (default: clients see it) or draft. |
pinned |
boolean | Shows the post before the others. Default false. |
publish_at |
string | Date and time clients start to see it. Leave it out to show it at once. |
expires_at |
string | Date and time clients stop seeing it. Leave it out to keep it. |
Returns: The new post’s id.
Errors:
- Post title was not passed (code 9999)
- Keep the title, slug, image and section under 255 characters. (code 9999)
- You need to set unique slug. (code 9999)
- Enter a valid date. (code 9999)
An active post with no publish date shows to clients at once: create it as a draft to prepare it first.
Example
Request parameters:
{ "title": "Planned maintenance on Saturday", "content": "<p>Our servers get a kernel update on Saturday night.</p>", "section": "Maintenance", "status": "draft"}result:
12delete
Section titled “delete”POST /api/admin/news/delete
Deletes a news post for good.
Permission: Manage news (news.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The post’s id. |
Returns: true.
Errors:
- Post ID was not passed (code 9999)
- News item not found (code 9999)
This cannot be undone.
batch_delete
Section titled “batch_delete”POST /api/admin/news/batch_delete
Deletes several news posts at once.
Permission: Manage news (news.manage)
| Parameter | Type | Description |
|---|---|---|
ids |
array, required | The ids of the posts to delete. Ids that do not exist are skipped. |
Returns: true.
Errors:
- IDs were not passed (code 9999)
This cannot be undone.
Guest calls
Section titled “Guest calls”get_list (guest)
Section titled “get_list (guest)”POST /api/guest/news/get_list
Lists the posts clients can see: active, past their publish date and not expired. Pinned posts come first, then the newest.
| Parameter | Type | Description |
|---|---|---|
id |
integer | Only the post with this id. |
search |
string | Text to find in the title, slug, description, section or content. |
section |
string | Text to find in the section name. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row has the fields of admin/get, except that author is an empty array.
get (guest)
Section titled “get (guest)”POST /api/guest/news/get
Returns one post clients can see, by id or slug.
| Parameter | Type | Description |
|---|---|---|
id |
integer | The post’s id. Give id or slug; id wins when both are given. |
slug |
string | The post’s slug. |
Returns: The post, with the fields of admin/get.
Errors:
- ID or slug is required. (code 9999)
- News item not found. (code 404) for a post that does not exist, is a draft, is scheduled for later or has expired.
Example
Request parameters:
{ "slug": "planned-maintenance-on-saturday"}result:
{ "id": 12, "title": "Planned maintenance on Saturday", "description": "Our servers get a kernel update on Saturday night.", "content": "<p>Our servers get a kernel update on Saturday night.</p>", "status": "active", "slug": "planned-maintenance-on-saturday", "image": null, "section": "Maintenance", "pinned": true, "publish_at": "2026-11-18 09:00:00", "published_at": null, "expires_at": "2026-11-23 00:00:00", "created_at": "2026-11-17 10:02:11", "updated_at": "2026-11-17 10:02:11", "author": { "name": "Jane Admin" }, "excerpt": null}
