Pushy Notifications
Overview
Use these routes for two related tasks:
- Managing device tokens and topic subscriptions.
- Sending push notifications to device tokens from a dev-oriented API endpoint.
Relevant routes:
POST /api/v2/device-infoGET /api/v2/device-infoPOST /api/v2/device-info/subscribePOST /api/v2/device-info/unsubscribeGET /api/v2/device-info/topics/{topic}/subscribersPOST /api/v2/notifications/send-dev
All of these routes should be treated as protected and called with:
Authorization: Bearer <access_token>
1. Register Device Token
POST /api/v2/device-info
Stores the current device token for the authenticated user.
This route accepts both plain JSON and the encrypted wrapper payload format described in the overview.
Request
{
"token": "pushy-device-token",
"platform": "ANDROID",
"language": "en"
}
Notes
platformmust be one ofIOS,ANDROID, orWEB.languagecurrently acceptsenorzh.- Registering a token refreshes the active device binding for that user and prevents the same token from remaining active under another user.
Success response
{
"status_code": 201,
"message": "Success",
"data": {
"token": "pushy-device-token",
"platform": "ANDROID"
}
}
2. List Registered Device Tokens
GET /api/v2/device-info
Returns device token rows linked to the authenticated mobile user.
Success response
{
"status_code": 200,
"message": "Success",
"data": [
{
"token": "pushy-device-token",
"platform": "ANDROID"
}
]
}
3. Subscribe a Device Token to Topics
POST /api/v2/device-info/subscribe
Subscribes a token to one or more Pushy topics.
Request
{
"token": "pushy-device-token",
"topics": ["announcements", "system-updates"]
}
Success response
{
"status_code": 200,
"message": "Success",
"data": {
"success": true,
"message": "Successfully subscribed to topics"
}
}
4. Unsubscribe a Device Token
POST /api/v2/device-info/unsubscribe
Unsubscribes a token from specific topics.
Request
{
"token": "pushy-device-token",
"topics": ["announcements"]
}
Notes
- If
topicsis omitted or empty, the handler falls back to["*"]. - Invalid device-token errors are surfaced as a bad request.
5. Inspect Topic Subscribers
GET /api/v2/device-info/topics/{topic}/subscribers
Returns the Pushy device tokens currently subscribed to the requested topic.
Success response
{
"status_code": 200,
"message": "Success",
"data": {
"topic": "announcements",
"subscribers": ["pushy-device-token"]
}
}
6. Send a Dev Push Notification
POST /api/v2/notifications/send-dev
Sends a push notification to one or more device tokens through Pushy.
This route also accepts plain JSON and the encrypted wrapper format.
Request
{
"title": "Balance Updated",
"content": "Your wallet has been credited.",
"to": ["pushy-device-token"],
"action": "wallet_refresh",
"additional_data": {
"wallet_id": 17,
"source": "topup"
}
}
Payload behavior
titleandcontentare required.tomust contain at least one device token.action, when present, is merged into the notification data payload.additional_datais merged into the same Pushy data payload as top-level keys.
Success response
{
"status_code": 200,
"message": "Success",
"data": {
"success": true,
"message": "Notification sent successfully"
}
}
Response note
The API returns only a success flag and message. Detailed delivery diagnostics are not included in this endpoint response.
Current Limits
The current Pushy integration enforces:
- Maximum payload size:
4096bytes - Maximum devices per request:
100000
Common underlying Pushy error mappings:
NO_RECIPIENTSNO_APNS_AUTHPAYLOAD_LIMIT_EXCEEDEDINVALID_DEVICE_TOKEN
If you hit these conditions, the API responds with the project’s normal JSON error envelope.