# Pushling

> Pushling sends notifications from your apps, cron jobs, CI and AI agents to one inbox on iPhone, Android and the web, with one HTTP request, a CLI or MCP. In development at Tiida Tech.

Status: in development. Purchases and sign-ups are not open yet. The API below is the development API and may change before release. It is not compatible with Pushover, although the parameters are similar.

## Send a notification (HTTP API)

- Endpoint: `POST {base}/1/messages.json` with form, multipart or JSON body. Development base URL: https://app.pushling.com
- Required: `token` (app token from a project), `user` (recipient user key), `message` (up to 1024 characters).
- Optional: `title` (up to 250), `url` (http or https) and `url_title` (up to 100), `priority` (-2 to 2, default 0), `sound` (`default`, `soft`, `bright` or `none`), `device` (comma-separated device names), `ttl` (seconds), `attachment` (multipart image: PNG, JPEG, WebP or GIF, up to 5 MB).
- Priority 2 needs `retry` and `expire` (30 to 10800 seconds each). It repeats until a person confirms, and the response includes a `receipt`.
- Idempotency: send `idempotency_key` (or an `Idempotency-Key` header). The same key and content within 24 hours returns the same request; reusing a key with different content returns 409.
- Repeats: the same title and message (or the same optional `collapse_key`, up to 64 letters, digits and `_ . : -`) from one project within 10 minutes is pushed silently and shown on receivers as one entry with a count. The response then has `collapsed: 1` and `repeat`. Emergencies and questions are never merged.
- Rate limit: a project may send 120 notifications a minute; beyond that the API returns 429. Idempotent replays do not count.
- Context (all optional): `source` (the sending tool, e.g. `claude-code`; letters, digits and `_ . -`), `workspace` (project or folder, up to 120), `session` (run or session ID, up to 64), `command` (the command or action the notice is about, up to 500) and `risk` (`low`, `medium` or `high`). Receivers show them with the notice and can narrow the inbox to one session. Coding agents should always set `source`, `workspace` and `session`, and set `command` and `risk` when asking for approval.
- Success response: `{"status":1,"request":"…"}`.
- Receipts: `GET {base}/1/receipts/{receipt}.json?token=…`; cancel with `POST {base}/1/receipts/{receipt}/cancel.json` and `token` in the body.
- Other endpoints: `POST {base}/1/users/validate.json`, `GET {base}/1/sounds.json?token=…`.
- Not supported (returns an error): `html`, `callback`, `encrypted`, base64 attachments, group keys.

Priorities: -2 history only (No push. Appears at the next sync); -1 quiet (Delivered without sound); 0 normal (Respects quiet hours); 1 high (Sounds even during quiet hours); 2 needs confirmation (Repeats every 30 s to 3 h until someone confirms).

## Ask a question and wait for the answer

- Add `answers` (up to 4 labels separated by `|`, or a JSON array; each 1 to 32 characters) and/or `answer_text=1` (free-text reply up to 500 characters) to `POST {base}/1/messages.json`. `answer_expire` sets the deadline in seconds (30 to 86400, default 3600). The response includes `question`.
- Read the answer with `GET {base}/1/questions/{question}.json?token=…&wait=25`. `wait` (0 to 25 seconds) holds the request until the question is answered or closed. The response has `answered`, `choice`, `text`, `answered_at`, `expired` and `expires_at`.
- Only the first answer from any of the receiver's devices is recorded. If `expired` is 1 and nothing was answered, treat it as no. Never proceed on silence.
- Withdraw a question with `POST {base}/1/questions/{question}/cancel.json` and `token` in the body. Answering a priority 2 question also confirms it.

## Send from an AI agent (MCP)

- Streamable HTTP endpoint `{base}/mcp` with `Authorization: Bearer <agent token>` issued in the app settings.
- Tools: `list_projects`, `create_project`, `send_notification`, `ask_user`, `wait_for_answer` (call again while `answered` and `expired` are both 0), `cancel_question`, `get_delivery_log`. Emergency priority is not available through MCP.

## Scheduled notifications and watchdogs

- Create a schedule: `POST {base}/1/schedules.json` with `token`, `user`, `message` and either `delay_seconds` (60 to 604800) or `deliver_at` (Unix seconds, 60 seconds to 7 days ahead).
- Create a watchdog: `POST {base}/1/watchdogs.json` with the same notification fields and `interval_seconds` (60 to 604800). Send `POST {base}/1/watchdogs/{id}/ping.json` with `token` to reset its deadline. A missed deadline produces one notification; the next ping rearms it.
- Read status with `GET {base}/1/schedules/{id}.json?token=…` or `GET {base}/1/watchdogs/{id}.json?token=…`. Cancel with `POST` to the corresponding `/{id}/cancel.json`, with `token` in the JSON body. Canceled watchdogs cannot be rearmed; already accepted notices are not withdrawn.
- Plain notifications only: priority -2 to 1, no questions, emergencies or attachments. Sender context is supported. TTL begins at notification acceptance. Creation and ping do not charge notification quota; firing does.
- Creation accepts `idempotency_key` or `Idempotency-Key` for 24 hours. Reuse the same key when retrying an unknown outcome. Default active limit: 100 per project; pending schedules and all uncanceled watchdogs count.
- Status `pending` means waiting or retrying; `fired` means server acceptance, not device delivery; `canceled` and `failed` are terminal for schedules. `request` is the last accepted notification ID.
- Requires running server maintenance. Recurring Cron execution has been observed in the development deployment, but end-to-end scheduled delivery and missed-heartbeat alerts have not yet been verified there; do not rely on them until that verification is complete. Minute-level execution, backlog and outages can delay delivery. This is not independent monitoring of Pushling itself. Temporary errors retry up to 10 attempts; inspect `last_error` on failure.
- MCP tools: `schedule_notification`, `create_watchdog`, `get_notification_automation`, `ping_watchdog`, `cancel_notification_automation`. Each requires the project `token`; management tools also take `automation_id`. Creation targets the signed-in account and checks project ownership.
- CLI: `schedule create --message TEXT --delay SECONDS` (or `--at UNIX_SECONDS`), `schedule status|cancel ID`, `watchdog create --message TEXT --interval SECONDS`, `watchdog ping|status|cancel ID`. Use the existing SIGNALBOX environment variables for credentials.

## Adding Pushling to a project

- Send a notification when a long-running task finishes or fails: `POST $PUSHLING_URL/1/messages.json` with `token` (app token), `user` (user key), `title`, `message` and a unique `idempotency_key` per event.
- Use priority 1 for failures and 0 otherwise.
- Before any destructive or irreversible step, ask for approval with `answers=Approve|Deny` and wait for the answer at `$PUSHLING_URL/1/questions/{id}.json?wait=25`. Treat no answer as Deny.
- Read `PUSHLING_URL`, `PUSHLING_APP_TOKEN` and `PUSHLING_USER_KEY` from the environment, and never hard-code the token or key.

## Prompt for coding agents

```text
Read https://pushling.com/llms.txt and add Pushling to this project: notify me when long tasks finish or fail, and ask me before anything irreversible.
```

## Pages

- [Pushling (English)](https://pushling.com/index.md): Push notifications for developers, scripts and AI agents
- [Pushling (日本語)](https://pushling.com/ja/index.md): 開発者・スクリプト・AIエージェントのためのプッシュ通知

## Optional

- [Tiida Tech Ltd](https://tiidatech.com/): the developer of Pushling