Activities

Activities are the core resource in PushWard. Each activity represents a trackable item that can be displayed as a Live Activity on subscribed devices.

ℹ Info

Each user can have a maximum of 50 activities. Attempting to create more returns 409 with a Problem Details body whose code is "activity.limit_exceeded" and a Retry-After header.

Create Activity

POST /activities

Create a new activity. Starts in `ended` state. All user devices are automatically subscribed.

Request Body

Field	Type	Required	Description
`slug`	string	Yes	URL-safe identifier, unique per user
`name`	string	Yes	Human-readable display name
`priority`	integer	No	Eviction priority 0-10 (default: 0). Higher = kept longer server-side and ordered ahead of other Live Activities on the iOS Lock Screen and Dynamic Island (mapped to APNs `relevance-score`).
`ended_ttl`	integer	No	Seconds after `ended` transition before server auto-deletes the activity
`stale_ttl`	integer	No	Seconds of inactivity while `ongoing` before server auto-ends the activity
`dismissal_ttl`	integer	No	Seconds after `ended` before the Live Activity is removed from the Lock Screen. `0` removes it immediately; max `14400` (4h, the iOS ceiling). When unset, removal follows `ended_ttl` — see Lock Screen dismissal

Example

curl -X POST https://api.pushward.app/activities \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "dishwasher",
    "name": "Dishwasher",
    "priority": 3
  }'

Response (always 201 Created):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "kind": "owned",
  "slug": "dishwasher",
  "name": "Dishwasher",
  "state": "ended",
  "priority": 3,
  "content": {},
  "ended_ttl": null,
  "stale_ttl": null,
  "dismissal_ttl": null,
  "delete_at": null,
  "created_at": "2025-06-15T10:30:00Z",
  "updated_at": "2025-06-15T10:30:00Z",
  "ended_at": null
}

ℹ Info

Re-POSTing the same slug is idempotent: the server upserts the existing activity and still returns 201 Created rather than 409 Conflict. The X-Resource-Action response header distinguishes the two cases:

X-Resource-Action: created — a fresh row was inserted
X-Resource-Action: updated — an existing slug was refreshed (name / priority / TTLs)

This lets integration bridges retry safely on network errors.

List Activities

GET /activities

List activities for the current user. Returns a cursor-paginated envelope sorted by slug.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Page size, between `1` and `100`.
`after`	string	—	Opaque base64url cursor returned as `next_cursor` on the previous page. Omit for the first page.
`state`	string	—	Filter on activity state. One of `ongoing`, `ended`, `preempted` (lowercase — the same casing response bodies use). Unknown values are rejected with `422`. Omit to return all states.

Example

curl "https://api.pushward.app/activities?limit=50" \
  -H "Authorization: Bearer hlk_YOUR_TOKEN"

Response (200):

{
  "items": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "kind": "owned",
      "slug": "ci-pipeline",
      "name": "CI Pipeline",
      "state": "ended",
      "priority": 0,
      "content": {},
      "ended_ttl": 3600,
      "stale_ttl": null,
      "dismissal_ttl": null,
      "delete_at": "2025-06-15T12:00:00Z",
      "created_at": "2025-06-15T10:00:00Z",
      "updated_at": "2025-06-15T11:00:00Z",
      "ended_at": "2025-06-15T11:00:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "kind": "owned",
      "slug": "dishwasher",
      "name": "Dishwasher",
      "state": "ongoing",
      "priority": 3,
      "content": {
        "template": "generic",
        "progress": 0.65,
        "state": "Washing",
        "icon": "washer",
        "remaining_time": 1800,
        "subtitle": "Cycle 2 of 3",
        "accent_color": "blue"
      },
      "ended_ttl": null,
      "stale_ttl": null,
      "dismissal_ttl": null,
      "delete_at": null,
      "created_at": "2025-06-15T10:30:00Z",
      "updated_at": "2025-06-15T11:00:00Z",
      "ended_at": null
    }
  ],
  "next_cursor": "eyJzIjoib3Zlbi10aW1lciIsImkiOjE5fQ"
}

ℹ Info

Iterate by passing next_cursor as the after parameter on the next request, until next_cursor is null or empty (the last page). The cursor encodes a stable (slug, id) pair, so paging stays consistent even if items are added or removed between requests.

Treat next_cursor as opaque — don't parse or construct it. Pass it back unchanged, and keep limit (and any future filter params) identical across pages of the same traversal.

