API documentation: Zapsy

Overview

The API lives at https://api.zapsy.com/1/. Requests are HTTPS POSTs with form-encoded or JSON bodies; responses are JSON. Every response carries a request id you can quote to support.

This site is a mock-up. The endpoints below are live on this host and answer with realistic JSON from a demo account, so you can try the shapes, but nothing is delivered anywhere.

Tokens and keys

Two 30-character strings identify every message:

Parameter	What it is	Where to find it
`token`	The application token. One per application you create.	Dashboard, the application's page
`user`	Your user key, or a group key. Where the message goes.	Dashboard, top of the page

Treat both like passwords. A leaked token lets anyone send you messages; rotate it from the application page.

Rate limits

Each application may send 10,000 messages per month. Every response includes the headers X-Limit-App-Limit, X-Limit-App-Remaining and X-Limit-App-Reset (Unix time). Beyond the limit you get HTTP 429 until the reset.

Send a message

POST/1/messages.json

Parameter	Description
`token`required	Application token.
`user`required	User or group key.
`message`required	The message body, up to 1,024 characters.
`title`	Up to 250 characters. Defaults to the application name.
`device`	A device name, or several separated by commas. Omit to reach all devices.
`priority`	-2 to 2, see below. Default 0.
`retry`	Emergency only. Seconds between repeats, minimum 30.
`expire`	Emergency only. Seconds until repeats stop, maximum 10,800.
`callback`	Emergency only. URL we POST to when the message is acknowledged.
`url`	Supplementary link shown with the message, up to 512 characters.
`url_title`	Label for the link, up to 100 characters.
`sound`	One of the sound names below.
`timestamp`	Unix time to show instead of the time of receipt.
`html`	Set to 1 to enable bold, italic, underline and links in the message.
`attachment`	Image file, multipart upload, up to 5 MB.

# request
curl -s https://api.zapsy.com/1/messages.json \
  -d token=aH3nX8qL2wP5vK9mC4rT7yB1zF6dJ0 \
  -d user=uZ4k9pQ2mN7xW1vB8cR3tY6hL0sD5f \
  -d title="Disk almost full" \
  -d message="/dev/sda1 at 94% on harvest-e" \
  -d priority=1 -d sound=siren

# response, HTTP 200
{ "status": 1, "request": "c4a2b7e0-5f3d-4c1a-9e8b-2d6f1a0b3c4d" }

Priorities

Value	Name	Behaviour
`-2`	Lowest	No notification. Badge count only.
`-1`	Low	Notification without sound or vibration.
`0`	Normal	Regular notification. Silent during the user's quiet hours.
`1`	High	Bypasses quiet hours. Highlighted in the app.
`2`	Emergency	Repeats every `retry` seconds until acknowledged or `expire` is reached. Returns a `receipt`.

Receipts

GET/1/receipts/{receipt}.json?token=...

Emergency messages return a receipt id. Poll it to learn the acknowledgement state, or give a callback URL when sending and we POST the same fields there once.

{ "status": 1,
  "acknowledged": 1, "acknowledged_at": 1760003620,
  "acknowledged_by": "uZ4k9pQ2mN7xW1vB8cR3tY6hL0sD5f", "acknowledged_by_device": "iphone",
  "last_delivered_at": 1760003590, "expired": 0, "expires_at": 1760007190,
  "called_back": 0, "called_back_at": 0,
  "request": "..." }

Validate a user or group

POST/1/users/validate.json

Pass token and user (optionally device) to check a key before storing it in your configuration. The answer lists the registered devices and licensed platforms.

Application limits

GET/1/apps/limits.json?token=...

Returns limit, remaining and reset for the application, the same numbers as the response headers.

Sounds

zap bolt chime bell ping drum siren cosmic none

Custom sounds uploaded to an application are addressed by the name you give them.

Errors

Invalid requests answer HTTP 400 with status: 0, a list of human-readable errors, and each offending parameter set to "invalid".

{ "status": 0,
  "errors": ["message cannot be blank"],
  "message": "invalid",
  "request": "..." }

HTTP	Meaning
200	Accepted for delivery.
400	Something in the request is invalid. See `errors`.
429	Monthly limit reached for this application.
5xx	Our fault. Retry with backoff; the request id helps us trace it.

Try it against this mock-up

The demo account's keys are on the dashboard. This sends through the mock endpoint on this host and the message appears in the dashboard's recent list:

curl -s /1/messages.json \
  -d token=aH3nX8qL2wP5vK9mC4rT7yB1zF6dJ0 \
  -d user=uZ4k9pQ2mN7xW1vB8cR3tY6hL0sD5f \
  -d message="Hello from the docs" -d priority=2 -d retry=30 -d expire=600