通知 API

向使用者的收件匣傳送通知，並可選擇透過 APNs 推播至其裝置。

Create Notification

POST /notifications

Create an in-app notification and optionally push it to all user devices. No subscription required — it counts toward your monthly notification quota (free tier included) and needs notifications at send or above, which your default integration key already has.

Request Body

Field	Type	Required	Description
`title`	string	Yes	Notification title
`body`	string	Yes	Notification body text
`subtitle`	string	No	Optional subtitle
`level`	string	No	`passive`, `active` (default), `time-sensitive`, or `critical`. Controls iOS interruption level.
`volume`	number	No	Sound volume for critical alerts (0.0–1.0). Only used when level is `critical`. Defaults to 1.0.
`thread_id`	string	No	Groups notifications in Notification Center
`collapse_id`	string	No	APNs deduplication key (max 64 chars). Not stored or returned in responses.
`source`	string	No	Source identifier (e.g. integration name)
`source_display_name`	string	No	Human-readable source name shown in notification settings and inbox grouping
`url`	string	No	Action URL (max 2048 chars). Any URL scheme except `javascript:`, `data:`, `file:`, or `vbscript:`; `http(s)` URLs also require a host.
`media`	object	No	Rich media attachment. `url` (HTTPS, max 2048 chars) plus `type` (`image`, `video`, or `audio`). iOS renders inline. Apple size caps: image 10 MB, audio 5 MB, video 50 MB.
`actions`	array	No	Up to 10 dynamic action buttons. Each: `id` (string, max 64), `title` (string, max 64), optional `url`, `foreground` (bool), `destructive` (bool), `authentication_required` (bool), `icon` (SF Symbol name). Full field list on Actions. An action with no `url` and no `foreground` is recorded by the server; see Notification Answers.
`icon_url`	string	No	Per-notification source avatar, shown as the Communication Notification avatar on iOS. Accepts `http` or `https` (max 2048 chars, recommended ≤256×256 and ≤100 KB; the iOS extension rejects responses larger than 512 KB).
`metadata`	object	No	Key-value string pairs (max 20 keys, key max 64 chars, value max 4096 chars, and 8 KB total across all keys and values)
`activity_slug`	string	No	Optional link to an existing activity. An unknown slug is rejected with `422` before the notification is persisted.
`push`	boolean	No	If `true` (default), send APNs rich alert to all user devices. Set `false` to store in the inbox only.
`target`	object	No	Organization keys only: which members get it, as `groups`, `tags` and `members`. See Teams.
將在 app 版本 1.17.0 中推出
`encrypted`	string	No	A `pw1` envelope holding the title, subtitle, body and url, sealed with the user's encryption key (max 3072 chars). Leave those four fields out when it is set; `title` and `body` are required only without it. Not available to organization keys. See End-to-End Encryption.
`acknowledge`	object	No	Repeat the push until someone acknowledges it: `repeat_seconds` (30-3600, default 60), `expire_seconds` (60-10800, default 3600), `action_title` (default `Acknowledge`). Not with `push: false` or level `passive`. See Acknowledged Alerts.
`tags`	array	No	Up to 10 labels (1-64 printable ASCII characters, no spaces) for canceling acknowledged notifications as a group. Requires `acknowledge`.
`callback_url`	string	No	https URL that gets a signed `POST` when the notification is acknowledged or expires (max 2048 chars). Requires `acknowledge`.

範例

curl -X POST https://api.pushward.app/notifications \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deploy Complete",
    "body": "Successfully deployed to production",
    "source": "github-actions",
    "source_display_name": "GitHub Actions",
    "level": "active"
  }'

Response (201):

{
  "id": 42,
  "title": "Deploy Complete",
  "subtitle": "",
  "body": "Successfully deployed to production",
  "thread_id": "",
  "level": "active",
  "source": "github-actions",
  "source_display_name": "GitHub Actions",
  "url": "",
  "media_url": "https://example.com/img.png",
  "media_type": "image",
  "actions": [
    { "id": "rerun", "title": "Re-run", "foreground": true }
  ],
  "icon_url": "",
  "metadata": {},
  "activity_slug": "",
  "pushed": true,
  "created_at": "2026-04-24T21:00:00Z",
  "delivery": "all"
}

