Retract Notifications

Send a notification with a collapse_id, and when it stops being true (the garage door closed, the build went green, someone else is already on it), take it back with POST /notifications/retract. Every device it reached with PushWard 1.1.0 or later on Android, or 1.20 or later on iPhone, iPad and Mac, removes it from the Lock Screen, Notification Center or the notification shade, and the PushWard app marks it read. Nothing is deleted: the notification stays in the app's history.

curl -X POST https://api.pushward.app/notifications \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Garage door open",
    "body": "It has been open for 30 minutes.",
    "level": "time-sensitive",
    "collapse_id": "garage-door"
  }'

curl -X POST https://api.pushward.app/notifications/retract \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"collapse_id": "garage-door"}'

The response is 202 Accepted with the number of devices the retraction was sent to. The silent pushes go out right after it.

{ "devices": 3 }

What it takes back

• Every notification of the account (or of the organization) sent with that collapse_id, whichever integration key sent it, scheduled and repeating sends included. The silent push goes to the devices a POST /notifications from the same caller would reach, except Apple Watch and Apple devices on PushWard versions before 1.20 (see Best effort).
• A personal retract matches only personal notifications, and an organization's retract matches only that organization's. When a team retracts garage-door, a member's own notification with the same collapse_id stays, and the other way round.
• An organization key limited to some groups or tags sends the retraction only to the members' devices those groups and tags reach.
• A snoozed notification that is waiting to come back is dropped as well.
• A device that never got such a notification ignores the push. A schedule that has not fired yet is not touched: cancel it with DELETE /notifications/scheduled/{id}.

Without a collapse_id there is nothing to retract by, so give one to every notification you may want back. The same id also replaces the earlier notification when you send again under it, which makes one id per thing (a door, a build, a host) the natural choice.

Acknowledged alerts stop repeating

A retract also stops the repeats of acknowledged alerts sent with that collapse_id. Which ones depends on who retracts:

• From a person, the app or an organization key without groups or tags, every acknowledged notification of the account or organization sent with that collapse_id stops repeating, whichever key sent it.
• From an organization key scoped to groups or tags, only the acknowledged notifications that key sent with that collapse_id stop repeating.

Their receipts end canceled, with cancel_reason retracted, and no callback is sent for them. An acknowledged alert sent without a collapse_id is out of its reach: cancel its receipt instead.

Best effort

A retraction is a silent push, and silent pushes are not guaranteed. iOS does not deliver them to an app the user force-quit, and Low Power Mode holds them back, so a notification can stay on screen until PushWard runs again. Android gets the retraction at normal priority, so in Doze it waits for a maintenance window, and an app the user force-stopped gets nothing until it is opened again. Do not use retract for anything that has to disappear, such as a one-time code.

• On Apple devices, PushWard 1.20 or later on iPhone, iPad and Mac retracts. Older versions and Apple Watch are neither sent to nor counted in devices.
• Every Android device is sent to and counted, including app versions before 1.1.0 that predate retract. Those only sync their inbox and leave the notification in the shade.

From the CLI, MCP and Home Assistant

The CLI (1.8.0 and later) takes it back by the collapse id and prints how many devices the retraction was sent to:

pushward notify --title "Garage door open" --body "Since 21:40" --collapse-id garage-door
pushward notification retract garage-door

On the MCP server (pushward-mcp 1.20.0 and later) it is retract_notifications with a collapse_id, which returns the same {"devices": n}. Give create_notification or create_scheduled_notification a collapse_id so there is something to take back.

Home Assistant calls it as pushward.clear_notification (integration 0.55.0 and later). It works like the Companion app's clear_notification message, with collapse_id in place of tag:

- alias: Garage closed, take the alert back
  triggers:
    - trigger: state
      entity_id: cover.garage_door
      to: closed
  actions:
    - action: pushward.clear_notification
      data:
        collapse_id: garage-door

Limits and errors

Retract is limited to 10 a minute per account or organization, counted across all of its keys, with at most 5 in a quick burst. A new key does not buy more.