1. Creating alerts (Pro+ license)
Administrators with the alerts:create permission can create alerts through:
- The admin API: POST /api/admin/alerts
- Plugins with the alerts:create permission
- Automation rules with an alert step
Required fields
| Field | Description |
|---|---|
| category | Alert category (for example system, maintenance, security) |
| severity | One of critical, warning, info |
| targetType | One of broadcast, role, user |
| title | Short notification title |
| message | Notification body text |
Optional fields
| Field | Description |
|---|---|
| targetValue | Role names or user IDs (required for role and user targeting) |
| imageUrl | URL of an image to show with the alert |
| modalContent | Rich content for a modal view |
| actions | Action buttons: [{label, labelKey, url, style}]. An action's url must be a path in the Wiki (such as /spaces) or an https:// address; anything else is refused with a validation error |
| titleKey, messageKey | Message keys from the Wiki's interface to show instead of title and message, in each person's language. title and message are still required: they are shown when a key isn't known and returned to API clients |
| params | Values for the placeholders in those messages: names mapped to text or numbers (up to 20) |
| metadata | Any JSON metadata |
| expiresAt | ISO 8601 time after which the alert is hidden |
Example: a broadcast alert
curl -X POST https://wiki.example.com/api/admin/alerts \
-H "Authorization: Bearer $WIKI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"category": "maintenance",
"severity": "warning",
"targetType": "broadcast",
"title": "Planned maintenance",
"message": "The wiki will be read-only from 02:00 to 02:30 UTC tonight.",
"actions": [{"label": "Read more", "url": "/spaces"}]
}'
Example: alert some roles
curl -X POST https://wiki.example.com/api/admin/alerts \
-H "Authorization: Bearer $WIKI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"category": "announcements",
"severity": "info",
"targetType": "role",
"targetValue": ["org_admin"],
"title": "New space templates",
"message": "Space admins can now copy templates between spaces."
}'
Alerts that administrators and plugins write are shown exactly as written; they are not translated unless they name message keys.
2. Forced categories (Enterprise license)
Administrators with the alerts:admin permission can set forced categories: categories people can't mute in their own notification preferences. Use them for alerts everyone must see, such as security notices or announcements about the service.
- See the current list of forced categories
- Add one (type the name and select Add, or press Enter)
- Remove one (select its ×)
- Select Save changes
# Current forced categories
GET /api/admin/alerts/config
# Change them
PUT /api/admin/alerts/config
{
"forcedCategories": ["security", "maintenance"]
}
3. Viewing all alerts (Enterprise license)
Administrators with alerts:admin can list every alert in the installation, whoever it was sent to, filtered by category, severity and target type:
GET /api/admin/alerts?category=system&severity=critical&limit=50
4. Alerts the Wiki sends by itself
- People's own work: a watched page was published, someone mentioned you, commented, asked you for a review or answered one, a review or review-by date passed, a scheduled publish failed or changed, a reader left feedback on a page, and in Q&A an answer, comment, accepted answer, mention or new question in a tag you follow. These are info alerts to one person each, in their language, with a button to the page or question. See Alerts.
- System health: the system check and cluster health share one System health alert, tuned under Alert tuning.
- Scheduled jobs: when a job fails several times in a row (3 by default, SCHEDULER_UNHEALTHY_THRESHOLD), super admins and organization admins get Job failing (critical), and Job recovered (info) when it succeeds again. Both link to Settings → Advanced → Scheduled jobs. They are built-in automation rules: super admins can change who gets them or switch them off. Each job has its own category ("Scheduled job: <name>"), so muting it mutes that one job's health alerts.
- Backups: a backup that can't be written or fails its check, and a failed restore or test restore, send super admins a critical alert with the reason. See Backups.
- Plugins: a plugin that is paused after failing, or that passes its storage quota, alerts super admins. See Plugins.
5. Automatic cleanup
The alert-cleanup job (daily at 02:00 UTC, see Scheduled jobs) removes alerts by state:
| State | Kept for |
|---|---|
| Active (unread) | 30 days |
| Read | 7 days |
| Cleared | 1 day |
| Superseded | 3 days |
6. Audit trail
Creating alerts (who, and what was sent) and changes to forced categories (before and after) are recorded in the audit log.
7. API reference
Your own alerts
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/alerts?status= | Your alerts (paginated): your inbox, or status=unread or status=cleared |
| GET | /api/alerts/counts | How many are unread, in your inbox and cleared |
| POST | /api/alerts/{id}/read | Mark an alert read |
| POST | /api/alerts/{id}/unread | Mark an alert unread |
| POST | /api/alerts/{id}/restore | Put a cleared alert back in your inbox |
| POST | /api/alerts/read-all | Mark all read |
| POST | /api/alerts/bulk | Mark several of your alerts read or unread, clear or restore them: {"ids": [1, 2], "action": "read"} (read, unread, clear or restore; up to 500 ids). Ids that aren't yours are skipped; the answer is {"updated": n} |
| POST | /api/alerts/{id}/clear | Clear an alert |
| POST | /api/alerts/clear-all | Clear all alerts |
| GET | /api/alerts/preferences | Your preferences |
| PUT | /api/alerts/preferences | Change your preferences: {"optedOut": false, "mutedCategories": ["announcements"]}. A forced category in mutedCategories is dropped; the answer shows what applies |
Admin
| Method | Endpoint | Permission | License |
|---|---|---|---|
| POST | /api/admin/alerts | alerts:create | Pro+ |
| GET | /api/admin/alerts | alerts:admin | Enterprise |
| GET | /api/admin/alerts/config | alerts:admin | Any |
| PUT | /api/admin/alerts/config | alerts:admin | Enterprise |
Lists are paginated with cursors: the answer has pagination.nextCursor and hasNext; pass ?cursor=<nextCursor>&limit=20 for the next page.
| Status | Meaning |
|---|---|
| 400 | Invalid request (missing fields, bad cursor) |
| 401 | Not signed in |
| 402 | The feature needs a higher license tier |
| 403 | Missing permission |
| 404 | Alert not found |
| 422 | A policy or plugin refused the alert |
8. Live updates
Browsers get new alerts at once over a WebSocket at /api/ws, signed in with the session cookie. Each message is JSON with a type, payload and timestamp:
| Type | Description |
|---|---|
| alert.init | Current alerts and count, sent on connect |
| alert.new | A new alert for you |
| alert.count | The unread count changed |
| alert.superseded | An alert was replaced by a newer one |
If the connection drops, the browser reconnects with growing delays (1 s, 2 s, 4 s… up to 30 s) and gets a fresh alert.init. If your reverse proxy doesn't pass /api/ws through, alerts refresh every 30 seconds instead and the system check warns about it.