On POST /notifications only, the response also includes these read-only fields (omitted from GET responses):

Field	Values	Meaning
`delivery`	`all`, `partial`, `none`	Whether every, some, or no devices accepted the push.
`reason`	`no_apns_token`, `apns_rejected`, `push_disabled`	Failure mode when `delivery` is not `all` -- for a `push: false` create it is `push_disabled` with `delivery` `none`. Omitted on a fully successful push.
`answerable`	`true`	The server records the answer to this notification (at least one action was sent without a `url`). Read it with `GET /notifications/answers/{id}`. Omitted otherwise.
將在 app 版本 1.17.0 中推出
`receipt`	object	Sent with `acknowledge`: the receipt, as `GET /notifications/receipts/{id}` returns it. Omitted otherwise.

Scheduled Notifications

Queue a notification for a later send_at, or repeat it on a cron schedule. The body, rules and statuses are on the Scheduled Notifications page.

POST /notifications/scheduled

Schedule a notification: a POST /notifications body plus send_at (RFC 3339, in the future, at most 365 days ahead), or a recurrence (cron, timezone, until, count) that repeats it, with send_at then optional as the start point. Returns 201 with the schedule. At most 25 pending per account (409 scheduled_notification.limit_exceeded); a repeating schedule holds one slot for its whole series. Each send counts toward the notification quota when it goes out; an account already out of quota gets 429 quota.exceeded.

GET /notifications/scheduled

List schedules. ?status=scheduled (default) lists pending ones soonest first; sent, failed, canceled or all list latest first. ?limit=1-100 (default 50) per page; pass next_cursor back as ?cursor= with the same status for the next page. A key sees only the schedules it created.

GET /notifications/scheduled/{id}

Get one schedule, including notification_id, sent_at and the push outcome once it has been sent, or failure_reason if it failed. A repeating schedule also reports recurrence, occurrence and last_sent_at.

DELETE /notifications/scheduled/{id}

Cancel a pending schedule (204); for a repeating schedule this stops the series. It stays readable as canceled for 24 hours, then it is deleted. ?purge=true deletes it outright with no canceled record.

Notification Answers

Read what the user answered to a notification sent with url-less actions. How recording works is on the Notification Answers page.

GET /notifications/answers/{id}

Get the answer to a notification: notification_id, status (pending or answered), action_id, text and answered_at. id is the notification id from POST /notifications, or the notification_id of a sent scheduled notification. ?wait=0-25 holds the request open until the answer lands (long-poll). The first answer wins; answers are kept 30 days. A key reads only answers to notifications it sent. Returns 404 notification_answer.not_found when none of the actions was url-less, and 429 answer_wait.limit_exceeded when too many waits are open.

將在 app 版本 1.17.0 中推出

本節介紹的功能來自一個正在等待 App Store 審核的 app 更新。更新上線後，此處會自動解鎖。

Error Responses

Errors use the RFC 9457 Problem Details shape (Content-Type: application/problem+json) — see Errors for the body shape and known code values.

Status	Meaning
`400`	Malformed JSON, or a field-level validation failure (media, action URL scheme, duplicate action `id`, metadata size, or `text_input` rules)
`401`	Missing or invalid token
`403`	Integration key's `notifications` level is `none` (`integration_key.permission_denied`), or it sets `activity_slug` without activity access, or an organization key limited to some groups and tags targets outside them (`integration_key.target_denied`)
`422`	Schema violation (wrong shape, `maxLength`, or `enum`), an unknown `activity_slug`, or a bad `target` (`org.target_*`)
`429`	Per-IP rate limit (`code: rate_limit.exceeded`) or monthly notification quota exhausted (`code: quota.exceeded`) — pairs with `Retry-After` and `retry_after_ms`. See Errors for the quota body shape.
`500`	Internal server error
將在 app 版本 1.17.0 中推出
`409`	25 acknowledged notifications are already active for the account (`notification_receipt.limit_exceeded`)
`422`	An encrypted push that would not fit 4 KB (`notification.encrypted_too_large`), `encrypted` from an organization key (`notification.encryption_unavailable`), or acknowledged notifications switched off for now (`notification_receipt.disabled`)