API Documentation

Everything you need to integrate PushCloud into your apps, scripts, and services. Send push notifications in seconds with our simple REST API.

Authentication

PushCloud uses two types of credentials:

Application Token — identifies the app sending the notification. Create one in your dashboard under Applications.
User Key — identifies the recipient. Find yours in Settings on the dashboard.

For account management endpoints (messages, devices, settings), authenticate with a session cookie obtained via the login endpoint, or pass your User Key via the Authorization header:

Authorization: Bearer YOUR_USER_KEY

Base URL

All API requests should be made to:

https://pushcloud.bobby.sh/api/v1

Send a Notification

The primary endpoint for sending push notifications to a user.

POST /api/v1/messages/send

Send a push notification to a user's registered devices.

Parameter	Type		Description
token	string	required	Your application token
user	string	required	Recipient's user key
message	string	required	The notification body text
title	string	optional	Notification title (defaults to app name)
priority	integer	optional	-2 to 2 (see priority levels below)
url	string	optional	URL to open when tapped
url_title	string	optional	Label for the URL
sound	string	optional	Sound name (default: "pushcloud")
image_url	string	optional	URL of an image to attach
html	boolean	optional	Enable HTML formatting in message

Example request:

curl -X POST https://pushcloud.bobby.sh/api/v1/messages/send \
  -H "Content-Type: application/json" \
  -d '{
    "token": "app_abc123...",
    "user": "usr_xyz789...",
    "message": "Build #4521 deployed to production",
    "title": "Deploy Complete",
    "priority": 1,
    "url": "https://ci.example.com/builds/4521"
  }'

Response:

{
  "status": 1,
  "request": "msg_1a2b3c..."
}

Quick Send (Pushover-compatible)

A simplified endpoint that's compatible with Pushover's API format, making migration easy.

POST /api/v1/send

Accepts the same parameters as the main send endpoint. Designed as a drop-in replacement for Pushover — just change the URL.

curl -X POST https://pushcloud.bobby.sh/api/v1/send \
  -H "Content-Type: application/json" \
  -d '{
    "token": "app_abc123...",
    "user": "usr_xyz789...",
    "message": "Server CPU at 95%!"
  }'

Priority Levels

Value	Name	Behavior
-2	Lowest	No notification, stored in inbox only
-1	Low	No sound or vibration
0	Normal	Standard notification with sound
1	High	Bypasses quiet hours
2	Critical	Sends as iOS Critical Alert — plays sound even in Do Not Disturb and silent mode

Priority 2 (Critical) requires the user to have enabled Critical Alerts for PushCloud in iOS Settings. These should be reserved for truly urgent notifications.

List Messages

GET /api/v1/messages

Retrieve a paginated list of the authenticated user's messages. Returns the most recent messages first.

Parameter	Type		Description
limit	integer	optional	Number of messages (default 50, max 200)
offset	integer	optional	Pagination offset

Get Message

GET /api/v1/messages/:id

Retrieve a single message by its ID.

Acknowledge Message

POST /api/v1/messages/:id/acknowledge

Mark a priority 2 (critical) message as acknowledged. This stops any repeat alerts for that message.

Archive / Delete Messages

POST /api/v1/messages/:id/archive

Archive a message. Archived messages are hidden from the default inbox view but not permanently deleted.

DELETE /api/v1/messages/:id

Permanently delete a message.

Register Device

POST /api/v1/devices

Parameter	Type		Description
token	string	required	APNs device token
name	string	required	Device name (e.g. "Bobby's iPhone")
model	string	optional	Device model identifier

List Devices

GET /api/v1/devices

List all registered devices for the authenticated user.

Create Application

POST /api/v1/applications

Create a new application and receive an API token for sending notifications.

Parameter	Type		Description
name	string	required	Application name
description	string	optional	What this app is for
icon	string	optional	Icon identifier

List Applications

GET /api/v1/applications

List all applications owned by the authenticated user.

Email Forwarding

PushCloud can convert incoming emails into push notifications. Each user has a unique email alias:

your-alias@pushcloud.bobby.sh

When an email arrives at this address, PushCloud will:

Use the email subject as the notification title
Use the email body (plain text) as the notification message
Deliver it at normal priority to all registered devices

Find your email alias in the Settings section of your dashboard. You can regenerate it at any time if needed.

Email forwarding is perfect for alerts from services that only support email notifications — like cron jobs, monitoring tools, or form submissions.