Notifications

These endpoints put a notification on screen and take it away again: show a banner, speak without a banner, dismiss, and snooze. This is the part of the HTTP API most integrations need, and often the only part. The examples use the $HERALD and $TOKEN variables from Connect.

How a notification works#

A notification is one JSON object sent by an app. The app is identified by an id you choose, such as example.bidbot. You do not have to register the app first: Herald registers an unknown id the first time it sends something.

Herald does four things with a notification:

1. It applies a template if the notification names one, or if the app's manifest sets a default. The template decides the layout. Without one, Herald uses a built-in layout.
2. It shows a banner, plays the app's sound, and speaks the text if you asked for speech.
3. It stores the notification in History, where it stays after the banner is gone.
4. It keeps the banner until the user closes it, a button is pressed, a timeout ends it, or you dismiss it.

Every notification has an id. If you send one, you can use it later to replace, dismiss or snooze that banner. If you leave it out, Herald generates one and returns it.

One notification as a banner: the title, the subtitle, the body, the time it arrived and the close button.

What happens when the user clicks a banner is described in How banners behave.

Endpoints#

POST /v1/notify#

Shows a notification as a banner and stores it in History. Sending the same id again replaces the banner that is on screen in place, which is how you update a progress or count without stacking new banners.

Request

Only app is required, plus title unless the template supplies one. The fields are grouped below; all of them go in the JSON body.

Fields that control how the banner behaves:

Fields that add buttons:

Fields that add speech (explained in the voice reference):

Fields for the built-in layouts, used only when no template applies:

curl -s -X POST "$HERALD/v1/notify" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "app": "example.bidbot",
    "id": "bid-42",
    "title": "Bid accepted",
    "subtitle": "Acme RFP",
    "body": "Your bid of $4,200 was accepted.",
    "url": "https://example.com/bids/42",
    "buttons": [{"label": "Open", "url": "https://example.com/bids/42"}]
  }'

{"ok": true, "id": "bid-42"}

Response fields

Errors

Notes

• A top-level key that is not in the tables above is treated as a template field and moved into metadata. You can send "amount": "$4,200" at the top level and bind {amount} in a template. A top-level key wins over the same key inside metadata.
• An unknown template name is not an error while the notification has its own title. Herald shows it with the built-in layout.
• An image is checked by its bytes, not its name. PNG, JPEG, GIF, WebP, HEIC, AVIF, TIFF and BMP are accepted, up to 10 MB. Anything else is ignored and the banner shows without a picture.
• An explicit empty list, "buttons": [], means no buttons, even when the manifest declares actions.
• priority: "urgent" breaks through quiet hours only for apps where the user allowed it.

Button object#

A button has a label and one thing it does. Give exactly one of url, command, script, shortcut, callback, openApp or reply. The full behaviour of each kind is in the actions reference.

{
  "app": "example.bidbot",
  "title": "Counter-offer from Acme",
  "body": "They offer $3,900. Accept?",
  "buttons": [
    {"label": "Accept", "callback": {"payload": {"decision": "accept"}}},
    {"label": "Decline", "style": "destructive", "callback": {"payload": {"decision": "decline"}}},
    {"label": "Reply", "reply": {"placeholder": "Message to Acme"}}
  ]
}

{
  "app": "example.bidbot",
  "title": "Bid accepted",
  "buttons": [
    {"label": "Forward", "shortcut": "Forward to phone", "input": "{title}"},
    {"label": "Log", "script": "log.sh"}
  ]
}

The first time a script or shortcut button runs for an app, the banner asks the person to allow it. The question names the script with its SHA-256 or the Shortcut with its input. snooze is not a button an app can send.

Follow-up object#

A follow-up runs one action when the banner is left unattended: nobody dismisses it, presses a button, replies or opens it for the time you set. Use it to forward a missed banner. How it works is in Follow-ups.

