Skip to content
Nowlark
Sign inGet the app
How it worksPricingDocsTeams
Get the appSign in
Support menu

Start

Support home

Guides

Send a notificationSchedule, repeat and escalateQuestions and receiptsSources, tones and your feedConnect your toolsTeams, roles and invitesChannels, escalation, webhooks and emailForms and spam protectionConsole, company sign‑in and SCIMAccount, keys and devices

Help

Contact

Send a notification

Every field a notification can carry, with the request that sets it: priority, replacing, grouping, links and the limits that apply.

One web request from a script, a cron job, a server or an app puts a notification on every device on your account. There is nothing to install and no sign‑in step in the sender.

Your scriptcron, CI, server, app
Nowlarkone request, one key
Every deviceiPhone, iPad, Mac, Watch, Vision
The whole path. Nothing in the middle needs setting up.

The smallest send#

curl https://nowlark.com/v1/notify \
  -H "X-Nowlark-Key: nlk_…" \
  -H "Content-Type: application/json" \
  -d '{"source":"Nightly backup","title":"Finished","body":"412 files, 3.1 GB"}'

A send needs a source (who is sending) and a title or a body. The answer tells you how many of your devices took it: delivered out of devices. 0 of 0 means no device has opened the app yet, which is not a failure.

N
NIGHTLY BACKUP · nowFinished412 files, 3.1 GB
What the request above looks like on the Lock Screen.

What a notification can carry#

Field What it does for you
source
The sender's name. Each name gets its own row in the app, where you can mute it, colour it or give it a tone.
title, body
The headline and the detail under it (up to 1,024 and 10,000 characters).
url
A link. Tapping the notification opens it straight from the Lock Screen.
priority
How loudly it arrives, from −2 (silent) to 2 (urgent, repeats until opened).
image
A picture on the notification and in the app. Needs the Upgrade Pass.
actions
Up to three buttons: Open, Copy, Mute, Done. Needs the Upgrade Pass.
copy_text
What the Copy button puts on your clipboard, a code or a link, without opening the app.
group_key
Notifications sharing this value stack together on the phone.
dedupe_key
Send the same value twice and only the first is delivered. A retrying job cannot buzz you twice.
replace_key
A newer notification with the same source and key takes the older one's place, in the feed and on the Lock Screen.
tags
Up to five short labels, kept in your history.
devices
Reach only some platforms: ios, ipados, macos, watchos, visionos.
ttl
How long Apple may hold the push if the device is out of reach, before dropping it.

Priority#

2 · Urgent
1 · High
0 · Normal
−1 · Low
−2 · Very low
Longer bar, louder arrival. Urgent and High get through a Focus; Urgent keeps alerting until you open it; Low and Very low are silent.

You can cap a noisy sender from the app: open it in Sources and set Priority to "At Most High" or lower. Its notifications then arrive at that level at most, whatever it asks for.

Replacing instead of piling up#

For a job that reports progress or state, give every message the same replace_key. The phone shows one notification that always says what is true now.

Deploy: buildingreplace_key: deploy
Deploy: testingreplace_key: deploy
Deploy: livethe only one left
Three sends, one notification on your phone.

A notification can carry one link, and web addresses written in its text are tappable. Links are http or https only. Choose where they open in the app under Settings › Links: the in‑app browser, or your default browser with your logins and extensions.

Limits you may meet#

  • Each key can send 1,000 notifications an hour. The answer to every send says how many are remaining and when the hour resets.
  • A refused send says why in plain words: a field too long, a feature the account has not unlocked (402), or a rate limit (429).
  • duplicate: true and muted: true are not errors. The first means your dedupe_key already did its job; the second means you muted that source, so it is kept in history without a buzz.

Every field, limit and error is in the API reference. To check a key without sending anything, call GET /v1/key/check.

You can list a source before it has sent anything with POST /v1/sources (free, not counted against the hour), so it can be muted or given a tone ahead of time.

Next: schedule it for later, or ask a question and get the answer back.

PreviousSupport homeNextSchedule, repeat and escalate