NUnullplatform
Announcements

Create a notification

Changed on

Creates a notification without an inbox rule: an announcement (kind: broadcast) for everyone in your organization, or a personal notification for a list of users.

Send a key to make retries safe: creating again with the same key answers 200 with the existing notification and creates nothing.

post/communications/notification

Request

  • Base URL
    https://api.nullplatform.com
  • URL
    https://api.nullplatform.com/communications/notification
  • Auth
    HTTP bearer

Request body

kind'broadcast' | 'personal' required

broadcast is an announcement for everyone in your organization, narrowed by audience.grants. personal reaches only the users in recipients.users.

categorystring required

What the notification is about. For an announcement, one of platform.release, platform.changelog, platform.maintenance, platform.incident, platform.advisory, or platform.other. For a personal notification, the ID of an inbox rule your organization sees: people's inbox settings for that rule apply.

titlestring required

The headline. Accepts inline Markdown (**bold**, *italic*, `code`), but no links.

bodystring

Optional text under the title. Accepts Markdown, with https or mailto links.

severity'informational' | 'maintenance' | 'degraded' | 'outage'

Sets the icon and the color of the notification.

nrnstring

The resource the notification is about, inside your organization. Defaults to your organization. An announcement's nrn must be your organization.

keystring

Makes the create idempotent: a later create with the same key returns the existing notification.

group_keystring

Groups notifications into a thread, so you can close them all at once with POST /communications/notification/close.

publish_atstring date-time

When it starts showing. Defaults to now.

expires_atstring date-time

When it stops showing. Defaults to never, until you close it.

Example request

{
  "kind": "broadcast",
  "category": "platform.maintenance",
  "title": "Scheduled maintenance on Saturday",
  "body": "Deployments are paused from 06:00 to 08:00 UTC.",
  "severity": "maintenance",
  "nrn": "organization=1",
  "recipients": {
    "users": [
      12345
    ]
  },
  "audience": {
    "grants": [
      "admin",
      "developer"
    ]
  },
  "surfaces": [
    {
      "type": "banner",
      "sections": [
        "development"
      ],
      "nrn": "organization=1:account=2",
      "dismissible": true
    }
  ],
  "places": [
    {
      "channel": "slack",
      "destination": {
        "channel_id": "C0123456789",
        "channel_name": "announcements"
      }
    }
  ],
  "cta": {
    "label": "See the status page",
    "kind": "link",
    "url": "https://status.example.com"
  },
  "media": {
    "email": {
      "subject": "Maintenance on Saturday"
    }
  },
  "key": "acme.maintenance:2026-11-01",
  "group_key": "acme.incident:inc-2031",
  "publish_at": "2026-10-31T09:00:00Z",
  "expires_at": "2026-11-01T08:00:00Z"
}

Response

A notification with the same key already existed. It's returned unchanged.

idstring uuid

The ID of the notification.

organization_idinteger

Your organization's ID.

kind'broadcast' | 'personal'
categorystring
severity'informational' | 'maintenance' | 'degraded' | 'outage'
status'open' | 'closed'
nrnstring
titlestring
bodystring nullable
audienceobject nullable
ctaobject nullable
mediaobject nullable
keystring nullable
group_keystring nullable
publisher'nullplatform' | 'organization'

organization for your organization's notifications, and nullplatform for the ones nullplatform sends your organization. Only the status of a nullplatform one can change.

publish_atstring date-time nullable
expires_atstring date-time nullable
closed_atstring date-time nullable
closed_byinteger nullable
created_byinteger

The ID of the user who created it.

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "6f1c2b9e-3a41-4f0e-9d55-2b7c1e0a9f13",
  "organization_id": 1,
  "kind": "broadcast",
  "category": "platform.maintenance",
  "severity": "maintenance",
  "status": "open",
  "nrn": "organization=1",
  "title": "Scheduled maintenance on Saturday",
  "surfaces": [
    {
      "type": "banner",
      "sections": [
        "development"
      ],
      "dismissible": true
    }
  ],
  "publisher": "organization",
  "created_by": 12345,
  "created_at": "2026-10-27T14:03:11.000Z",
  "updated_at": "2026-10-27T14:03:11.000Z"
}

Changes