Coming soon. The Wiki is in active development, so features and these docs may still change. Early adopters: contact us for access.

Managing Alerts

Send alerts, force categories, the alerts the Wiki sends by itself, and the alerts API

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

FieldDescription
categoryAlert category (for example system, maintenance, security)
severityOne of critical, warning, info
targetTypeOne of broadcast, role, user
titleShort notification title
messageNotification body text

Optional fields

FieldDescription
targetValueRole names or user IDs (required for role and user targeting)
imageUrlURL of an image to show with the alert
modalContentRich content for a modal view
actionsAction 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, messageKeyMessage 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
paramsValues for the placeholders in those messages: names mapped to text or numbers (up to 20)
metadataAny JSON metadata
expiresAtISO 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:

StateKept for
Active (unread)30 days
Read7 days
Cleared1 day
Superseded3 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

MethodEndpointDescription
GET/api/alerts?status=Your alerts (paginated): your inbox, or status=unread or status=cleared
GET/api/alerts/countsHow many are unread, in your inbox and cleared
POST/api/alerts/{id}/readMark an alert read
POST/api/alerts/{id}/unreadMark an alert unread
POST/api/alerts/{id}/restorePut a cleared alert back in your inbox
POST/api/alerts/read-allMark all read
POST/api/alerts/bulkMark 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}/clearClear an alert
POST/api/alerts/clear-allClear all alerts
GET/api/alerts/preferencesYour preferences
PUT/api/alerts/preferencesChange your preferences: {"optedOut": false, "mutedCategories": ["announcements"]}. A forced category in mutedCategories is dropped; the answer shows what applies

Admin

MethodEndpointPermissionLicense
POST/api/admin/alertsalerts:createPro+
GET/api/admin/alertsalerts:adminEnterprise
GET/api/admin/alerts/configalerts:adminAny
PUT/api/admin/alerts/configalerts:adminEnterprise

Lists are paginated with cursors: the answer has pagination.nextCursor and hasNext; pass ?cursor=<nextCursor>&limit=20 for the next page.

StatusMeaning
400Invalid request (missing fields, bad cursor)
401Not signed in
402The feature needs a higher license tier
403Missing permission
404Alert not found
422A 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:

TypeDescription
alert.initCurrent alerts and count, sent on connect
alert.newA new alert for you
alert.countThe unread count changed
alert.supersededAn 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.