Send a notification
/notificationsSends an in-app notification and a push to users or to every active user of the user_types (both is a 422). Recipients must be active users of the token organisation, not linked ones, else 422. url must be a platform path (one leading /). description is push only; is_download needs url. 202 with a job: result.recipient_count is those targeted, result.sent_count those sent to (a user suspended after the request is still sent to). Polling Location needs jobs:read. dry_run: 202, no job. No webhook. It can't be undone.
Query parameters
Validate and run the call without committing it, returning what the real call would return with
meta.dry_runset.
Headers
Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.
Request body
application/json, required · NotificationSend
The headline.
Where the notification leads, a path on the platform that starts with a single
/(not//, no spaces or backslashes), else 422. Required when is_download is true.- Default:
Whether the url is a document to download rather than a page to open.
false The body of the push notification. It is never stored and never shown in-app.
The ids of the users to send to. Each must be an active user of the token organisation; users of its linked organisations are refused.
- One of:
Send to every active user of the token organisation of these types (not its linked organisations):
investorfor investors,internalfor internal users,entrepreneurfor entrepreneurs.investor,internal,entrepreneur
{
"title": "The Q3 report is ready",
"url": "/reporting/portfolio/documents",
"is_download": false,
"description": "Open the app to read it.",
"user_types": [
"investor"
]
}Responses
{
"data": {
"id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
"type": "notification-send",
"status": "queued",
"progress": {
"done": 0,
"total": 2
},
"result": {
"recipient_count": 2
},
"error": null,
"created_at": "2026-11-09T12:00:00Z",
"updated_at": "2026-11-09T12:00:00Z",
"completed_at": null
}
}Authorization failed. error.code is one of org_disabled,
ip_blocked, missing_scope, scope_disabled, user_disabled.
The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per
problem, or a code documented on the operation.
Examples
curl -X POST https://your-org-domain/kong/core/api/v2/notifications\
-H "Authorization: Bearer $HELM_API_KEY"\
-H "Content-Type: application/json"\
-d '{
"title": "The Q3 report is ready",
"url": "/reporting/portfolio/documents",
"is_download": false,
"description": "Open the app to read it.",
"user_types": [
"investor"
]
}'