# Fetch the next page
curl "https://api.pushward.app/activities?limit=50&after=eyJzIjoib3Zlbi10aW1lciIsImkiOjE5fQ" \
  -H "Authorization: Bearer hlk_YOUR_TOKEN"

Get Activity

GET /activities/{slug}

Get a single activity by slug.

Example

curl https://api.pushward.app/activities/dishwasher \
  -H "Authorization: Bearer hlk_YOUR_TOKEN"

Delete Activity

DELETE /activities/{slug}

Delete an activity and all associated subscriptions.

Example

curl -X DELETE https://api.pushward.app/activities/dishwasher \
  -H "Authorization: Bearer hlk_YOUR_TOKEN"

Response: 204 No Content

ℹ Info

If the activity is still ongoing at the time of DELETE, the Live Activity is force-dismissed from the Lock Screen and Dynamic Island immediately — the server sends a push-end with a dismissal date in the past, so iOS removes it as soon as the call completes. This is independent of ended_ttl (which only applies to natural ongoing → ended transitions).

Deleting an activity that has already transitioned to ended only cleans up the database row. The on-screen lifetime is already governed by the dismissal date that was sent when the activity ended, so subsequent DELETEs cannot shorten it.

Update Activity (Primary Integration Endpoint)

PATCH /activities/{slug}

Partial update using RFC 7396 JSON Merge Patch semantics. State transitions automatically trigger push notifications to subscribed devices.

ℹ Info

This is the main endpoint for integrations. Absent fields are preserved; explicit null clears the field; present values overwrite. Server-owned fields (warning_pushed, snoozed_until) are stripped from incoming patches.

Request Body

Field	Type	Required	Description
`state`	string	No	`"ongoing"` or `"ended"`. If omitted, the current stored state is kept. Required when the activity is `preempted` — the caller must explicitly set `ongoing` or `ended`.
`content`	object	No	Partial template content. Fields present overwrite stored values; fields set to `null` clear them; absent fields are preserved. See Live Activities.
`priority`	integer	No	Update eviction priority (0-10). Also drives APNs `relevance-score`, so higher-priority activities are ordered ahead of others on the iOS Lock Screen and Dynamic Island.
`sound`	string	No	Optional Live Activity alert sound. Plays on Lock Screen and Dynamic Island and marks the push `time-sensitive` so it breaks through Focus modes. Request-scoped (not persisted) and ignored on `ended` transitions. One of `default`, `chime`, `alert`, `success`, `warning`, `bell`, `ding`, `buzz`, `notification`.

ℹ Info

Merge-patch rules (per RFC 7396):

The canonical request Content-Type is application/merge-patch+json; application/json is also accepted.
Once set, alarm and warning_threshold persist across updates until explicitly cleared with null.
If both end_date and duration are sent, end_date wins.
duration accepts integer seconds (60) or a string ("60s", "5m", "1h30m").
Transitioning to ended clears alarm, snoozed_until, and warning_pushed on the server.
Semantic validation failures (e.g. arming alarm: true without end_date) return 422 Unprocessable Entity; 400 is reserved for malformed JSON or wrong shape.

Query Parameters

Parameter	Type	Default	Description
`upsert`	boolean	`false`	When `true` and the slug doesn't exist yet, the server creates the activity (its `name` defaults to the slug) and applies the patch in the same request, instead of returning `404`.

ℹ Info

Create-on-missing with ?upsert=true. A plain PATCH to a slug that doesn't exist returns 404. Add ?upsert=true to create the activity on the fly and patch it in a single round-trip:

New slug → the activity is created (name = the slug), the patch is applied, and the response is 201 Created with X-Resource-Action: created.
Existing slug → behaves like a normal patch and returns 200 OK.
Creation requires a key with the activity:manage scope (or full access). An activity:update key gets 403 (activity.upsert_forbidden) for a missing slug when the flag is set, because it isn't allowed to create activities. Without the flag, a missing slug is a plain 404.

Create-and-update in one call

curl -X PATCH "https://api.pushward.app/activities/dishwasher?upsert=true" \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
    "state": "ongoing",
    "content": {
      "template": "generic",
      "progress": 0.1,
      "state": "Washing",
      "icon": "washer",
      "accent_color": "blue"
    }
  }'

💡 Tip

If you'd rather not depend on the query flag, POST /activities is itself an idempotent upsert (re-posting a slug refreshes its name / priority / TTLs and preserves state and content). So POST then PATCH is the zero-flag way to guarantee the activity exists before you push content: the POST creates or refreshes the shell, the PATCH starts and updates it. Use ?upsert=true when you want to collapse those two requests into one.

