Live Activities

Start, update, and end real-time Live Activities on your users' devices.

Authentication

All endpoints are authenticated via the X-NativeSuite-Key header using your app's App Secret.

X-NativeSuite-Key: {your-app-secret}

---

Start Live Activity

Start a new Live Activity for one or more users.

Endpoint

POST /api/apps/{appId}/live-activities

Request Body

{
  "templateSlug": "string",
  "attributes": { "key": "value" },
  "contentState": { "key": "value" },
  "targetUsers": ["user-id-1", "user-id-2"]
}

Parameters

Field	Type	Required	Description
templateSlug	string	Yes	Template identifier. One of: status-tracker, metric-live, countdown, progress-bar, two-column, key-value-list, image-banner, mini-table. See Live Activity Templates reference
attributes	object	No	Static data set once at creation. Keys and values must be strings. See template reference
contentState	object	Yes	Dynamic data that can be updated over time. Keys and values must be strings
targetUsers	string[]	No	End user IDs to target. If omitted, starts for all connected users

Example

curl -X POST https://api.nativesuite.io/api/apps/{appId}/live-activities \
  -H "X-NativeSuite-Key: your-app-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "templateSlug": "progress-bar",
    "attributes": {
      "label": "Uploading report.pdf"
    },
    "contentState": {
      "progress": "0",
      "detail": "Starting upload..."
    },
    "targetUsers": ["550e8400-e29b-41d4-a716-446655440000"]
  }'

Response

Success (200):

{
  "activityCount": 1,
  "activities": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "appId": "your-app-id",
      "endUserId": "550e8400-e29b-41d4-a716-446655440000",
      "templateSlug": "progress-bar",
      "state": "Active",
      "platform": "ios",
      "startedAt": "2026-04-19T12:00:00Z"
    }
  ]
}

Save the id from the response — you need it to update or end the activity.

Error (400) — invalid template:

{
  "title": "Bad Request",
  "status": 400,
  "detail": "invalid template slug"
}

Error (403) — feature not available:

{
  "title": "Forbidden",
  "status": 403,
  "detail": "live activities are not available on your current plan"
}

Error (429) — quota exceeded:

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "live activity minutes limit exceeded for this billing period"
}

---

Update Live Activity

Update the dynamic content of a running Live Activity.

Endpoint

PATCH /api/apps/{appId}/live-activities/{id}

Request Body

{
  "contentState": { "key": "value" }
}

Parameters

Field	Type	Required	Description
contentState	object	Yes	Updated dynamic data. Replaces the previous content state entirely

Example

curl -X PATCH https://api.nativesuite.io/api/apps/{appId}/live-activities/{activityId} \
  -H "X-NativeSuite-Key: your-app-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "contentState": {
      "progress": "73",
      "detail": "3.2 MB of 4.4 MB"
    }
  }'

Response

Success (200):

{
  "success": true
}

Error (404) — activity not found:

{
  "title": "Not Found",
  "status": 404,
  "detail": "live activity not found"
}

Error (409) — activity already ended:

{
  "title": "Conflict",
  "status": 409,
  "detail": "live activity is not active"
}

---

End Live Activity

End a running Live Activity. Removes it from the user's device.

Endpoint

DELETE /api/apps/{appId}/live-activities/{id}

Example

curl -X DELETE https://api.nativesuite.io/api/apps/{appId}/live-activities/{activityId} \
  -H "X-NativeSuite-Key: your-app-secret"

Response

Success (200):

{
  "success": true
}

---

List Live Activities

List all Live Activities for an app (both active and ended).

Endpoint

GET /api/apps/{appId}/live-activities

Query Parameters

Field	Type	Default	Description
limit	integer	50	Max results (1-100)
offset	integer	0	Pagination offset

Example

curl https://api.nativesuite.io/api/apps/{appId}/live-activities?limit=10 \
  -H "X-NativeSuite-Key: your-app-secret"

Response

{
  "activities": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "appId": "your-app-id",
      "endUserId": "550e8400-e29b-41d4-a716-446655440000",
      "templateSlug": "progress-bar",
      "state": "Active",
      "platform": "ios",
      "startedAt": "2026-04-19T12:00:00Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "appId": "your-app-id",
      "endUserId": "660e8400-e29b-41d4-a716-446655440000",
      "templateSlug": "status-tracker",
      "state": "Ended",
      "platform": "android",
      "startedAt": "2026-04-19T11:00:00Z",
      "endedAt": "2026-04-19T11:45:00Z"
    }
  ],
  "total": 2
}

---

Notes

• Activities are delivered asynchronously — the start response confirms the activity was created, not that it appeared on the user's device
• On iOS, the activity appears on the Lock Screen and Dynamic Island. On Android, it appears as an ongoing notification
• contentState is replaced entirely on each update — send the full state, not a partial diff
• All values in attributes and contentState must be strings (not numbers or booleans)
• Activities that run longer than 8 hours are automatically ended by iOS on the Dynamic Island (they persist on the Lock Screen for up to 12 hours total)
• If your plan's live activity minutes quota is exceeded, active activities on non-overage plans will be automatically ended