Activități

Creează, actualizează și încheie activitățile din spatele fiecărei Activități live cu apeluri REST simple: POST pentru pornire, PATCH pentru actualizare, DELETE pentru încheiere.

Create Activity

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
  }'

{
  "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
}

List Activities

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

{
  "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"
}

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

Get Activity

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

Delete Activity

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

Update Activity (Primary Integration Endpoint)

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"
    }
  }'

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"
    }
  }'

Content Object

Shared fields on content; each template adds its own required fields on top (see Live Activities):

Tap actions

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

All three accept the same Action object:

Dispatch modes

iOS picks a mode from the object's shape:

1. Custom scheme (e.g. homeassistant://, youtube://) → calls openURL to launch the target app. foreground, method, headers, and body are ignored.
2. http(s) with foreground: true → opens the URL in Safari / the in-app browser. The app is brought to the foreground.
3. 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.
4. 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".

Silent-only buttons

The button-bearing templates — media.controls and approval.options — treat an http(s) URL as a silent webhook always: the app stays in the background, the response is discarded, and method defaults to POST. Sending foreground: true there returns 422; a custom-scheme URL opens that app instead.

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:

{
  "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

When stale_ttl expires, the server auto-ends the activity with a distinct visual state — content.state becomes "Stale (auto-ended)", accent_color #8E8E93 (system gray), icon clock.badge.xmark — and sends the push-end to all subscribed devices. The same expiration is sent to iOS as the APNs stale-date, so the Lock Screen presentation is marked stale at the same moment; if ended_ttl is also set, its auto-delete timer starts from that point.

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 the usual merge-patch semantics apply. Sending it together with the end transition applies it to that end:

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}'

Alarms (iOS 26+ AlarmKit)

Setting content.alarm: true schedules a native iOS alarm at content.end_date using Apple's AlarmKit framework (iOS 26 or later; silently ignored on older versions). The alarm rings like a Clock app alarm — breaking through silent mode and Focus — in addition to the Live Activity countdown. 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.

# 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}}'

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": "..." }
  ]
}

Status Codes

Known code Values

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"
}