Zona for developers
One HTTPS endpoint turns anything that can make a request into an alert in your Zona inbox. This page explains the model before you write code.
Zona is an inbox on your phone for the machines you look after. A backup script, a CI job, a health check or an AI agent sends a short alert, and it waits for you in Zona with a title, a message, an optional severity, a checklist and up to five screenshots.
There is no SDK to install. If a program can send an HTTPS POST, it can send to Zona.
The one endpoint
Link to this sectionEvery alert goes to the same URL:
POST https://gerncrjtrdjtjvybvseb.supabase.co/functions/v1/notifyThree headers travel with every request, and the body is a small JSON object:
Authorization: Bearer zona_live_YOUR_SOURCE_TOKEN
Idempotency-Key: backup-20260726-020000
Content-Type: application/json
{"title": "Backup complete", "body": "The nightly backup finished successfully."}A new alert returns 202 Accepted with a notificationId. Sending the same request again with
the same Idempotency-Key returns 200 and the original alert instead of a duplicate.
Sources and tokens
Link to this sectionA source is the sender you see in the inbox: Office PC, Release pipeline, Home server.
You create sources in the app under Sources, and each one keeps its own name, sound and
history.
A source signs its requests with an access key, a token that starts with zona_live_. Zona
shows the complete token once, when you create it, and stores only a SHA-256 hash of it. The
server works out which account and which source sent an alert from the token alone, so a request
can never claim to be a different source by changing a field.
- Create one source per computer or application that should look distinct in the inbox.
- A source can hold several keys. Each key can be paused, resumed or revoked on its own, which is how you rotate a credential without changing what the inbox shows.
- A key is a password. Keep it in an environment variable, an OS secret store or a CI secret.
Read Authentication and source tokens for storage and rotation.
What a 202 means
Link to this sectionA 202 means the alert is stored in your inbox before the response is sent. Phone notifications
are delivered afterwards by a background worker, and they can be skipped on purpose: quiet hours
keep the alert in the inbox and only silence the banner.
What Zona does not do
Link to this sectionZona receives alerts; it does not reach back into your machines. It has no remote shell, no command execution and no PC heartbeat, so a quiet source means no alerts were accepted, not that a computer is offline.
AI agents do not need raw HTTP at all: the MCP server gives them zona_notify as a
tool. If something in these docs does not match what the API does, write to
terabasedevteam@gmail.com.
Every page
Send alerts
- AuthenticationHow a zona_live_ token identifies a source, where to keep it, and how to rotate, pause or revoke a key without losing the source's history.
- Sending alertsEvery header, every body field and its exact rules, how severity and category behave, and what each field in the response means.
- ChecklistsSend up to 20 to-do items with an alert. The recipient ticks them off in Zona; retries never reset what they have done.
- ImagesAttach up to five PNG, JPEG or WebP screenshots with multipart/form-data, stay inside the plan's byte budget, and retry without duplicates.
Reliability
- Idempotency and retriesPick one stable Idempotency-Key per event, retry only what is safe to retry, and honour Retry-After, so a flaky network never sends the same alert twice.
- Errors and limitsEvery status and error code /notify can return, what caused it and what to do next, plus the documented request, rate and plan limits.
- Quiet hours and deliveryWhat a 202 guarantees and what it does not, how quiet hours skip the push but keep the alert, and how phone delivery works after the response.
Reference