---
id: communications-notification-create
title: Create a notification
description: >-
  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.
sidebar_label: Create a notification
hide_title: true
hide_table_of_contents: true
api: >-
  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
sidebar_class_name: post api-method
info_path: docs/api/communications
custom_edit_url: null
canonical: 'https://docs.nullplatform.com/docs/api/communications-notification-create'
---
<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a notification"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/communications/notification"}
  context={"endpoint"}
>

</MethodEndpoint>

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.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={undefined}
>

</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"title":"NotificationCreate","type":"object","description":"The main fields of a notification. `organization_id`, `publisher`, and `created_by` are set by nullplatform.","required":["kind","category","title"],"properties":{"kind":{"type":"string","enum":["broadcast","personal"],"description":"`broadcast` is an announcement for everyone in your organization, narrowed by `audience.grants`. `personal` reaches only the users in `recipients.users`.","example":"broadcast"},"category":{"type":"string","maxLength":60,"description":"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.\n","example":"platform.maintenance"},"title":{"type":"string","maxLength":250,"description":"The headline. Accepts inline Markdown (`**bold**`, `*italic*`, `` `code` ``), but no links.","example":"Scheduled maintenance on Saturday"},"body":{"type":"string","maxLength":2000,"description":"Optional text under the title. Accepts Markdown, with `https` or `mailto` links.","example":"Deployments are paused from 06:00 to 08:00 UTC."},"severity":{"type":"string","enum":["informational","maintenance","degraded","outage"],"default":"informational","description":"Sets the icon and the color of the notification.","example":"maintenance"},"nrn":{"type":"string","maxLength":500,"description":"The resource the notification is about, inside your organization. Defaults to your organization. An announcement's `nrn` must be your organization.","example":"organization=1"},"recipients":{"type":"object","description":"Required for a personal notification. Each user must be able to see the resource at `nrn`.","properties":{"users":{"type":"array","maxItems":5000,"items":{"type":"integer"},"description":"The IDs of the users who receive it.","example":[12345]}}},"audience":{"type":"object","description":"Announcements only. Leave it out to reach everyone in your organization.","properties":{"grants":{"type":"array","maxItems":50,"items":{"type":"string"},"description":"Reach only the people who hold one of these roles.","example":["admin","developer"]}}},"surfaces":{"type":"array","maxItems":5,"description":"Where it shows. Defaults to the bell.","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["inbox","banner"],"description":"`inbox` shows it in the bell, and `banner` as a banner across the product.","example":"banner"},"sections":{"type":"array","items":{"type":"string","enum":["development","platform_settings","insights"]},"description":"Required on a banner: the sections of the product it shows in.","example":["development"]},"nrn":{"type":"string","description":"Banners in the `development` section only: the one resource the banner shows on, within the notification's `nrn`.","example":"organization=1:account=2"},"dismissible":{"type":"boolean","description":"Whether people can dismiss it.","example":true}}}},"places":{"type":"array","maxItems":10,"description":"Announcements only: the Slack channels it's also posted to, each one once. Slack must be connected to your organization.","items":{"type":"object","required":["channel","destination"],"properties":{"channel":{"type":"string","enum":["slack"],"example":"slack"},"destination":{"type":"object","required":["channel_id","channel_name"],"properties":{"channel_id":{"type":"string","example":"C0123456789"},"channel_name":{"type":"string","example":"announcements"}}}}}},"cta":{"type":"object","description":"A button on the notification. A `link` takes a `url`.","required":["label","kind"],"properties":{"label":{"type":"string","maxLength":80,"example":"See the status page"},"kind":{"type":"string","enum":["link","tour"],"example":"link"},"url":{"type":"string","example":"https://status.example.com"}}},"media":{"type":"object","description":"Different wording by email or in Slack. Any field you leave out falls back to the notification's own `title` and `body`.","properties":{"email":{"type":"object","properties":{"subject":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"}}},"slack":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"},"cta":{"type":"boolean","enum":[false],"description":"Set to `false` to leave the button out of Slack."}}}},"example":{"email":{"subject":"Maintenance on Saturday"}}},"key":{"type":"string","maxLength":200,"description":"Makes the create idempotent: a later create with the same key returns the existing notification.","example":"acme.maintenance:2026-11-01"},"group_key":{"type":"string","maxLength":200,"description":"Groups notifications into a thread, so you can close them all at once with `POST /communications/notification/close`.","example":"acme.incident:inc-2031"},"publish_at":{"type":"string","format":"date-time","description":"When it starts showing. Defaults to now.","example":"2026-10-31T09:00:00Z"},"expires_at":{"type":"string","format":"date-time","description":"When it stops showing. Defaults to never, until you close it.","example":"2026-11-01T08:00:00Z"}}}}}}}
>

</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"A notification with the same `key` already existed. It's returned unchanged.","content":{"application/json":{"schema":{"title":"Notification","type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The ID of the notification.","example":"6f1c2b9e-3a41-4f0e-9d55-2b7c1e0a9f13"},"organization_id":{"type":"integer","description":"Your organization's ID.","example":1},"kind":{"type":"string","enum":["broadcast","personal"],"example":"broadcast"},"category":{"type":"string","example":"platform.maintenance"},"severity":{"type":"string","enum":["informational","maintenance","degraded","outage"],"example":"maintenance"},"status":{"type":"string","enum":["open","closed"],"example":"open"},"nrn":{"type":"string","example":"organization=1"},"title":{"type":"string","example":"Scheduled maintenance on Saturday"},"body":{"type":"string","nullable":true},"audience":{"type":"object","nullable":true},"surfaces":{"type":"array","example":[{"type":"banner","sections":["development"],"dismissible":true}]},"places":{"type":"array"},"cta":{"type":"object","nullable":true},"media":{"type":"object","nullable":true},"key":{"type":"string","nullable":true},"group_key":{"type":"string","nullable":true},"publisher":{"type":"string","enum":["nullplatform","organization"],"description":"`organization` for your organization's notifications, and `nullplatform` for the ones nullplatform sends your organization. Only the `status` of a `nullplatform` one can change.","example":"organization"},"publish_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"closed_at":{"type":"string","format":"date-time","nullable":true},"closed_by":{"type":"integer","nullable":true},"created_by":{"type":"integer","description":"The ID of the user who created it.","example":12345},"created_at":{"type":"string","format":"date-time","example":"2026-10-27T14:03:11.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-10-27T14:03:11.000Z"}}}}}},"201":{"description":"The notification was created.","content":{"application/json":{"schema":{"title":"Notification","type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The ID of the notification.","example":"6f1c2b9e-3a41-4f0e-9d55-2b7c1e0a9f13"},"organization_id":{"type":"integer","description":"Your organization's ID.","example":1},"kind":{"type":"string","enum":["broadcast","personal"],"example":"broadcast"},"category":{"type":"string","example":"platform.maintenance"},"severity":{"type":"string","enum":["informational","maintenance","degraded","outage"],"example":"maintenance"},"status":{"type":"string","enum":["open","closed"],"example":"open"},"nrn":{"type":"string","example":"organization=1"},"title":{"type":"string","example":"Scheduled maintenance on Saturday"},"body":{"type":"string","nullable":true},"audience":{"type":"object","nullable":true},"surfaces":{"type":"array","example":[{"type":"banner","sections":["development"],"dismissible":true}]},"places":{"type":"array"},"cta":{"type":"object","nullable":true},"media":{"type":"object","nullable":true},"key":{"type":"string","nullable":true},"group_key":{"type":"string","nullable":true},"publisher":{"type":"string","enum":["nullplatform","organization"],"description":"`organization` for your organization's notifications, and `nullplatform` for the ones nullplatform sends your organization. Only the `status` of a `nullplatform` one can change.","example":"organization"},"publish_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"closed_at":{"type":"string","format":"date-time","nullable":true},"closed_by":{"type":"integer","nullable":true},"created_by":{"type":"integer","description":"The ID of the user who created it.","example":12345},"created_at":{"type":"string","format":"date-time","example":"2026-10-27T14:03:11.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-10-27T14:03:11.000Z"}}}}}},"4XX":{"description":"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).","content":{"application/problem+json":{"schema":{"type":"object","description":"Describes what went wrong, following the RFC 9457 problem details format.","required":["type","title","status"],"properties":{"type":{"type":"string","description":"A URI that identifies the kind of problem. It's an identifier, not a link, and it's the same every time this problem occurs.","example":"urn:nullplatform:error:routes-helper:invalid-params"},"title":{"type":"string","description":"A short, human-readable summary of the problem.","example":"There are invalid parameters on the request"},"status":{"type":"integer","description":"The HTTP status code of the response.","example":400},"code":{"type":"string","description":"A stable, machine-readable error code. Use it to handle specific errors in your integrations.","example":"ROUTES_HELPER.INVALID_PARAMS"},"detail":{"type":"string","nullable":true,"description":"More information about what went wrong in this request, when available.","example":null},"errors":{"type":"array","description":"One entry per invalid field or parameter. Only present on validation errors.","items":{"type":"object","properties":{"field":{"type":"string","description":"The name of the invalid field or parameter.","example":"application_id"},"in":{"type":"string","description":"Where the field was sent: `body`, `query`, or `params` (path parameters).","example":"query"},"issue":{"type":"string","description":"What's wrong with the field, such as `required` or `invalid`.","example":"invalid"},"value":{"description":"The value that was sent, when relevant.","example":"not-a-number"},"message":{"type":"string","description":"A human-readable explanation of the issue."}}}},"message":{"type":"string","deprecated":true,"description":"Same value as `title`, kept for backward compatibility. Use `title` or `code` instead.","example":"There are invalid parameters on the request"},"traceId":{"type":"string","description":"An identifier for this request, when available. Include it when you contact nullplatform support."}}}}}},"5XX":{"description":"Something went wrong on nullplatform's side. The body is a problem details object (RFC 9457).","content":{"application/problem+json":{"schema":{"type":"object","description":"Describes what went wrong, following the RFC 9457 problem details format.","required":["type","title","status"],"properties":{"type":{"type":"string","description":"A URI that identifies the kind of problem. It's an identifier, not a link, and it's the same every time this problem occurs.","example":"about:blank"},"title":{"type":"string","description":"A short, human-readable summary of the problem.","example":"Oops.. there was an internal error"},"status":{"type":"integer","description":"The HTTP status code of the response.","example":500},"code":{"type":"string","description":"A stable, machine-readable error code. Use it to handle specific errors in your integrations."},"detail":{"type":"string","nullable":true,"description":"More information about what went wrong in this request, when available.","example":null},"message":{"type":"string","deprecated":true,"description":"Same value as `title`, kept for backward compatibility. Use `title` or `code` instead.","example":"Oops.. there was an internal error"},"traceId":{"type":"string","description":"An identifier for this request, when available. Include it when you contact nullplatform support."}}}}}}}}
>

</StatusCodes>