Skip to content

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.

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>"
}

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:

true

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:

12

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.

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.

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.

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
}