System Announcements

A system announcement is a banner an administrator writes once and every user of the installation sees: planned maintenance, an incident in progress, a new release, an upcoming event.

The banner sits above the whole working area rather than inside one page. That is deliberate: somebody who is in the mock editor when the notice goes up needs to see the maintenance warning right there, without navigating anywhere.

Four kinds

The kind decides both how the banner looks and whether dismissing it is final.

Maintenance and incident notices returning is not a bug. Somebody who dismissed the banner on Monday still needs to know on Tuesday morning that the platform stops at noon.

Within one installation, dismissal is remembered per person, not per browser: opening that installation from two computers does not mean closing the same banner twice. Separate Desktop installations keep their own local Cloud notice state.

Publishing

Publishing is for administrators. The message reaches everybody it is addressed to, so both publishing and withdrawing are written to the audit trail — it is always visible who put a notice up.

curl -X POST http://localhost:5770/api/v1/admin/announcements \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "maintenance",
    "title": "Planned maintenance",
    "body": "The platform will be unavailable from 02:00 to 03:00 UTC. No data is affected.",
    "link_label": "Details",
    "link_url": "https://status.example.com/maintenance/1",
    "starts_at": "2026-09-04T02:00:00Z",
    "ends_at": "2026-09-04T03:30:00Z"
  }'

The response carries the id you will need to withdraw it.

What matters about the fields:

• title and body are plain text. Markup is shown as letters, not rendered. Write sentences, not HTML.
• A link is a pair. Both link_label and link_url are needed: a label with no address is a dead button, an address with no label is an unexplained click. Only http:// and https:// are accepted.
• The window is UTC. The banner appears by itself at starts_at and disappears by itself at ends_at. Publishing ahead of time is fine — nothing is shown before the window opens.
• Title up to 160 characters, body up to 2000.

When something is wrong, the answer names the field instead of sending you hunting:

{"error":"invalid_announcement","message":"announce: invalid announcement: the link must be an http(s) address"}

Who sees it

By default everybody does — that is the normal case and needs no configuration. When you need to narrow it, there are three independent filters:

{
  "audience_roles": ["admin"],
  "audience_namespaces": ["prod"],
  "audience_surfaces": ["desktop"]
}

• audience_roles — only readers holding that role.
• audience_namespaces — only readers looking at that namespace. Somebody without access to it never sees the announcement, whatever they ask for.
• audience_surfaces — platform (the web UI) or desktop (the desktop app).

An empty list means everybody. Filters combine: an announcement for role admin and namespace prod reaches only an administrator working in prod.

The filtering happens on the server. An announcement that is not addressed to you never reaches your browser at all.
The Dismiss action also accepts only a currently visible announcement addressed to you; knowing another announcement’s ID does not let you hide it.

Withdrawing

The work finished early, or the notice turned out to be wrong:

curl -X DELETE http://localhost:5770/api/v1/admin/announcements/$ID \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

This is not a delete: what people already saw stays on the record, and the withdrawal is audited.

To see what is scheduled and what has already run:

curl http://localhost:5770/api/v1/admin/announcements \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

Through an AI agent

An agent that takes the installation down for maintenance should be able to warn people itself — otherwise its maintenance window is a silent outage. The MCP tools:

• announcements_publish — put a banner up. Only kind, title and body are required: with no window given it defaults to “now, for six hours”, which is what an incident notice wants.
• announcements_list — see what is up and find an id.
• announcements_withdraw — take one down by id when the work is done.

Installations without internet access

Announcements are stored in the installation itself. An isolated deployment needs to reach nothing to warn its own users about planned work — the mechanic runs entirely locally, identically on PostgreSQL and SQLite.

When Desktop is connected to Cloud, it also shows Cloud notices addressed to the active signed-in profile. The last successfully received Cloud notices remain available without a network connection while that profile is still signed in. Switching profiles or signing out hides the previous profile’s notices; notices published by the local installation remain visible. Dismissing a Cloud notice in one profile does not dismiss it in another.