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
}
'

import requests

url = "https://api.sublay.io/api/v6/:projectId/api/v7/push-notifications/send"

payload = {
    "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
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    userIds: ['<string>'],
    title: '<string>',
    body: JSON.stringify('<string>'),
    data: {},
    sound: '<string>',
    badge: 123,
    channelId: '<string>',
    priority: '<string>',
    subtitle: '<string>',
    imageUrl: '<string>',
    tag: '<string>',
    collapseId: '<string>',
    threadId: '<string>',
    ttl: 123,
    mutableContent: true
  })
};

fetch('https://api.sublay.io/api/v6/:projectId/api/v7/push-notifications/send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sublay.io/api/v6/:projectId/api/v7/push-notifications/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sublay.io/api/v6/:projectId/api/v7/push-notifications/send"

	payload := strings.NewReader("{\n  \"userIds\": [\n    \"<string>\"\n  ],\n  \"title\": \"<string>\",\n  \"body\": \"<string>\",\n  \"data\": {},\n  \"sound\": \"<string>\",\n  \"badge\": 123,\n  \"channelId\": \"<string>\",\n  \"priority\": \"<string>\",\n  \"subtitle\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"collapseId\": \"<string>\",\n  \"threadId\": \"<string>\",\n  \"ttl\": 123,\n  \"mutableContent\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sublay.io/api/v6/:projectId/api/v7/push-notifications/send")
  .header("Content-Type", "application/json")
  .body("{\n  \"userIds\": [\n    \"<string>\"\n  ],\n  \"title\": \"<string>\",\n  \"body\": \"<string>\",\n  \"data\": {},\n  \"sound\": \"<string>\",\n  \"badge\": 123,\n  \"channelId\": \"<string>\",\n  \"priority\": \"<string>\",\n  \"subtitle\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"collapseId\": \"<string>\",\n  \"threadId\": \"<string>\",\n  \"ttl\": 123,\n  \"mutableContent\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sublay.io/api/v6/:projectId/api/v7/push-notifications/send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"userIds\": [\n    \"<string>\"\n  ],\n  \"title\": \"<string>\",\n  \"body\": \"<string>\",\n  \"data\": {},\n  \"sound\": \"<string>\",\n  \"badge\": 123,\n  \"channelId\": \"<string>\",\n  \"priority\": \"<string>\",\n  \"subtitle\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"collapseId\": \"<string>\",\n  \"threadId\": \"<string>\",\n  \"ttl\": 123,\n  \"mutableContent\": true\n}"

response = http.request(request)
puts response.read_body

{
  "results": {
    "platform": {},
    "success": true,
    "reason": "<string>"
  }
}

POST

:projectId

api

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
}
'

import requests

url = "https://api.sublay.io/api/v6/:projectId/api/v7/push-notifications/send"

payload = {
    "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
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    userIds: ['<string>'],
    title: '<string>',
    body: JSON.stringify('<string>'),
    data: {},
    sound: '<string>',
    badge: 123,
    channelId: '<string>',
    priority: '<string>',
    subtitle: '<string>',
    imageUrl: '<string>',
    tag: '<string>',
    collapseId: '<string>',
    threadId: '<string>',
    ttl: 123,
    mutableContent: true
  })
};

