---
title: "Create a notification"
method: POST
path: "/communications/notification"
tags: ["Announcements"]
---

# Create a notification

`POST /communications/notification`

## Request

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

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.

## Request body

- NotificationCreate: The main fields of a notification. `organization_id`, `publisher`, and `created_by` are set by nullplatform.
  - `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`.
  - `category` string, 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.
  - `title` string, required: The headline. Accepts inline Markdown (`**bold**`, `*italic*`, `` `code` ``), but no links.
  - `body` string: 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.
  - `nrn` string: The resource the notification is about, inside your organization. Defaults to your organization. An announcement's `nrn` must be your organization.
  - `recipients` object: Required for a personal notification. Each user must be able to see the resource at `nrn`.
    - `users` integer[]: The IDs of the users who receive it.
  - `audience` object: Announcements only. Leave it out to reach everyone in your organization.
    - `grants` string[]: Reach only the people who hold one of these roles.
  - `surfaces` object[]: Where it shows. Defaults to the bell.
    - `type` 'inbox' | 'banner', required: `inbox` shows it in the bell, and `banner` as a banner across the product.
    - `sections` string[]: Required on a banner: the sections of the product it shows in.
    - `nrn` string: Banners in the `development` section only: the one resource the banner shows on, within the notification's `nrn`.
    - `dismissible` boolean: Whether people can dismiss it.
  - `places` object[]: Announcements only: the Slack channels it's also posted to, each one once. Slack must be connected to your organization.
    - `channel` 'slack', required
    - `destination` object, required
      - `channel_id` string, required
      - `channel_name` string, required
  - `cta` object: A button on the notification. A `link` takes a `url`.
    - `label` string, required
    - `kind` 'link' | 'tour', required
    - `url` string
  - `media` object: Different wording by email or in Slack. Any field you leave out falls back to the notification's own `title` and `body`.
    - `email` object
      - `subject` string
      - `title` string
      - `body` string
    - `slack` object
      - `title` string
      - `body` string
      - `cta` false: Set to `false` to leave the button out of Slack.
  - `key` string: Makes the create idempotent: a later create with the same key returns the existing notification.
  - `group_key` string: Groups notifications into a thread, so you can close them all at once with `POST /communications/notification/close`.
  - `publish_at` string, date-time: When it starts showing. Defaults to now.
  - `expires_at` string, date-time: When it stops showing. Defaults to never, until you close it.

## Response `200`

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

- Notification
  - `id` string, uuid: The ID of the notification.
  - `organization_id` integer: Your organization's ID.
  - `kind` 'broadcast' | 'personal'
  - `category` string
  - `severity` 'informational' | 'maintenance' | 'degraded' | 'outage'
  - `status` 'open' | 'closed'
  - `nrn` string
  - `title` string
  - `body` string, nullable
  - `audience` object, nullable
  - `surfaces` unknown[]
    - unknown
  - `places` unknown[]
    - unknown
  - `cta` object, nullable
  - `media` object, nullable
  - `key` string, nullable
  - `group_key` string, 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_at` string, date-time, nullable
  - `expires_at` string, date-time, nullable
  - `closed_at` string, date-time, nullable
  - `closed_by` integer, nullable
  - `created_by` integer: The ID of the user who created it.
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `201`: The notification was created.
- `4XX`: The request couldn't be processed. For example, a parameter is invalid, the resource doesn't exist, or you don't have permission. The body is a problem details object (RFC 9457).
- `5XX`: Something went wrong on nullplatform's side. The body is a problem details object (RFC 9457).

## Changes

- **2026-10-27** `c0f507ec6087`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nullplatform/apis/nullplatform-api/changes/communications/notification/post.md)

---

[API](https://skmtc.dev/nullplatform/apis/nullplatform-api.md) - [All operations](https://skmtc.dev/nullplatform/apis/nullplatform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nullplatform/apis/nullplatform-api/revisions/d3f66bc633d4?raw)