Skip to main content
POST
/
:projectId
/
api
/
v7
/
push-notifications
/
send
Send Push Notification
curl --request POST \
  --url https://api.sublay.io/api/v6/:projectId/api/v7/push-notifications/send \
  --header 'Content-Type: application/json' \
  --data '
{
  "userIds": [
    "<string>"
  ],
  "title": "<string>",
  "body": "<string>",
  "data": {},
  "sound": "<string>",
  "badge": 123,
  "channelId": "<string>",
  "priority": "<string>",
  "subtitle": "<string>",
  "imageUrl": "<string>",
  "tag": "<string>",
  "collapseId": "<string>",
  "threadId": "<string>",
  "ttl": 123,
  "mutableContent": true
}
'
{
  "results": {
    "platform": {},
    "success": true,
    "reason": "<string>"
  }
}
Fans a push notification out to every registered device belonging to the listed users. The server dispatches to APNs (iOS), FCM (Android), and the Web Push protocol in parallel, using whichever platform credentials are configured for this project. Requires a service or master key (Authorization: Bearer <serviceKey>). End-user tokens are rejected — this endpoint is intended for your backend, not for end users calling it directly. Requires the push bundle.

​
Body Parameters

​
userIds
string[]
required
Array of Sublay user IDs to notify. Between 1 and 100 IDs per request.
​
title
string
required
Notification title. Displayed as the bold heading on the device.
​
body
string
required
Notification body text.
​
data
object
Optional key-value data payload forwarded to the app alongside the notification. Values must be strings or serializable primitives. Use this to pass deep-link targets, IDs, or any context your app needs when the user taps the notification.

​
Rich payload fields

All optional. Each is mapped to whichever platform(s) support it at dispatch time and silently ignored on platforms that have no equivalent. See the Push Notifications guide for the client-side setup some of these require (Android channels, the iOS Notification Service Extension, your web service worker).
​
sound
string
Sound file to play. iOS: APNs sound. Android: governed by the channel on 8+ — pair with channelId. Web: forwarded to the service worker.
​
badge
number
iOS app-icon badge count (APNs badge). No Android equivalent. The caller supplies the number; Sublay tracks no unread state.
​
channelId
string
Android notification channel id (FCM android.notification.channel_id). The channel must be created client-side; on Android 8+ it owns sound/importance/vibration.
​
priority
string
"high" or "normal". iOS: APNs apns-priority (10/5). Android: FCM android.priority. high wakes the device for time-sensitive pushes.
​
subtitle
string
iOS subtitle line under the title (APNs alert.subtitle).
​
imageUrl
string
Rich/big-picture image URL. Android (FCM image) and Web work out of the box. iOS additionally requires a Notification Service Extension in the app — the URL is forwarded in the payload and mutable-content is set automatically.
​
tag
string
Display-replace key so notifications collapse in the UI (FCM android.notification.tag, Web tag).
​
collapseId
string
Transport-level collapse identifier (APNs apns-collapse-id, FCM collapse_key) — supersedes an undelivered push with the same id.
​
threadId
string
iOS notification grouping (APNs thread-id).
​
ttl
number
Time-to-live in seconds for offline devices (APNs apns-expiration computed from now, FCM android.ttl).
​
mutableContent
boolean
iOS mutable-content flag, enabling the app’s Notification Service Extension to modify the payload (e.g. attach imageUrl). Set implicitly when imageUrl is provided.

​
Response

Returns 200 with a results map keyed by user ID. Every requested userId is present in the response — users with no registered devices get an empty array rather than being omitted. 
{
  "results": {
    "usr_abc123": [
      { "platform": "ios", "success": true },
      { "platform": "android", "success": true }
    ],
    "usr_def456": [],
    "usr_ghi789": [
      { "platform": "web", "success": false, "reason": "credentials_not_configured" }
    ]
  }
}
​
results
object
Map from user ID to an array of per-device delivery results.
Devices whose tokens or subscriptions are reported as permanently invalid by the upstream provider (e.g. APNs BadDeviceToken, FCM UNREGISTERED, Web Push HTTP 410) are automatically deleted during the send — no separate cleanup step is needed.

​
Error Responses

{ "error": "...", "code": "push-send/invalid-body" }
Returned when userIds is empty, exceeds 100 entries, or required fields are missing.
{ "error": "Forbidden" }
Returned when called with an end-user access token instead of a service/master key.
{ "error": "...", "code": "database/tables-not-available" }

​
See Also