Announcements API

Announcements are platform notices we publish: maintenance windows, new features, the occasional heads-up. You can read them and mark them read. That is the whole API - you do not create them.

Every request needs a bearer token. No particular permission: everyone on the account sees the same notices, and the bell in the console's top bar and the Home page read exactly these endpoints.

List announcements

GET /api/announcements

Only currently active announcements - the ones still switched on and not past their expiry - newest first, each flagged read or unread for you:

{
  "data": [
    {
      "id": "6a4d5b83b7006ccae6391860",
      "title": "Scheduled maintenance this weekend",
      "body": "Networking in one region will blip for a few minutes on Saturday between 02:00 and 04:00 UTC. Pods keep running; new connections may be refused during the window.",
      "level": "warning",
      "active": true,
      "expiresAt": "2026-07-20T00:00:00Z",
      "read": false,
      "createdAt": "2026-07-15T10:00:00Z",
      "updatedAt": null
    },
    {
      "id": "6a4d5b83b7006ccae6391861",
      "title": "Backups now restore into a new pod",
      "body": "Restoring a backup no longer touches the original pod. See the backups guide for what changed.",
      "level": "info",
      "active": true,
      "read": true,
      "createdAt": "2026-07-02T08:30:00Z",
      "updatedAt": null
    }
  ],
  "unreadCount": 1
}

level is info, warning, or critical. read is per-user, so marking one read only affects you, not your teammates, and unreadCount counts the unread entries in data. expiresAt is absent on a notice with no end date.

Note the response is not the paginated envelope used elsewhere - there is no page, limit or totalPages, and no way to reach an announcement that is no longer active.

Mark one read

POST /api/announcements/read

{ "id": "6a4d5b83b7006ccae6391860" }

Returns 204 No Content. Marking an announcement you have already read is a no-op, not an error. This is what Dismiss on the console's Home page does: the notice leaves the Home page and stays in the bell and on the Announcements page, marked read.

Mark all read

POST /api/announcements/read-all

No body. Clears your unread count in one shot. Returns 204 No Content.

Example

curl -s https://cloud-api.microapps.io/api/announcements \
  -H "Authorization: Bearer $MICROAPPS_API_KEY" \
  | jq '{unread: .unreadCount, titles: [.data[] | select(.read == false) | .title]}'

Then clear them:

curl -X POST https://cloud-api.microapps.io/api/announcements/read-all \
  -H "Authorization: Bearer $MICROAPPS_API_KEY"

Publishing

A POST /api/announcements route exists, but it is an operator action: it needs a platform admin account, and a customer token gets 403. When we publish one, every active user on every account also gets it by email, unless it is a minor notice we keep to the console.