State Transitions

From	To	Push Action
`ended`	`ongoing`	Push-to-start (starts Live Activity)
`ongoing`	`ongoing`	Push update (updates running activity)
`ongoing`	`ended`	Push end (dismisses after 4 hours)

Example: Start a generic activity

curl -X PATCH https://api.pushward.app/activities/dishwasher \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
    "state": "ongoing",
    "content": {
      "template": "generic",
      "progress": 0.65,
      "state": "Washing",
      "icon": "washer",
      "remaining_time": 1800,
      "subtitle": "Cycle 2 of 3",
      "accent_color": "blue"
    }
  }'

Example: Update with an alert sound

curl -X PATCH https://api.pushward.app/activities/dishwasher \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
    "state": "ongoing",
    "sound": "chime",
    "content": {
      "template": "generic",
      "progress": 1.0,
      "state": "Done",
      "icon": "washer",
      "accent_color": "green"
    }
  }'

Response (200):

The response is the unified Activity object — the same shape returned by GET, list, and POST. The sharing fields (share_role, owner_id, owner_nickname, share_count) use omitempty: they are omitted when they don't apply, not sent as null. Integration (hlk_) keys never receive shared activities, so these fields don't appear in their responses and aren't listed in the API reference.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "kind": "owned",
  "slug": "dishwasher",
  "name": "Dishwasher",
  "state": "ongoing",
  "priority": 3,
  "content": {
    "template": "generic",
    "progress": 0.65,
    "state": "Washing",
    "icon": "washer",
    "remaining_time": 1800,
    "subtitle": "Cycle 2 of 3",
    "accent_color": "blue"
  },
  "ended_ttl": null,
  "stale_ttl": null,
  "dismissal_ttl": null,
  "delete_at": null,
  "created_at": "2025-06-15T10:30:00Z",
  "updated_at": "2025-06-15T11:00:00Z",
  "ended_at": null
}

Content Object

The content object is shared across all templates. Only template is required; each template adds its own required fields on top.

Field	Type	Description
`template`	string	Required. One of: `generic`, `countdown`, `steps`, `alert`, `gauge`, `timeline`, `board`, `log`
`progress`	float	Optional. Value between `0.0` and `1.0`. Computed automatically for `gauge` from `value`/`min_value`/`max_value`.
`alarm`	boolean	Optional. Opt-in iOS AlarmKit alarm at `end_date`. Rings through silent mode and Focus. Requires `end_date`; iOS 26+ only. See Alarms.
`snooze_seconds`	integer	Optional. How many seconds `POST /activities/{slug}/snooze` extends `end_date`, and the iOS AlarmKit snooze window. `60`–`3600`; defaults to `300` (5 min) when omitted. Only meaningful with `alarm: true`.
`snoozed_until`	integer	Read-only. Unix timestamp set when the user snoozes an alarm from iOS. When non-null and in the future, iOS renders a "Snoozed" banner; it auto-clears when the client sees `snoozed_until ≤ now`. Any client-supplied value is stripped on `PATCH`.
`tiles`	array	Required for the `board` template. 1–4 tile objects. See Board.
`lines`	array	Required for the `log` template. 1–20 line objects, newest first. See Log.
`log_backlog`	array	Read-only (`log` template). Server-kept scroll-back history, returned only on `GET /activities/{slug}?include=log_backlog`. Never sent by clients.

See the Live Activities section for template-specific fields.

Tap actions

Every template accepts up to three optional tap targets on its content:

Field	Where the tap target appears
`tap_action`	The Live Activity background — tapping anywhere outside a button.
`url_action`	The primary button (replaces the legacy `url` string).
`secondary_url_action`	The secondary button (replaces the legacy `secondary_url` string).

All three accept the same Action object:

Field	Type	Description
`url`	string	Required. Max 2,048 chars. Any scheme except `javascript:`, `data:`, `file:`, `vbscript:`. `http(s)` URLs require a host; custom schemes (e.g. `youtube://`, `homeassistant://`) open the matching app on the user's device.
`foreground`	boolean	`http(s)` only. `true` opens the URL in Safari / the in-app browser. `false` (combined with at least one of `method` / `headers` / `body`) fires the request silently from the widget process without launching the app. Ignored for custom schemes.
`method`	string	HTTP method for a silent webhook. One of `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`. Defaults to `GET`. Ignored for custom schemes.
`headers`	object<string,string>	HTTP headers for a silent webhook. ≤1,024 bytes total across keys and values. Ignored for custom schemes.
`body`	string	HTTP request body for a silent webhook. ≤1,024 chars. Ignored for custom schemes.
`title`	string	Button label. Max 64 chars. Only meaningful on `url_action` / `secondary_url_action` — ignored on `tap_action`.
`icon`	string	SF Symbol name (e.g. `checkmark.circle`). Max 64 chars. Only meaningful on `url_action` / `secondary_url_action`.

