Messages messages
In-app messages and announcements; admins publish announcements and tenants read and mark them as read.
Pick an endpoint to see its example call on the right.
Authentication
Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.
X-API-Key
Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).
Conventions
Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.
Times are RFC 3339 (UTC); amounts are in cents.
Writes return 200/201/204 on success; duplicates of a unique key return 409.
/api/v2/messagesList messages
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
tenant_ids | string | Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too. Filters only and does not switch the request scope; combined with tenant_id and other filters as an intersection. A tenant credential sending a non-empty value gets 403 |
type | string | Message type, such as announcement or cert-expire. |
site_id | integer | Site ID |
site_ids | string | Filter by sites: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too; combined with other filters as an intersection |
read | boolean | Read filter. false returns unread only (same scope as the bell unread count, announcements excluded) and true returns read only within that scope; omit for no filter. For administrators the state is the administrator's own. |
/api/v2/messagesPublish announcement
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
content | string | Message body. Announcements are sanitized with an allow-list before saving (paragraphs, headings, bold, italic, lists, quotes, http(s) links); scripts, event attributes, images and tables are removed. |
is_external | boolean | When true, clicking jumps to url and url is required; otherwise content is required. |
is_important | boolean | Whether to mark it as important (an "Important" tag before the title). |
is_pinned | boolean | Whether it is pinned. A newly pinned one goes first in the pinned group; reorder with PUT /messages/pin-order. |
is_popup | boolean | Whether to show it as a pop-up. |
is_show | boolean | Whether the message is visible. |
sort | integer | Order within the pinned group (smaller first); meaningful only for pinned announcements. The server puts a newly pinned one first; reorder with PUT /messages/pin-order. |
titleRequired | string | Message title. |
url | string | Link opened on click when is_external is true. |
/api/v2/messages/pin-orderReorder pinned announcements
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
idsRequired | integer[] | Pinned announcement ids in the desired order (first is shown first). |
/api/v2/messages/readMark messages as read
Authentication: User
Request body application/json
| Field | Type | Description |
|---|---|---|
ids | integer[] | Pinned announcement ids in the desired order (first is shown first). |
/api/v2/messages/{id}Get message
Authentication: User (some parameters admin only)
/api/v2/messages/{id}Update message
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
content | string | Message body. Announcements are sanitized with an allow-list before saving (paragraphs, headings, bold, italic, lists, quotes, http(s) links); scripts, event attributes, images and tables are removed. |
is_external | boolean | When true, clicking jumps to url and url is required; otherwise content is required. |
is_important | boolean | Whether to mark it as important (an "Important" tag before the title). |
is_pinned | boolean | Whether it is pinned. A newly pinned one goes first in the pinned group; reorder with PUT /messages/pin-order. |
is_popup | boolean | Whether to show it as a pop-up. |
is_show | boolean | Whether the message is visible. |
sort | integer | Order within the pinned group (smaller first); meaningful only for pinned announcements. The server puts a newly pinned one first; reorder with PUT /messages/pin-order. |
title | string | Message title. |
url | string | Link opened on click when is_external is true. |
/api/v2/messages/{id}Delete message
Authentication: Admin only
Messages object
| Field | Type | Description |
|---|---|---|
content | string | Message body. Announcements are sanitized with an allow-list before saving (paragraphs, headings, bold, italic, lists, quotes, http(s) links); scripts, event attributes, images and tables are removed. |
count | integer | Number of unread messages. |
created_at | string | Created at |
id | integer | Record ID |
idsRequired | integer[] | Pinned announcement ids in the desired order (first is shown first). |
is_external | boolean | When true, clicking jumps to url and url is required; otherwise content is required. |
is_important | boolean | Whether to mark it as important (an "Important" tag before the title). |
is_pinned | boolean | Whether it is pinned. A newly pinned one goes first in the pinned group; reorder with PUT /messages/pin-order. |
is_popup | boolean | Whether to show it as a pop-up. |
is_show | boolean | Whether the message is visible. |
read | boolean | Whether the message has been read. |
read_count | integer | Number of tenants that have read it (tenants only, administrators excluded; returned to administrators only). |
site_id | integer | Site ID |
sort | integer | Order within the pinned group (smaller first); meaningful only for pinned announcements. The server puts a newly pinned one first; reorder with PUT /messages/pin-order. |
tenant_id | integer | Recipient tenant; empty for announcements. |
title | string | Message title. |
title_args | object | Arguments of the title key: name → string, number, or a clause {key, args} (a clause is looked up in the dictionary and filled the same way, and may nest). |
title_key | string | Title key (the Chinese sentence with {name} placeholders). When set, the panel looks it up in the UI-language dictionary and fills the placeholders from title_args; when null (old messages, announcements, edited titles) the panel shows title as is. |
type | string | announcement = announcement; others are notification types (such as cert-expire, package-expire). |
updated_at | string | Updated at |
url | string | Link opened on click when is_external is true. |
Responses and errors
Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"code": "validation_failed",
"detail": "Invalid request parameters",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name is required"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}