Give exactly one of actionRef and action. The kind must be shortcut, script, command or callback: a link, an app, a reply, a snooze or a dismiss would take focus, need the person or hide the banner.

{
  "app": "example.bidbot",
  "id": "bid-42",
  "title": "Bid accepted",
  "persistent": true,
  "followUp": {
    "after": "10m",
    "action": {"id": "fwd", "label": "Forward", "kind": "shortcut",
               "shortcut": "Forward to phone", "input": "{title}"}
  }
}

• A template's follow-up wins over the notification's, and the notification's over the manifest's.
• The timer starts when the banner is on screen. Dismissing, any button, a reply and opening cancel it. Snoozing restarts it when the banner comes back.
• A follow-up runs at most once for a notification.
• A follow-up that runs code runs under the app's permission. A notification cannot grant it.
• A timeout that is not longer than after means the banner closes first and never follows up.
• Herald keeps the timer in memory. Quitting Herald drops it.
• An app that reaches Herald through the cloud relay cannot send followUp. Its owner adds one to the template.

Reminder object#

POST /v1/speak#

Says text aloud and shows no banner. It is a shortcut for a notification with presentation: "voice", and the text is stored in History like any other notification. Use it for a short spoken status when a banner would be noise.

Request

curl -s -X POST "$HERALD/v1/speak" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"app": "example.bidbot", "text": "Deploy finished", "voice": "af_bella", "speed": 1.1}'

{"ok": true, "id": "7C1D0E52-3F0B-4B8E-9A55-0F3A1C0D2E11"}

Errors

Notes

• If speech cannot play (Herald is muted, the app's Speak switch is off, or the engine is off), the text is shown as a normal banner instead, so it is never lost.
• The History title is the first 80 characters of the text.

POST /v1/dismiss#

Closes one banner. The notification stays in History. Use it when the event behind a banner is over, for example when the user handled it in your own app.

Request

curl -s -X POST "$HERALD/v1/dismiss" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"app": "example.bidbot", "id": "bid-42"}'

{"ok": true}

Errors

Notes

• Dismissing an id that is not on screen is not an error. The reply is still {"ok": true}.

POST /v1/dismissAll#

Closes several banners at once. What it closes depends on the body.

Request

curl -s -X POST "$HERALD/v1/dismissAll" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"app": "example.bidbot", "group": "acme"}'

{"ok": true}

Errors

Notes

• An empty body closes every banner on screen.
• Dismissed notifications stay in History.

POST /v1/snooze#

Hides a banner and shows it again, with the same id, after a number of minutes. A snooze survives a restart of Herald, and History marks the notification as snoozed while it waits.

Request

curl -s -X POST "$HERALD/v1/snooze" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"app": "example.bidbot", "id": "bid-42", "minutes": 15}'

{"ok": true, "until": "2026-10-02T13:15:00.000Z"}

Response fields

Errors

Notes

• Sending a new notification with the same id cancels a pending snooze.
• The duration is elapsed time: one hour is one hour even across a daylight-saving change.

POST /v1/unsnooze#

Cancels a snooze and shows the banner again at once. It plays no sound, because it is not a new alert.

Request

curl -s -X POST "$HERALD/v1/unsnooze" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"app": "example.bidbot", "id": "bid-42"}'

{"ok": true}

Errors

POST /v1/compose#

Opens Herald's Composer window, where a person fills in a notification by hand and sends it. It is what herald compose calls. It takes no body and shows no banner.

Request

No parameters.

curl -s -X POST "$HERALD/v1/compose" -H "Authorization: Bearer $TOKEN"

{"ok": true}

Related#

• Send your first notification: a walk through the first POST /v1/notify.
• How banners behave: clicking, expanding, closing and timeouts.
• Templates: control the layout a notification is drawn with.
• Actions: buttons that call you back, run commands or take a reply.
• Voice reference: the speak, audio and presentation fields in full.
• History API: read back what was sent.