Dispatch modes

iOS decides what to do with the tap by inspecting the action object:

Custom scheme (e.g. homeassistant://, youtube://) → calls openURL to launch the target app. foreground, method, headers, and body are ignored.
http(s) with foreground: true → opens the URL in Safari / the in-app browser. The app is brought to the foreground.
http(s) with at least one of method / headers / body (and foreground absent or false) → fires the HTTP request silently from the Live Activity widget process. The user's app stays in the background; the request runs inside the widget extension under tight time and memory limits.
Bare {"url":"https://…"} without any HTTP shape → treated like #2 (opens Safari). Without an explicit HTTP shape there is no silent-dispatch intent, so the absent foreground key is interpreted as "open this".

ℹ Info

Silent webhooks are best-effort. They run inside the iOS widget extension under tight time and memory limits. Treat them as fire-and-forget acknowledgements — the device discards the response. For anything that needs reliable delivery or a return value, use foreground: true so your own app or backend handles the work.

Back-compat with string `url` / `secondary_url`

The legacy string fields url and secondary_url on each template are still accepted — older integrations don't need to change. Whenever url_action is set, the server omits the legacy url string from the APNs payload entirely (and likewise for secondary_url vs secondary_url_action) — emitting both blows past the 4 KB APNs cap. Newer iOS clients read the structured action; older clients fall back to the legacy string only when the structured action isn't sent.

Example

A Grafana alert activity that lets the user acknowledge with one tap (silent webhook), open the panel in Safari (foreground), and deep-link into the Grafana iOS app when tapping the background of the Live Activity:

Alert with primary, secondary, and background tap actions

{
  "state": "ongoing",
  "content": {
    "template": "alert",
    "progress": 0.0,
    "state": "CPU usage is 94.2%",
    "icon": "exclamationmark.triangle.fill",
    "subtitle": "Grafana · nas-01",
    "severity": "warning",
    "fired_at": 1750009000,
    "accent_color": "red",
    "tap_action": {
      "url": "grafana://alerts/1afz29v7z"
    },
    "url_action": {
      "url": "https://hooks.example.com/grafana/ack",
      "method": "POST",
      "headers": { "Authorization": "Bearer hooks_xxx" },
      "body": "{\"alert\":\"1afz29v7z\",\"acked\":true}",
      "title": "Acknowledge",
      "icon": "checkmark.circle"
    },
    "secondary_url_action": {
      "url": "https://grafana.example.com/d/abc123?viewPanel=1",
      "foreground": true,
      "title": "Open panel",
      "icon": "chart.bar"
    }
  }
}

Server-Side TTL

Activities support optional server-side time-to-live (TTL) for automatic lifecycle management:

Field	Set On	Behavior
`stale_ttl`	Create / PATCH	If an `ongoing` activity receives no updates for this many seconds, the server auto-ends it
`ended_ttl`	Create / PATCH	When an activity transitions to `ended`, the server schedules auto-deletion after this many seconds and — unless `dismissal_ttl` is set — tells iOS to dismiss the Live Activity from the lock screen at the same moment (capped at the iOS 4-hour limit). Without it, iOS keeps the ended activity on the lock screen for the full 4-hour default.
`dismissal_ttl`	Create / PATCH	Seconds after `ended` before iOS removes the Live Activity from the Lock Screen: `0` = immediately, max `14400` (4h). Overrides the `ended_ttl`-derived dismissal without touching auto-deletion. Ignored when the server preempts an activity to free a Live Activity slot — preempted cards keep the default linger so they stay glanceable.
`delete_at`	Auto	Computed timestamp (read-only). Set automatically from `ended_ttl` when state becomes `ended`
`ended_at`	Auto	Server-stamped timestamp (read-only). Set the first time state transitions to `ended` and preserved across later transitions, so callers can tell when the most recent end happened independently of `updated_at`. `null` until the activity has ended at least once.

ℹ Info

When stale_ttl expires, the server auto-ends the activity with a distinct visual state: it sets content.state to "Stale (auto-ended)", accent_color to #8E8E93 (system gray), and icon to clock.badge.xmark. The activity then transitions to ended and a push-end notification is sent to all subscribed devices. If ended_ttl is also set, the auto-delete timer starts from that point.

The same expiration is sent to iOS as the APNs stale-date, so the Lock Screen presentation is marked stale at the same moment the server auto-ends the activity.

Lock Screen dismissal & linger

When a Live Activity ends, iOS doesn't remove it instantly. It keeps a de-emphasized, dimmed copy on the Lock Screen for a while so the user can still see the final state (the "Done", the final score, the delivered package). How long that ended card lingers is controlled by the APNs dismissal date, which PushWard derives from dismissal_ttl when set, or from ended_ttl otherwise.

This is PushWard's answer to Apple's ActivityUIDismissalPolicy: yes, it's supported — you set it per activity through dismissal_ttl rather than in client code.

dismissal_ttl: 0 — the card disappears from the Lock Screen the moment the activity ends (Apple's .immediate). Works for client-sent ends and server auto-ends (stale_ttl, countdown expiry), and doesn't delete anything server-side.
dismissal_ttl: N (up to 14400) — the card lingers N seconds after ending, independent of when the database row is deleted.
Unset dismissal_ttl, with ended_ttl — legacy coupling: ended_ttl drives both the server-side auto-delete and the on-device dismissal date (capped at 4 hours). The minimum is 1; 0 is rejected with 422.
Neither set — the ended card lingers for the full iOS maximum of 4 hours, then iOS removes it. The database row is kept for 30 days after its last change and then auto-deleted.
Preemption is exempt — when the server evicts an activity to free a Live Activity slot, the preempted card keeps the ended_ttl-derived linger even if dismissal_ttl is 0. A preempted activity can be restarted, so its card stays glanceable.

dismissal_ttl is settable on POST /activities (re-POSTing an existing slug refreshes it) and on PATCH /activities/{slug}, where it follows merge-patch semantics: omit to keep, null to clear, a number to set. Sending it together with the end transition applies it to that end:

End and dismiss immediately

curl -X PATCH https://api.pushward.app/activities/backup \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state": "ended", "dismissal_ttl": 0}'

💡 Tip

Use dismissal_ttl: 0 for activities whose ended state has no glance value — a resolved alert, a finished sync — so the card doesn't sit dimmed on the user's Lock Screen for hours. Keep it unset (or set ended_ttl) when the final state is the payoff: a download that completed, a score, a delivered package. ended_ttl still handles database cleanup either way; an activity that reaches ended without one is deleted 30 days after its last change.

Alarms (iOS 26+ AlarmKit)

Setting content.alarm: true schedules a native iOS alarm at content.end_date using Apple's AlarmKit framework. The alarm rings like a Clock app alarm — breaking through silent mode and Focus — in addition to the Live Activity countdown.

ℹ Info

iOS 26 or later. On older iOS versions the field is silently ignored. The user is prompted to authorize alarms the first time one is scheduled; if denied, the alarm is skipped and the Live Activity still updates normally.

Rules

Opt-in, persists until cleared. Once set, the alarm stays armed across partial updates. Clear it with {"content":{"alarm":null}} in a PATCH body, or by transitioning to ended.
Requires end_date. Sending alarm: true without content.end_date returns 422 Unprocessable Entity.
Updating end_date reschedules the alarm. Send a new PATCH with the new end_date; the armed alarm re-derives automatically.
Past end_date is a no-op. If the push arrives after end_date has already elapsed, no alarm is scheduled (but the Live Activity content still updates).
Designed for the countdown template. Other templates accept the field if they set end_date, but only countdown meaningfully uses it.
What the user sees. When the alarm fires, iOS presents a full-screen alarm using the activity's name as the title with Dismiss and Snooze buttons. Snooze extends end_date by the configured snooze window and sets snoozed_until so the Live Activity shows a "Snoozed" banner. The PushWard Live Activity continues to display alongside.
Configurable snooze window. Set content.snooze_seconds (60–3600) to control how long Snooze extends the timer; it defaults to 300 (5 min) when omitted. iOS reads this value to size its AlarmKit snooze countdown, so a changed value applies to the next scheduled alarm.

⚠ Warning

iOS enforces a small per-app cap on pending AlarmKit alarms. If a user has many concurrent timers with alarm: true, iOS rejects further schedules until one fires or is cancelled — the Live Activity still updates normally in that case.

Start a 25-minute countdown with an alarm on completion

# Arm the alarm
curl -X PATCH https://api.pushward.app/activities/oven-timer \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
    "state": "ongoing",
    "content": {
      "template": "countdown",
      "progress": 0.0,
      "state": "Baking",
      "icon": "flame",
      "duration": "25m",
      "completion_message": "Done baking!",
      "accent_color": "orange",
      "alarm": true
    }
  }'

# Clear the alarm without touching the rest of content
curl -X PATCH https://api.pushward.app/activities/oven-timer \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"content": {"alarm": null}}'

💡 Tip

AlarmKit complements the existing sound field: sound plays once when a push arrives, while alarm rings continuously at end_date until the user dismisses it — even if the device was locked and silent the whole time.

Error Responses

All errors follow RFC 9457 Problem Details and are served with Content-Type: application/problem+json. The same shape is used everywhere on the API — including auth, rate-limit, subscription-gate, and permission-check responses from middleware.

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "Activity limit reached (max 50).",
  "instance": "/activities",
  "code": "activity.limit_exceeded",
  "retry_after_ms": 3000,
  "errors": [
    { "message": "...", "location": "..." }
  ]
}

