Replace Push Notification

Replaces a Push Notification you already sent, using the notification_id from the send response. The replacement takes the original's place on the Lock Screen and in Notification Center instead of appearing as a second notification. It is delivered silently, with no sound or screen wake, to the same recipients as the original. Notification history is updated in place.

PUT https://activitysmith.com/api/push-notification/{notification_id}

Authentication#

Use your API key in the request header.

Authorization: Bearer $YOUR_API_KEY

Parameters#

notification_id#

path parameter. Required.

The notification_id returned when the Push Notification was sent.

Type: string

Min Length: 1

Request examples#

curl -X PUT "https://activitysmith.com/api/push-notification/Xk3pQ8mV2nR7tL9wB4yZ" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "✅ checkout-api recovered",
    "message": "Error rate is back to normal. Incident resolved."
  }'

Bodyapplication/json

Replacement content. title, subtitle, message, redirection, media, icon, actions, and payload fully replace the original values. Omit metadata or tags to keep the stored values; send {} or [] to clear them.

metadataMetadata

Optional. Omit to keep the stored metadata; send {} to clear it.

titlestringrequired

messagestring

subtitlestring

iconstring<uri>

Optional HTTPS image URL without credentials for a custom notification icon. If the image cannot be loaded, the app icon is used. iOS may omit subtitle when displaying a custom icon.

Pattern: ^https://

mediastring<uri>

Optional HTTPS URL for an image, audio file, or video that users can preview or play when they expand the notification. If redirection is omitted, tapping the notification opens this URL. Cannot be combined with actions.

Pattern: ^https://

redirectionstring<uri>

Optional HTTP, HTTPS, Shortcuts, or installed app URL opened when the user taps the notification body. Custom schemes such as spotify:// and spotify:track:123 require iOS 1.13.4 build 2 or later and an installed handler; no web fallback is provided. Internal and executable schemes are blocked. Overrides the default tap target from media.

Pattern: ^[A-Za-z][A-Za-z0-9+.-]*:

Max Length: 2048

actionsarray of PushNotificationAction

Optional interactive actions shown when users expand the notification. Cannot be combined with media.

Max Items: 4

payloadobject

Additional Properties: true

badgeinteger

tagsTagSlugs

Optional. Omit to keep the stored tags; send [] to clear them.

Additional Properties: false

default

{
  "title": "✅ checkout-api recovered",
  "message": "Error rate is back to normal. Incident resolved."
}

Responses#

200#

Push notification replaced

Content type: application/json

Schema: PushNotificationReplaceResponse#

Apple APNs acceptance result for the replacement. Acceptance does not confirm device delivery or presentation.

successbooleanrequired

True when APNs accepts the replacement for at least one device.

notification_idstringrequired

ID of the replaced Push Notification. It stays the same, so you can replace it again.

devices_notifiedinteger

Number of device tokens for which APNs accepted the notification, without confirming on-device delivery.

users_notifiedinteger

effective_channel_slugsarray of string or null

tagsTagSlugs

timestampstring<date-time>required

Additional Properties: false

default

{
  "success": true,
  "notification_id": "Xk3pQ8mV2nR7tL9wB4yZ",
  "devices_notified": 2,
  "users_notified": 1,
  "effective_channel_slugs": null,
  "timestamp": "2025-08-12T12:05:00.000Z"
}

400#

Bad request (invalid payload or channel targeting input)

Content type: application/json

Schema: BadRequestError#

errorstringrequired

messagestringrequired

Additional Properties: true

missing title

{
  "error": "Missing title",
  "code": "missing_title",
  "message": "title is required in the request body."
}

invalid tags

{
  "error": "Invalid tags",
  "code": "invalid_tags",
  "message": "tags must use 1-64 lowercase letters, numbers, dashes, underscores, periods, or colons"
}

402#

Billing access required

Content type: application/json

Schema: BillingBlockedError#

errorstringrequired

Enum: ["trial_expired","trial_exhausted","billing_overage_cap_reached"]

messagestringrequired

trial_periodobject

trial_period.started_atstring<date-time>required

trial_period.ends_atstring<date-time>required

upgrade_urlstring<uri>required

Additional Properties: true

403#

Forbidden (API key scope or channel assignment violation)

Content type: application/json

Schema: ForbiddenError#

errorstringrequired

messagestringrequired

Additional Properties: true

channel scope violation

{
  "error": "Invalid channel targeting",
  "message": "This API key can only target assigned channels. Requested channels include channels outside this key scope."
}

404#

Push notification not found

Content type: application/json

Schema: NotFoundError#

errorstringrequired

messagestringrequired

Additional Properties: true

not found

{
  "error": "Push notification not found",
  "code": "push_notification_not_found",
  "message": "No push notification found with id: Xk3pQ8mV2nR7tL9wB4yZ"
}

409#

Push notification was sent before replacement support

Content type: application/json

Schema: NotFoundError

not replaceable

{
  "error": "Push notification cannot be replaced",
  "code": "push_notification_not_replaceable",
  "message": "This push notification was sent before replacement was supported and cannot be replaced. Send a new push notification instead."
}

422#

No recipients of the original Push Notification are still available

Content type: application/json

Schema: NoRecipientsError#

errorstringrequired

messagestringrequired

effective_channel_slugsarray of string or null

Additional Properties: true

no devices

{
  "error": "No recipients found",
  "message": "No devices matched the effective channel target",
  "effective_channel_slugs": [
    "marketing"
  ]
}

429#

Rate limit exceeded

Content type: application/json

oneOf

Schema: RateLimitError

Schema: LiveActivityLimitError

rate limited

{
  "error": "Rate limit exceeded",
  "message": "Too many requests, please try again later."
}

Download the OpenAPI specification