Atividades

Atividades são o recurso central do PushWard. Cada atividade representa um item rastreável que pode ser exibido como uma Live Activity nos dispositivos inscritos.

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,
  "delete_at": null,
  "created_at": "2025-06-15T10:30:00Z",
  "updated_at": "2025-06-15T10:30:00Z",
  "ended_at": null,
  "share_role": null,
  "owner_id": null,
  "owner_nickname": null,
  "share_count": 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,
      "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",
      "share_role": null,
      "owner_id": null,
      "owner_nickname": null,
      "share_count": null
    },
    {
      "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,
      "delete_at": null,
      "created_at": "2025-06-15T10:30:00Z",
      "updated_at": "2025-06-15T11:00:00Z",
      "ended_at": null,
      "share_role": null,
      "owner_id": null,
      "owner_nickname": null,
      "share_count": null
    },
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "kind": "shared",
      "slug": "oven-timer",
      "name": "Oven Timer",
      "state": "ongoing",
      "priority": 0,
      "content": {},
      "ended_ttl": null,
      "stale_ttl": null,
      "delete_at": null,
      "created_at": "2025-06-15T09:00:00Z",
      "updated_at": "2025-06-15T10:00:00Z",
      "ended_at": null,
      "share_role": "viewer",
      "owner_id": "usr_abc123",
      "owner_nickname": "Bob",
      "share_count": 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"
    }
  }'

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

{
  "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,
  "delete_at": null,
  "created_at": "2025-06-15T10:30:00Z",
  "updated_at": "2025-06-15T11:00:00Z",
  "ended_at": null,
  "share_role": null,
  "owner_id": null,
  "owner_nickname": null,
  "share_count": null
}

Content Object

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

See the Live Activities section for template-specific fields.

Tap actions

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

All three accept the same Action object:

Dispatch modes

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

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

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

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

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 ended_ttl.

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

• Default (no ended_ttl) — 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.
• With ended_ttl — the value drives both the server-side auto-delete and the on-device dismissal date. The minimum is 1 (one second, near-instant dismissal); e.g. ended_ttl: 600 lets the card linger ten minutes. 0 is rejected with 422.
• iOS caps the linger at 4 hours — a value larger than 14400 still governs when the database row is deleted, but the Lock Screen card is gone after 4 hours regardless.

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.

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

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