fetch('https://api.sublay.io/api/v6/:projectId/api/v7/push-notifications/send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sublay.io/api/v6/:projectId/api/v7/push-notifications/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sublay.io/api/v6/:projectId/api/v7/push-notifications/send"

	payload := strings.NewReader("{\n  \"userIds\": [\n    \"<string>\"\n  ],\n  \"title\": \"<string>\",\n  \"body\": \"<string>\",\n  \"data\": {},\n  \"sound\": \"<string>\",\n  \"badge\": 123,\n  \"channelId\": \"<string>\",\n  \"priority\": \"<string>\",\n  \"subtitle\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"collapseId\": \"<string>\",\n  \"threadId\": \"<string>\",\n  \"ttl\": 123,\n  \"mutableContent\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sublay.io/api/v6/:projectId/api/v7/push-notifications/send")
  .header("Content-Type", "application/json")
  .body("{\n  \"userIds\": [\n    \"<string>\"\n  ],\n  \"title\": \"<string>\",\n  \"body\": \"<string>\",\n  \"data\": {},\n  \"sound\": \"<string>\",\n  \"badge\": 123,\n  \"channelId\": \"<string>\",\n  \"priority\": \"<string>\",\n  \"subtitle\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"collapseId\": \"<string>\",\n  \"threadId\": \"<string>\",\n  \"ttl\": 123,\n  \"mutableContent\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sublay.io/api/v6/:projectId/api/v7/push-notifications/send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"userIds\": [\n    \"<string>\"\n  ],\n  \"title\": \"<string>\",\n  \"body\": \"<string>\",\n  \"data\": {},\n  \"sound\": \"<string>\",\n  \"badge\": 123,\n  \"channelId\": \"<string>\",\n  \"priority\": \"<string>\",\n  \"subtitle\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"collapseId\": \"<string>\",\n  \"threadId\": \"<string>\",\n  \"ttl\": 123,\n  \"mutableContent\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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

string[]

required

Array of Sublay user IDs to notify. Between 1 and 100 IDs per request.

string

required

Notification title. Displayed as the bold heading on the device.

string

required

Notification body text.

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).

string

Sound file to play. iOS: APNs sound. Android: governed by the channel on 8+ — pair with channelId. Web: forwarded to the service worker.

number

iOS app-icon badge count (APNs badge). No Android equivalent. The caller supplies the number; Sublay tracks no unread state.

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.

string

"high" or "normal". iOS: APNs apns-priority (10/5). Android: FCM android.priority. high wakes the device for time-sensitive pushes.

string

iOS subtitle line under the title (APNs alert.subtitle).

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.

string

Display-replace key so notifications collapse in the UI (FCM android.notification.tag, Web tag).

string

Transport-level collapse identifier (APNs apns-collapse-id, FCM collapse_key) — supersedes an undelivered push with the same id.

string

iOS notification grouping (APNs thread-id).

number

Time-to-live in seconds for offline devices (APNs apns-expiration computed from now, FCM android.ttl).

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" }
    ]
  }
}

object

Map from user ID to an array of per-device delivery results.

Show per-device result fields

"ios" | "android" | "web"

The platform this result is for.

boolean

Whether the push was accepted by the upstream provider (APNs, FCM, or Web Push).

string

Present only when success is false. Common values:

"credentials_not_configured" — no provider config exists for this platform (or it is disabled)
Provider-specific error codes returned by APNs/FCM/Web Push

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

Invalid Body — 400

{ "error": "...", "code": "push-send/invalid-body" }

Returned when userIds is empty, exceeds 100 entries, or required fields are missing.

Forbidden — 403

{ "error": "Forbidden" }

Returned when called with an end-user access token instead of a service/master key.

Bundle Not Installed — 403

{ "error": "...", "code": "database/tables-not-available" }

Overview

Auth Endpoints

OAuth Endpoints

User Endpoints

User Follow Operations

User Connection Operations

Follow Endpoints

Connection Endpoints

Entity Endpoints

Comment Endpoints

Chat — Conversations

Chat — Members

Chat — Messages

Collection Endpoints

App Notification Endpoints

Push Notification Endpoints

Report Endpoints

Search Endpoints

Space Endpoints

Space — Membership

Space — Rules

Space — Moderation

Space — Chat

Event Endpoints

Storage Endpoints

Utils

Crypto

Send Push Notification

Body Parameters

Rich payload fields

Response

Error Responses

See Also

​Body Parameters

​Rich payload fields

​Response

​Error Responses

​See Also

Body Parameters

Rich payload fields

Response

Error Responses

See Also