API documentation

Quick start

1 Create an account to get your user key — the address messages are sent to.
2 Install the iOS app and sign in, so your device can receive notifications.
3 Create an application to get an API token, then send:

curl -s https://veloxipush.planthelper.org/1/messages.json \
  -F token=YOUR_APP_TOKEN \
  -F user=YOUR_USER_KEY \
  -F title='Deploy finished' \
  -F message='Build 412 is live.'

const response = await fetch('https://veloxipush.planthelper.org/1/messages.json', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    token: 'YOUR_APP_TOKEN',
    user: 'YOUR_USER_KEY',
    title: 'Deploy finished',
    message: 'Build 412 is live.',
  }),
});

const result = await response.json();

if (result.status !== 1) {
  throw new Error(result.errors.join(', '));
}

import requests

response = requests.post('https://veloxipush.planthelper.org/1/messages.json', data={
    'token': 'YOUR_APP_TOKEN',
    'user': 'YOUR_USER_KEY',
    'title': 'Deploy finished',
    'message': 'Build 412 is live.',
}, timeout=15)

result = response.json()

if result['status'] != 1:
    raise RuntimeError(', '.join(result['errors']))

$ch = curl_init('https://veloxipush.planthelper.org/1/messages.json');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'token' => 'YOUR_APP_TOKEN',
        'user' => 'YOUR_USER_KEY',
        'title' => 'Deploy finished',
        'message' => 'Build 412 is live.',
    ],
]);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($result['status'] !== 1) {
    throw new RuntimeException(implode(', ', $result['errors']));
}

Authentication

Every request carries two identifiers. They are different things and both are required.

Field	What it identifies
`token`	Who is sending. Created per application in your dashboard, so a leaked token can be rotated without touching your other integrations. Treat it as a password.
`user`	Who receives. A user key, or a group key to fan out to a whole team. Safe to share with anyone you want to be able to notify you.

The token may travel as a normal parameter, or as a bearer header if you prefer:

Authorization: Bearer YOUR_APP_TOKEN

Request bodies may be multipart/form-data, application/x-www-form-urlencoded or application/json.

Send a message

POST https://veloxipush.planthelper.org/1/messages.json

A successful call returns:

{"status":1,"request":"9f1c3e2a-…"}

The response comes back as soon as the message is stored and queued — delivery happens immediately afterwards on a worker, so a slow device never slows down your script. The request id is also returned in the X-Request-Id header; quote it if you ever need to ask about a specific delivery.

Parameters

Name	Required	Description
`token`	required	Your application's API token.
`user`	required	A user key or a group key.
`message`	required	The body. Up to 1024 characters.
`title`	optional	Up to 250 characters. Defaults to the application name.
`priority`	optional	-2 to 2. Defaults to 0. See below.
`sound`	optional	One of the sound names below.
`device`	optional	Comma-separated device names, to target instead of all devices.
`url`	optional	A supplementary URL, up to 512 characters.
`url_title`	optional	Link text shown instead of the raw URL.
`timestamp`	optional	Unix timestamp to display instead of the receipt time.
`ttl`	optional	Seconds after which the message disappears. Ignored for emergency.
`html`	optional	Set to 1 to allow a small subset of HTML in the body.
`monospace`	optional	Set to 1 to render in a monospace font. Cannot combine with html.
`attachment`	optional	An image file, up to 5 MB.
`attachment_base64`	optional	The same image inline. Requires attachment_type.
`retry`	priority 2	Seconds between re-deliveries. Minimum 30.
`expire`	priority 2	Seconds before giving up. Maximum 10800.
`callback`	optional	URL called when an emergency message is acknowledged or expires.

Priority

-2 Lowest

Stored and synced to the app, but raises no notification at all. Useful for logging a stream of events you want to browse later.

-1 Low

Shows a banner without sound or vibration.

0 Normal

Normal. Banner and sound, unless the recipient is inside their quiet hours.

1 High

Delivered as time-sensitive and bypasses quiet hours.

2 Emergency

Emergency. Repeats every retry seconds until acknowledged, or until expire passes. Requires both.

Emergency messages and receipts

A priority 2 message keeps arriving until a human deals with it. The send response includes a receipt token you can poll, and an optional callback URL we POST to the moment it is acknowledged or expires.

# Repeats every 60s for up to an hour, until acknowledged.
curl -s https://veloxipush.planthelper.org/1/messages.json \
  -F token=YOUR_APP_TOKEN \
  -F user=YOUR_USER_KEY \
  -F message='Database primary is down.' \
  -F priority=2 \
  -F retry=60 \
  -F expire=3600

# -> {"status":1,"request":"...","receipt":"aBc123..."}

# Poll whether anyone has acknowledged it yet.
curl -s 'https://veloxipush.planthelper.org/1/receipts/RECEIPT.json?token=YOUR_APP_TOKEN'

const send = await fetch('https://veloxipush.planthelper.org/1/messages.json', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    token: 'YOUR_APP_TOKEN',
    user: 'YOUR_USER_KEY',
    message: 'Database primary is down.',
    priority: 2,
    retry: 60,     // seconds between re-deliveries
    expire: 3600,  // give up after an hour
  }),
});

const { receipt } = await send.json();

// Later: has anyone acknowledged it?
const status = await fetch(
  `https://veloxipush.planthelper.org/1/receipts/${receipt}.json?token=YOUR_APP_TOKEN`
).then((r) => r.json());

console.log(status.acknowledged === 1 ? 'Someone is on it' : 'Still ringing');

import requests