💡 Tip

Prefer matching on the stable code field over the human-readable detail string — detail messages may be reworded between releases, but code is contract-level. errors is an array of per-field messages, populated for shape-validation failures.

Status Codes

Status	Meaning
`400`	Malformed JSON or wrong shape. Semantic validation now uses `422`.
`401`	Missing or invalid token
`403`	Integration key not allowed for this activity, or insufficient scope
`404`	Activity not found
`409`	Conflict — e.g. activity limit reached or demo cooldown active. Pairs with a `Retry-After` response header and a `retry_after_ms` extension.
`422`	Unprocessable: semantic validation failure (e.g. arming `alarm: true` without `end_date`, or `POST /notifications` referencing an unknown `activity_slug`).
`429`	Two distinct cases — distinguish via the `code` field (`rate_limit.exceeded` or `quota.exceeded`). See the code table below for per-mode contracts and retry semantics.

Known `code` Values

Code	Status	Description
`activity.limit_exceeded`	`409`	Per-user activity cap reached on `POST /activities`.
`demo.conflict`	`409`	Demo flow is on cooldown — retry after `retry_after_ms`.
`subscription.required`	`403`	Endpoint requires an active subscription (granting shares, or redeeming editor-role / pattern share codes).
`permission.free_recipient_limit_exceeded`	`403`	The activity owner already has the maximum number of free recipients. See sharing for the policy.
`permission.editor_requires_paid_recipient`	`403`	Editor access requires the recipient to have an active subscription — returned when granting editor rights to (or upgrading) a free recipient.
`permission.free_share_limit_exceeded`	`403`	The free plan's concurrent shared-activity limit was reached — the recipient must leave another shared activity or upgrade to join more.
`rate_limit.exceeded`	`429`	IP rate limit hit — back off using `Retry-After`.
`quota.exceeded`	`429`	Free-tier monthly quota exhausted. The Problem Details body includes `kind` (`"notifications"`, `"live_activity_updates"`, `"widget_updates"`, or `"emails"`), `used`, `limit`, and `reset_at` (RFC 3339 UTC, the start of next calendar month). The `Retry-After` header gives seconds until `reset_at`. Upgrading the user's plan clears the quota immediately — retrying before `reset_at` on the free tier will keep failing.

Free-Tier Quota Response Example

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 1209600

{
  "type": "about:blank",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Monthly notification quota exceeded for the free tier.",
  "instance": "/notifications",
  "code": "quota.exceeded",
  "kind": "notifications",
  "used": 501,
  "limit": 500,
  "reset_at": "2026-06-01T00:00:00Z"
}

💡 Tip

Pin clients to the code field, not the HTTP status — the same 429 means very different things for rate_limit.exceeded (transient, retry after a few seconds) versus quota.exceeded (sticky until the start of next month, or until the user upgrades). For quota.exceeded, surface an upgrade prompt rather than a blind retry loop.

Activities

Create Activity

Request Body

List Activities

Query Parameters

Get Activity

Delete Activity

Update Activity (Primary Integration Endpoint)

Request Body

Query Parameters

State Transitions

Content Object

Tap actions

Dispatch modes

Back-compat with string url / secondary_url

Example

Server-Side TTL

Lock Screen dismissal & linger

Alarms (iOS 26+ AlarmKit)

Rules

Error Responses

Status Codes

Known code Values

Free-Tier Quota Response Example

Back-compat with string `url` / `secondary_url`

Known `code` Values