Documentation

  1. Home
  2. Documentation
Need Help?

Visit the support center for answers to common questions and for ways to get in touch.

Got Feedback?

We'd love to hear what you have to say about our documentation. Let us know how we can improve it.

API Reference

The Pushy API is a HTTPS API that accepts and returns JSON.

Host
https://api.pushy.me
API Endpoints

Push APIs

Name Method Endpoint
Send Notifications API POST /push
Send push notifications to your users.
Notification Status API GET /pushes/PUSH_ID
Check the delivery status of your push notifications.
Notification Deletion API DELETE /pushes/PUSH_ID
Permanently delete a pending notification.

Device APIs

Name Method Endpoint
Device Info API GET /devices/TOKEN
Retrieve device info, presence, pending notifications, etc.
Device Presence API POST /devices/presence
Retrieve device presence and connectivity status in bulk.

Pub/Sub APIs

Name Method Endpoint
Pub/Sub Topics API GET /topics
Retrieve a list of your app's topics and subscribers count.
Pub/Sub Subscribers API GET /topics/TOPIC
Retrieve a list of devices subscribed to a certain topic.
Pub/Sub Subscribe API POST /topics/subscribe
Subscribe a device to one or more topics.
Pub/Sub Unsubscribe API POST /topics/unsubscribe
Unsubscribe a device from one or more topics.
Authentication

All requests must include an ?api_key= query parameter: 

POST https://api.pushy.me/example?api_key=SECRET_API_KEY

Note: Make sure to replace SECRET_API_KEY with your app's Secret API Key, available in the Pushy Dashboard (Click your app -> API Authentication tab). Never expose your application's Secret API Key in your client code. All Pushy APIs are backend APIs.

API Request Body

For API endpoints that accept POST body, send the request body in JSON format: 

POST /push?api_key=6a547f1e7fa1dca83ec11a9210b99dfc87f3935b12415
Content-type: application/json

{
    "to": "a6345d0278adc55d3474f5",
    "data": {
        "message": "Hello World!"
    },
    "notification": {
        "title": "Test Notification",
        "body": "Hello World \u270c",
        "badge": 1,
        "sound": "ping.aiff"
    }
}

Note: Please make sure to send the Content-type: application/json header with your request.

API Response

The Pushy API returns a 200 OK status code with JSON response: 

HTTP/1.1 200 OK
Content-type: application/json

{
    "success": true
}
API Error Handling

If the request fails, a non-200 OK status code is returned with a JSON encoded error: 

HTTP/1.1 403 Forbidden
Content-type: application/json
                                    
{
    "code": "INVALID_API_KEY",
    "error":"The Secret API Key you used to authenticate is invalid."
}
Error Schema
Field Description
code A constant reference string for the specified error (see below).
error A helpful description string on what caused the error to help you resolve it.
Error Codes
Error code Description HTTP status code
INVALID_PARAM An API parameter is missing or invalid (see returned error for more details). 400 Bad Request
INVALID_API_KEY The SECRET_API_KEY you used to authenticate is invalid. 403 Forbidden
AUTH_LIMIT_EXCEEDED Too many attempts have been made to authentiate against the API with an invalid SECRET_API_KEY in the past hour. 403 Forbidden
ACCOUNT_SUSPENDED Your account has been suspended due to a billing issue or platform abuse. 403 Forbidden
RATE_LIMIT_EXCEEDED Your account has exceeed the 800 requests per minute limit (see below). 429 Too Many Requests
INTERNAL_SERVER_ERROR Returned in the rare event of an unexpected uptime incident on our end. 500 Internal Server Error

Note: Please check each individual API endpoint's documentation page for endpoint-specific error codes.

API Rate Limit

By default, the API is rate-limited to 800 requests per minute (about 13 per second). Exceeding the limit will cause requests to fail with 429 Too Many Requests.

Note: You are not limited to sending just 800 notifications per minute, since you can target multiple users/devices in a single API request by specifying multiple device tokens or sending to a Pub/Sub topic.

More info is available in the support center.

API Service Status

We routinely monitor the API for elevated error rates and high latency, and publish any service degradation incidents to status.pushy.me.

Send Notifications API