send = requests.post('https://veloxipush.planthelper.org/1/messages.json', data={
    'token': 'YOUR_APP_TOKEN',
    'user': 'YOUR_USER_KEY',
    'message': 'Database primary is down.',
    'priority': 2,
    'retry': 60,     # seconds between re-deliveries
    'expire': 3600,  # give up after an hour
}, timeout=15)

receipt = send.json()['receipt']

# Later: has anyone acknowledged it?
status = requests.get(
    f'https://veloxipush.planthelper.org/1/receipts/{receipt}.json',
    params={'token': 'YOUR_APP_TOKEN'},
    timeout=15,
).json()

print('Someone is on it' if status['acknowledged'] else 'Still ringing')

$ch = curl_init('https://veloxipush.planthelper.org/1/messages.json');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'token' => 'YOUR_APP_TOKEN',
        'user' => 'YOUR_USER_KEY',
        'message' => 'Database primary is down.',
        'priority' => 2,
        'retry' => 60,     // seconds between re-deliveries
        'expire' => 3600,  // give up after an hour
    ],
]);

$receipt = json_decode(curl_exec($ch), true)['receipt'];
curl_close($ch);

// Later: has anyone acknowledged it?
$status = json_decode(file_get_contents(
    'https://veloxipush.planthelper.org/1/receipts/' . $receipt . '.json?token=YOUR_APP_TOKEN'
), true);

echo $status['acknowledged'] ? 'Someone is on it' : 'Still ringing';

Receipt endpoints

GET	`/1/receipts/{token}.json`	Whether it has been acknowledged, by whom, and when.
POST	`/1/receipts/{token}/cancel.json`	Stop retrying without marking it acknowledged — for when the condition cleared on its own.

A receipt is only visible to the application that created it.

Attachments and links

Attach a JPEG, PNG, GIF or WebP up to 5 MB, and add a URL the notification can open.

curl -s https://veloxipush.planthelper.org/1/messages.json \
  -F token=YOUR_APP_TOKEN \
  -F user=YOUR_USER_KEY \
  -F title='New signup' \
  -F message='<b>Ada Lovelace</b> just started a trial.' \
  -F html=1 \
  -F url='https://dashboard.example.com/users/42' \
  -F url_title='Open in dashboard' \
  -F sound=cashregister \
  -F attachment=@chart.png

import { readFile } from 'node:fs/promises';

const form = new FormData();

form.set('token', 'YOUR_APP_TOKEN');
form.set('user', 'YOUR_USER_KEY');
form.set('title', 'New signup');
form.set('message', '<b>Ada Lovelace</b> just started a trial.');
form.set('html', '1');
form.set('url', 'https://dashboard.example.com/users/42');
form.set('url_title', 'Open in dashboard');
form.set('sound', 'cashregister');

const chart = await readFile('chart.png');
form.set('attachment', new Blob([chart]), 'chart.png');

await fetch('https://veloxipush.planthelper.org/1/messages.json', { method: 'POST', body: form });

import requests

with open('chart.png', 'rb') as attachment:
    requests.post('https://veloxipush.planthelper.org/1/messages.json', data={
        'token': 'YOUR_APP_TOKEN',
        'user': 'YOUR_USER_KEY',
        'title': 'New signup',
        'message': '<b>Ada Lovelace</b> just started a trial.',
        'html': 1,
        'url': 'https://dashboard.example.com/users/42',
        'url_title': 'Open in dashboard',
        'sound': 'cashregister',
    }, files={'attachment': attachment}, timeout=30)

$ch = curl_init('https://veloxipush.planthelper.org/1/messages.json');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'token' => 'YOUR_APP_TOKEN',
        'user' => 'YOUR_USER_KEY',
        'title' => 'New signup',
        'message' => '<b>Ada Lovelace</b> just started a trial.',
        'html' => 1,
        'url' => 'https://dashboard.example.com/users/42',
        'url_title' => 'Open in dashboard',
        'sound' => 'cashregister',
        'attachment' => new CURLFile('chart.png', 'image/png'),
    ],
]);

curl_exec($ch);
curl_close($ch);

Sounds

Pass any of these as sound. Also available as JSON from GET https://veloxipush.planthelper.org/1/sounds.json, which needs no token.

veloxi VeloxiPush

bike Bike

bugle Bugle

cashregister Cash Register

classical Classical

cosmic Cosmic

falling Falling

gamelan Gamelan

incoming Incoming

intermission Intermission

magic Magic

mechanical Mechanical

pianobar Piano Bar

siren Siren

spacealarm Space Alarm

tugboat Tug Boat

alien Alien Alarm

climb Climb

persistent Persistent

echo Echo

updown Up Down

vibrate Vibrate Only

none Silent

Validating a key

Confirm a user or group key exists and has a device attached, before wiring it into something that runs unattended.

curl -s https://veloxipush.planthelper.org/1/users/validate.json \
  -F token=YOUR_APP_TOKEN \
  -F user=YOUR_USER_KEY

Returns the device names the key can address. A key with no active devices is reported as an error rather than accepting messages that would go nowhere.

Limits and quotas

10,000

messages per application, per month

120/min

requests per application

25

devices per account

50

applications per account

1024

characters per message

5 MB

maximum attachment size

Check what is left with GET https://veloxipush.planthelper.org/1/apps/limits.json?token=…

Errors

Failures return status: 0 and a list of problems in plain language.

{"status":0,"request":"9f1c3e2a-…","errors":["user is invalid"]}

Status	Meaning
`400`	A parameter is missing or invalid. The errors array says which.
`402`	The recipient has no active subscription. For a group send, unsubscribed members are listed in skipped instead.
`403`	The application has been disabled.
`404`	No such receipt for this application.
`429`	Rate limit or monthly quota exhausted.